Passer au contenu principal
Ensemble de requêtes permettant de modifier la structure de la table. Syntaxe : 
ALTER [TEMPORARY] TABLE [db].name [ON CLUSTER cluster] ADD|DROP|RENAME|CLEAR|COMMENT|{MODIFY|ALTER}|MATERIALIZE COLUMN ...
Dans la requête, indiquez une liste d’une ou plusieurs actions séparées par des virgules. Chaque action correspond à une opération sur une colonne. Les actions suivantes sont prises en charge :

​
ADD COLUMN

ADD COLUMN [IF NOT EXISTS] name [type] [default_expr] [codec] [AFTER name_after | FIRST]
Ajoute une nouvelle colonne à la table avec les name, type, codec et default_expr spécifiés (voir la section Expressions par défaut). Si la clause IF NOT EXISTS est incluse, la requête ne renvoie pas d’erreur si la colonne existe déjà. Si vous spécifiez AFTER name_after (le nom d’une autre colonne), la colonne est ajoutée après celle-ci dans la liste des colonnes de la table. Si vous voulez ajouter une colonne au début de la table, utilisez la clause FIRST. Sinon, la colonne est ajoutée à la fin de la table. Dans une chaîne d’actions, name_after peut être le nom d’une colonne ajoutée dans l’une des actions précédentes. L’ajout d’une colonne modifie uniquement la structure de la table, sans effectuer d’opération sur les données. Les données n’apparaissent pas sur le disque après ALTER. Si les données d’une colonne sont absentes lors de la lecture de la table, elles sont complétées par des valeurs par défaut (en évaluant l’expression par défaut s’il y en a une, ou en utilisant des zéros ou des chaînes vides). La colonne apparaît sur le disque après la fusion des parts de données (voir MergeTree). Cette approche permet d’exécuter la requête ALTER instantanément, sans augmenter le volume des anciennes données. Exemple : 
ALTER TABLE alter_test ADD COLUMN Added1 UInt32 FIRST;
ALTER TABLE alter_test ADD COLUMN Added2 UInt32 AFTER NestedColumn;
ALTER TABLE alter_test ADD COLUMN Added3 UInt32 AFTER ToDrop;
DESC alter_test FORMAT TSV;

Added1  UInt32
CounterID       UInt32
StartDate       Date
UserID  UInt32
VisitID UInt32
NestedColumn.A  Array(UInt8)
NestedColumn.S  Array(String)
Added2  UInt32
ToDrop  UInt32
Added3  UInt32

​
DROP COLUMN

DROP COLUMN [IF EXISTS] name
Supprime la colonne nommée name. Si la clause IF EXISTS est spécifiée, la requête ne renverra pas d’erreur si la colonne n’existe pas. Supprime les données du système de fichiers. Comme l’opération supprime des fichiers entiers, la requête est exécutée presque instantanément.
Vous ne pouvez pas supprimer une colonne si elle est référencée par une vue matérialisée. Sinon, une erreur est renvoyée.
Exemple : 
ALTER TABLE visits DROP COLUMN browser

​
RENAME COLUMN

RENAME COLUMN [IF EXISTS] name to new_name
Renomme la colonne name en new_name. Si la clause IF EXISTS est spécifiée, la requête ne renvoie pas d’erreur si la colonne n’existe pas. Comme le renommage n’affecte pas les données sous-jacentes, la requête s’exécute presque instantanément. NOTE : Les colonnes spécifiées dans l’expression de clé de la table (via ORDER BY ou PRIMARY KEY) ne peuvent pas être renommées. Toute tentative de modifier ces colonnes entraînera SQL Error [524]. Exemple : 
ALTER TABLE visits RENAME COLUMN webBrowser TO browser

​
CLEAR COLUMN

