> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentation d’ALTER

# ALTER

La plupart des requêtes `ALTER TABLE` modifient les paramètres ou les données d’une table :

| Modifier                                                                |
| ----------------------------------------------------------------------- |
| [COLUMN](/fr/reference/statements/alter/column)                         |
| [PARTITION](/fr/reference/statements/alter/partition)                   |
| [DELETE](/fr/reference/statements/alter/delete)                         |
| [UPDATE](/fr/reference/statements/alter/update)                         |
| [ORDER BY](/fr/reference/statements/alter/order-by)                     |
| [SAMPLE BY](/fr/reference/statements/alter/sample-by)                   |
| [INDEX](/fr/reference/statements/alter/skipping-index)                  |
| [PROJECTION](/fr/reference/statements/alter/projection)                 |
| [CONSTRAINT](/fr/reference/statements/alter/constraint)                 |
| [TTL](/fr/reference/statements/alter/ttl)                               |
| [STATISTICS](/fr/reference/statements/alter/statistics)                 |
| [SETTING](/fr/reference/statements/alter/setting)                       |
| [APPLY DELETED MASK](/fr/reference/statements/alter/apply-deleted-mask) |
| [APPLY PATCHES](/fr/reference/statements/alter/apply-patches)           |

<Note>
  La plupart des requêtes `ALTER TABLE` ne sont prises en charge que pour les tables [\*MergeTree](/fr/reference/engines/table-engines/mergetree-family/index), [Merge](/fr/reference/engines/table-engines/special/merge) et [Distributed](/fr/reference/engines/table-engines/special/distributed).
</Note>

Ces instructions `ALTER` s’appliquent aux vues :

| Statement                                                           | Description                                                                          |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [ALTER TABLE ... MODIFY QUERY](/fr/reference/statements/alter/view) | Modifie la structure d’une [vue matérialisée](/fr/reference/statements/create/view). |

Ces instructions `ALTER` modifient les entités liées au contrôle d’accès basé sur les rôles :

| Statement                                                           |
| ------------------------------------------------------------------- |
| [USER](/fr/reference/statements/alter/user)                         |
| [ROLE](/fr/reference/statements/alter/role)                         |
| [QUOTA](/fr/reference/statements/alter/quota)                       |
| [ROW POLICY](/fr/reference/statements/alter/row-policy)             |
| [MASKING POLICY](/fr/reference/statements/alter/masking-policy)     |
| [SETTINGS PROFILE](/fr/reference/statements/alter/settings-profile) |

| Statement                                                                            | Description                                                                                                       |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| [ALTER TABLE ... MODIFY COMMENT](/fr/reference/statements/alter/comment)             | Ajoute, modifie ou supprime les commentaires de la table, qu’un commentaire ait déjà été défini ou non.           |
| [ALTER DATABASE ... MODIFY COMMENT](/fr/reference/statements/alter/database-comment) | Ajoute, modifie ou supprime les commentaires de la base de données, qu’un commentaire ait déjà été défini ou non. |
| [ALTER NAMED COLLECTION](/fr/reference/statements/alter/named-collection)            | Modifie les [collections nommées](/fr/concepts/features/configuration/server-config/named-collections).           |

<div id="mutations">
  ## Mutations
</div>

Les requêtes `ALTER` destinées à modifier les données des tables sont mises en œuvre au moyen d’un mécanisme appelé « mutations », notamment [ALTER TABLE ... DELETE](/fr/reference/statements/alter/delete) et [ALTER TABLE ... UPDATE](/fr/reference/statements/alter/update). Il s’agit de processus asynchrones en arrière-plan, similaires aux fusions dans les tables [MergeTree](/fr/reference/engines/table-engines/mergetree-family/index), qui produisent de nouvelles versions « mutées » des parts.

Pour les tables `*MergeTree`, les mutations s’exécutent en **réécrivant des data parts entières**.
Il n’y a pas d’atomicité — les parts sont remplacées par leurs versions mutées dès qu’elles sont prêtes, et une requête `SELECT` dont l’exécution a commencé pendant une mutation verra à la fois des données provenant de parts déjà mutées et de parts qui ne l’ont pas encore été.

Les mutations sont totalement ordonnées selon leur ordre de création et sont appliquées à chaque part dans cet ordre. Les mutations sont également partiellement ordonnées par rapport aux requêtes `INSERT INTO` : les données insérées dans la table avant la soumission de la mutation seront mutées, et celles insérées après ne le seront pas. Notez que les mutations ne bloquent en aucune façon les insertions.