CLEAR COLUMN [IF EXISTS] name IN PARTITION partition_name
Réinitialise toutes les données d’une colonne pour une partition donnée. Pour en savoir plus sur la manière de définir le nom de la partition, consultez la section Comment définir l’expression de partition. Si la clause IF EXISTS est spécifiée, la requête ne renverra pas d’erreur si la colonne n’existe pas. Exemple : 
ALTER TABLE visits CLEAR COLUMN browser IN PARTITION tuple()

​
COMMENT COLUMN

COMMENT COLUMN [IF EXISTS] name 'Text comment'
Ajoute un commentaire à la colonne. Si la clause IF EXISTS est spécifiée, la requête ne renverra pas d’erreur si la colonne n’existe pas. Chaque colonne peut avoir un commentaire. Si un commentaire existe déjà pour la colonne, un nouveau commentaire remplace le précédent. Les commentaires sont stockés dans la colonne comment_expression renvoyée par la requête DESCRIBE TABLE. Exemple : 
ALTER TABLE visits COMMENT COLUMN browser 'This column shows the browser used for accessing the site.'

​
MODIFY COLUMN

MODIFY COLUMN [IF EXISTS] name
    [type] [default_expr] [codec] [TTL] [settings] [AFTER name_after | FIRST]
    | ADD ENUM VALUES ( 'name' [= number] [, ...] )
ALTER COLUMN [IF EXISTS] name
    TYPE [type] [default_expr] [codec] [TTL] [settings] [AFTER name_after | FIRST]
    | ADD ENUM VALUES ( 'name' [= number] [, ...] )
Cette requête modifie les propriétés de la colonne name :
  • Type
  • Expression par défaut
  • Codec de compression
  • TTL
  • Paramètres au niveau des colonnes
  • Valeurs d’énumération pour les types Enum/Enum8/Enum16
Pour des exemples de modification des CODECS de compression des colonnes, consultez Codecs de compression des colonnes. Pour des exemples de modification du TTL des colonnes, consultez TTL des colonnes. Pour des exemples de modification des paramètres au niveau des colonnes, consultez Paramètres au niveau des colonnes. Si la clause IF EXISTS est spécifiée, la requête ne renverra pas d’erreur si la colonne n’existe pas. Lors de la modification du type, les valeurs sont converties comme si les fonctions toType leur étaient appliquées. Si seule l’expression par défaut est modifiée, la requête n’effectue aucune opération complexe et se termine presque instantanément. Exemple : 
ALTER TABLE visits MODIFY COLUMN browser Array(String)
La modification du type de colonne est la seule opération complexe : elle modifie le contenu des fichiers de données. Pour les grandes tables, cela peut prendre beaucoup de temps. La requête peut également modifier l’ordre des colonnes à l’aide de la clause FIRST | AFTER ; voir la description de ADD COLUMN, mais le type de colonne est obligatoire dans ce cas. Exemple : 
CREATE TABLE users (
    c1 Int16,
    c2 String
) ENGINE = MergeTree
ORDER BY c1;

DESCRIBE users;
┌─name─┬─type───┬
│ c1   │ Int16  │
│ c2   │ String │
└──────┴────────┴

ALTER TABLE users MODIFY COLUMN c2 String FIRST;

DESCRIBE users;
┌─name─┬─type───┬
│ c2   │ String │
│ c1   │ Int16  │
└──────┴────────┴

ALTER TABLE users ALTER COLUMN c2 TYPE String AFTER c1;

DESCRIBE users;
┌─name─┬─type───┬
│ c1   │ Int16  │
│ c2   │ String │
└──────┴────────┴
La requête ALTER est atomique. Pour les tables MergeTree, elle est également sans verrouillage. La requête ALTER de modification de colonnes est répliquée. Les instructions sont enregistrées dans ZooKeeper, puis chaque réplique les applique. Toutes les requêtes ALTER sont exécutées dans le même ordre. La requête attend que les opérations correspondantes soient terminées sur les autres répliques. Cependant, une requête de modification de colonnes dans une table répliquée peut être interrompue, et toutes les opérations seront effectuées de manière asynchrone.
Soyez prudent lorsque vous modifiez une colonne Nullable en Non-Nullable. Assurez-vous qu’elle ne contient aucune valeur NULL, sinon cela provoquera des problèmes à la lecture. Dans ce cas, la solution de contournement consiste à lancer Kill sur la mutation et à remettre la colonne en type Nullable.

​
MODIFY COLUMN REMOVE

Supprime l’une des propriétés de la colonne : DEFAULT, ALIAS, MATERIALIZED, CODEC, COMMENT, TTL, SETTINGS. Syntaxe : 
ALTER TABLE table_name MODIFY COLUMN column_name REMOVE property;
Exemple Supprimer le TTL : 
ALTER TABLE table_with_ttl MODIFY COLUMN column_ttl REMOVE TTL;
Voir aussi

​
MODIFY COLUMN MODIFY SETTING

Modifie le paramètre d’une colonne. Syntaxe : 
ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING name=value,...;
Exemple Modifiez le paramètre max_compress_block_size de la colonne pour le définir à 1MB : 
ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING max_compress_block_size = 1048576;

​
MODIFY COLUMN RESET SETTING

Réinitialise un paramètre de colonne et supprime également la déclaration de ce paramètre dans l’expression de colonne de la requête CREATE de la table. Syntaxe : 
ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING name,...;
Exemple Réinitialiser le paramètre de colonne max_compress_block_size à sa valeur par défaut : 
ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING max_compress_block_size;

​
MODIFY COLUMN ADD ENUM VALUES

Ajoute de nouvelles valeurs à une colonne de type Enum, Enum8, Enum16, Nullable(Enum), Nullable(Enum8) ou Nullable(Enum16) Syntaxe : 
ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('EnumName' [= number], ...);
Exemple Ajoutez deux valeurs à la colonne enum_column_name : 
ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('Hundred' = 100, 'HundredOne');

​
MATERIALIZE COLUMN

Matérialise une colonne avec une expression DEFAULT ou MATERIALIZED. Lors de l’ajout d’une colonne matérialisée à l’aide de ALTER TABLE table_name ADD COLUMN column_name MATERIALIZED, les lignes existantes sans valeur matérialisée ne sont pas remplies automatiquement. L’instruction MATERIALIZE COLUMN peut être utilisée pour réécrire les données de colonne existantes après l’ajout ou la mise à jour d’une expression DEFAULT ou MATERIALIZED (ce qui met uniquement à jour les métadonnées, sans modifier les données existantes). Notez que matérialiser une colonne dans la clé de tri est une opération non valide, car cela pourrait rompre l’ordre de tri. Implémentée sous forme de mutation. Pour les colonnes avec une expression MATERIALIZED nouvelle ou mise à jour, toutes les lignes existantes sont réécrites. Pour les colonnes avec une expression DEFAULT nouvelle ou mise à jour, le comportement dépend de la version de ClickHouse :
  • Dans ClickHouse < v24.2, toutes les lignes existantes sont réécrites.
  • ClickHouse >= v24.2 distingue si la valeur d’une ligne dans une colonne avec une expression DEFAULT a été explicitement spécifiée lors de l’insertion ou non, c.-à-d. si elle a été calculée à partir de l’expression DEFAULT. Si la valeur a été explicitement spécifiée, ClickHouse la conserve telle quelle. Si la valeur a été calculée, ClickHouse la remplace par la nouvelle expression MATERIALIZED ou par sa version mise à jour.
Syntaxe : 
ALTER TABLE [db.]table [ON CLUSTER cluster] MATERIALIZE COLUMN col [IN PARTITION partition | IN PARTITION ID 'partition_id'];
  • Si vous spécifiez une PARTITION, une colonne sera matérialisée uniquement pour la partition spécifiée.