Une requête de mutation renvoie immédiatement après l’ajout de l’entrée de mutation (dans le cas des tables répliquées, dans ZooKeeper ; pour les tables non répliquées, dans le système de fichiers). La mutation elle-même s’exécute de manière asynchrone en utilisant les paramètres du profil système. Pour suivre la progression des mutations, vous pouvez utiliser la table [`system.mutations`](/fr/reference/system-tables/mutations). Une mutation soumise avec succès continuera à s’exécuter même si les serveurs ClickHouse sont redémarrés. Il n’existe aucun moyen de revenir sur une mutation une fois qu’elle a été soumise, mais si elle est bloquée pour une raison quelconque, elle peut être annulée avec la requête [`KILL MUTATION`](/fr/reference/statements/kill#kill-mutation).

Les entrées des mutations terminées ne sont pas supprimées immédiatement (le nombre d’entrées conservées est déterminé par le paramètre du moteur de stockage `finished_mutations_to_keep`). Les entrées de mutation plus anciennes sont supprimées.

<div id="synchronicity-of-alter-queries">
  ## Exécution synchrone des requêtes ALTER
</div>

Pour les tables non répliquées, toutes les requêtes `ALTER` sont exécutées de manière synchrone. Pour les tables répliquées, la requête se contente d'ajouter dans `ZooKeeper` les instructions correspondant aux actions appropriées, et ces actions sont ensuite exécutées dès que possible. Toutefois, la requête peut attendre que ces actions soient terminées sur toutes les répliques.

Pour les requêtes `ALTER` qui créent des mutations (par ex. : `UPDATE`, `DELETE`, `MATERIALIZE INDEX`, `MATERIALIZE PROJECTION`, `MATERIALIZE COLUMN`, `APPLY DELETED MASK`, `APPLY PATCHES`, `CLEAR STATISTIC`, `MATERIALIZE STATISTIC`, entre autres), le caractère synchrone est défini par le paramètre [mutations\_sync](/fr/reference/settings/session-settings/mutations#mutations_sync).

Pour les autres requêtes `ALTER` qui modifient uniquement les métadonnées, vous pouvez utiliser le paramètre [alter\_sync](/fr/reference/settings/session-settings/alter#alter_sync) pour définir l'attente.

Vous pouvez spécifier, avec le paramètre [replication\_wait\_for\_inactive\_replica\_timeout](/fr/reference/settings/session-settings/other#replication_wait_for_inactive_replica_timeout), combien de temps (en secondes) attendre que les répliques inactives exécutent toutes les requêtes `ALTER`.

<Note>
  Pour toutes les requêtes `ALTER`, si `alter_sync = 2` et que certaines répliques restent inactives au-delà de la durée spécifiée par le paramètre `replication_wait_for_inactive_replica_timeout`, une exception `UNFINISHED` est levée.
</Note>

<div id="concurrent-alter-assignment-on-one-table">
  ### Attribution concurrente d’`ALTER` sur une même table
</div>

Sur les tables répliquées, l’envoi rapide de plusieurs instructions `ALTER` distinctes sur une même table peut échouer avec `CANNOT_ASSIGN_ALTER` (code 517). Le chemin de réplication déclenche cette erreur lorsque la réplique n’a pas encore appliqué certains `ALTER` précédents (la version des métadonnées est toujours en retard par rapport aux métadonnées communes — le serveur peut indiquer que la réplique « still not applied some of previous alters » ou « Probably too many alters executing concurrently »). Cette condition peut persister même lorsqu’un `ALTER` précédent a déjà été attribué. Il s’agit d’une condition **générale de concurrence entre `ALTER` de métadonnées et mutations** — elle ne se limite pas aux instructions produisant uniquement des mutations. Des modifications concurrentes ordinaires des métadonnées (`ADD` / `DROP` / `MODIFY` et similaires) peuvent déclencher le même code pouvant donner lieu à un réessai (voir, par exemple, le chemin de réessai couvert par `tests/queries/0_stateless/03518_alter_logical_race.sh`).

Approches permettant d’éviter la condition de concurrence :

* Regroupez les opérations de métadonnées indépendantes dans un **unique** `ALTER` comportant plusieurs clauses lorsque la grammaire le permet (par exemple, plusieurs clauses `ADD INDEX`).
* Sérialisez les instructions `ALTER` et réessayez en cas de code 517 jusqu’à ce que les `ALTER` précédents aient été appliqués sur la réplique.
* Pour les `ALTER` produisant des mutations, attendez la fin de la mutation précédente à l’aide d’un indicateur observable documenté, tel que [`mutations_sync`](/fr/reference/settings/session-settings/mutations#mutations_sync) ou `is_done` dans [`system.mutations`](/fr/reference/system-tables/mutations), avant d’envoyer la suivante.

<div id="combining-materialize-index-clauses">
  ### Combinaison de clauses `MATERIALIZE INDEX`
</div>

Plusieurs clauses `MATERIALIZE INDEX` peuvent figurer dans une même instruction `ALTER`. Le cas couvert dans le code source consiste à regrouper plusieurs clauses `ADD INDEX` et les clauses `MATERIALIZE INDEX` correspondantes pour ces nouveaux index dans une seule instruction (voir `tests/queries/0_stateless/02911_add_index_and_materialize_index.sql`). Cette forme combinant `ADD INDEX` et `MATERIALIZE INDEX` mêle un segment `AlterCommand` à un segment `MutationCommand` ; **`DatabaseReplicated` la rejette donc** avec `QUERY_IS_PROHIBITED` (`InterpreterAlterQuery::validateReplicatedDatabaseSegments`). Considérez l’exemple `02911` comme valide pour les bases de données ordinaires (non-`DatabaseReplicated`) ; avec `DatabaseReplicated`, conservez les modifications de métadonnées et les mutations de matérialisation dans des instructions distinctes.

Dans l’implémentation actuelle, chaque clause `MATERIALIZE INDEX` est résolue par rapport à l’instantané des métadonnées de la table lors de la préparation de la mutation. Les formes à plusieurs clauses qui ne font que matérialiser des index déjà existants suivent donc le même chemin de préparation (mutation uniquement, elles restent donc dans un seul segment). Cette forme précise n’est pas encore couverte par un test stateless ciblé ; considérez-la comme un comportement de l’implémentation actuelle plutôt que comme une garantie distincte tant qu’une telle couverture n’existe pas.

Si vous avez besoin d’appliquer les mutations dans un ordre précis, vous pouvez toujours émettre une instruction `MATERIALIZE INDEX` par instruction et attendre avec [`mutations_sync`](/fr/reference/settings/session-settings/mutations#mutations_sync).

<div id="related-content">
  ## Articles connexes
</div>

* Blog : [Gestion des mises à jour et des suppressions dans ClickHouse](https://clickhouse.com/blog/handling-updates-and-deletes-in-clickhouse)