Exemple 
DROP TABLE IF EXISTS tmp;
SET mutations_sync = 2;
CREATE TABLE tmp (x Int64) ENGINE = MergeTree() ORDER BY tuple() PARTITION BY tuple();
INSERT INTO tmp SELECT * FROM system.numbers LIMIT 5;
ALTER TABLE tmp ADD COLUMN s String MATERIALIZED toString(x);

ALTER TABLE tmp MATERIALIZE COLUMN s;

SELECT groupArray(x), groupArray(s) FROM (select x,s from tmp order by x);

┌─groupArray(x)─┬─groupArray(s)─────────┐
│ [0,1,2,3,4]   │ ['0','1','2','3','4'] │
└───────────────┴───────────────────────┘

ALTER TABLE tmp MODIFY COLUMN s String MATERIALIZED toString(round(100/x));

INSERT INTO tmp SELECT * FROM system.numbers LIMIT 5,5;

SELECT groupArray(x), groupArray(s) FROM tmp;

┌─groupArray(x)─────────┬─groupArray(s)──────────────────────────────────┐
│ [0,1,2,3,4,5,6,7,8,9] │ ['0','1','2','3','4','20','17','14','12','11'] │
└───────────────────────┴────────────────────────────────────────────────┘

ALTER TABLE tmp MATERIALIZE COLUMN s;

SELECT groupArray(x), groupArray(s) FROM tmp;

┌─groupArray(x)─────────┬─groupArray(s)─────────────────────────────────────────┐
│ [0,1,2,3,4,5,6,7,8,9] │ ['inf','100','50','33','25','20','17','14','12','11'] │
└───────────────────────┴───────────────────────────────────────────────────────┘
Voir aussi

​
Limitations

La requête ALTER vous permet de créer et de supprimer des éléments distincts (colonnes) dans des structures de données imbriquées, mais pas des structures de données imbriquées complètes. Pour ajouter une structure de données imbriquée, vous pouvez ajouter des colonnes portant un nom tel que name.nested_name et de type Array(T). Une structure de données imbriquée équivaut à plusieurs colonnes Array dont le nom partage le même préfixe avant le point. Le renommage de colonnes contenant des points dans leur nom est partiellement pris en charge. Les points sont réservés à l’accès aux sous-colonnes Nested, le préfixe (nom parent) doit donc rester inchangé. Seul le suffixe (nom de la sous-colonne) peut être modifié. Par exemple, a.b peut être renommé en a.c, mais renommer a.b en b.d n’est pas autorisé, car cela modifie le préfixe parent de Nested. La suppression de colonnes dans la clé primaire ou la clé d’échantillonnage (colonnes utilisées dans l’expression ENGINE) n’est pas prise en charge. La modification du type des colonnes incluses dans la clé primaire n’est possible que si elle n’entraîne pas de modification des données (par exemple, vous pouvez ajouter des valeurs à un Enum ou remplacer un type DateTime par UInt32). Si la requête ALTER ne suffit pas à effectuer les modifications de table dont vous avez besoin, vous pouvez créer une nouvelle table, y copier les données à l’aide de la requête INSERT SELECT, puis permuter les tables à l’aide de la requête RENAME et supprimer l’ancienne table. La requête ALTER bloque toutes les lectures et écritures sur la table. En d’autres termes, si un SELECT long est en cours d’exécution au moment de la requête ALTER, la requête ALTER attendra qu’il se termine. En parallèle, toutes les nouvelles requêtes sur la même table attendront pendant l’exécution de cet ALTER. Pour les tables qui ne stockent pas elles-mêmes de données (comme Merge et Distributed), ALTER modifie uniquement la structure de la table et ne modifie pas celle des tables sous-jacentes. Par exemple, lorsque vous exécutez ALTER sur une table Distributed, vous devez également exécuter ALTER sur les tables de tous les serveurs distants.
Dernière modification le 25 juin 2026