Skip to main content
Crée une nouvelle table. Par défaut, les tables sont créées uniquement sur le serveur actuel. Les requêtes DDL distribuées utilisent la clause ON CLUSTER, qui est décrite séparément.

Formes de syntaxe

Cette requête peut prendre différentes formes de syntaxe selon le cas d’utilisation.

Créer une table avec un schéma explicite

Crée une table nommée table_name dans la base de données db ou dans la base de données courante si db n’est pas défini, avec la structure spécifiée entre crochets et le moteur engine. La structure de la table est une liste de descriptions de colonnes, d’index secondaires, de projections et de contraintes. Si la clé primaire est prise en charge par le moteur, elle sera indiquée comme paramètre du moteur de table. Dans le cas le plus simple, une description de colonne est de la forme name type. Exemple : RegionID UInt32. Les modificateurs qui suivent le type — COMMENT, compression_codec, STATISTICS, TTL, COLLATE, PRIMARY KEY et SETTINGS par colonne — peuvent être écrits dans n’importe quel ordre, chacun au plus une fois. Par exemple, RegionID UInt32 CODEC(ZSTD) COMMENT 'comment for column' et RegionID UInt32 COMMENT 'comment for column' CODEC(ZSTD) sont identiques. Notez que SHOW CREATE TABLE normalise la déclaration de colonne : les modificateurs qui y restent sont toujours affichés dans l’ordre canonique COMMENT, CODEC, STATISTICS, TTL, COLLATE, SETTINGS, tandis qu’une PRIMARY KEY par colonne est déplacée hors de la déclaration de colonne vers la clause PRIMARY KEY au niveau de la table. Des expressions peuvent également être définies pour les valeurs par défaut (voir ci-dessous). Si nécessaire, la clé primaire peut être spécifiée, avec une ou plusieurs expressions de clé. Des commentaires peuvent être ajoutés aux colonnes et à la table.

Créer une table avec le schéma d’une table existante

ClickHouse permet de copier le schéma et les données d’une table existante. Pour reproduire le schéma d’une table existante : Cela crée une table avec la même structure qu’une autre table.

Créer une table avec le schéma et les données d’une table existante

Pour répliquer le schéma et les données d’une table existante :
Cette instruction crée une table avec le même schéma et les mêmes données qu’une table existante. Une fois la nouvelle table créée, toutes les partitions de db.table lui sont attachées. En d’autres termes, les données de db.table sont clonées dans db2.table_clone lors de sa création. Cette requête est équivalente à ce qui suit :
Pour ces deux fonctionnalités, vous pouvez spécifier un moteur différent pour la table. Si le moteur n’est pas spécifié, le même moteur que pour la table d’origine (db.table) sera utilisé.

Créer une table avec une fonction de table

Crée une table produisant le même résultat que la fonction de table spécifiée. La table créée fonctionnera également de la même manière que la fonction de table correspondante.

Créer une table avec une requête SELECT

Crée une table dont la structure est similaire au résultat de la requête SELECT, avec le moteur engine, et la remplit avec les données issues de SELECT. Vous pouvez également spécifier explicitement la définition des colonnes. Si la table existe déjà et que IF NOT EXISTS est spécifié, la requête n’aura aucun effet. D’autres clauses peuvent apparaître après la clause ENGINE dans la requête. Consultez la documentation détaillée sur la création de tables dans les descriptions des moteurs de table. Exemple
Query
Response

Spécifier les valeurs par défaut des colonnes

La description de colonne peut spécifier une expression de valeur par défaut sous la forme DEFAULT expr, MATERIALIZED expr ou ALIAS expr. Exemple : URLDomain String DEFAULT domain(URL). L’expression expr est facultative. Si elle est omise, le type de colonne doit être indiqué explicitement et la valeur par défaut sera 0 pour les colonnes numériques, '' (la chaîne vide) pour les colonnes de type chaîne, [] (le tableau vide) pour les colonnes de type tableau, 1970-01-01 pour les colonnes de type date, ou NULL pour les colonnes Nullable. Le type de colonne d’une colonne avec valeur par défaut peut être omis ; dans ce cas, il est déduit du type de expr. Par exemple, le type de la colonne EventDate DEFAULT toDate(EventTime) sera Date. Si un type de données et une expression de valeur par défaut sont tous deux spécifiés, une fonction implicite de transtypage est insérée pour convertir l’expression dans le type spécifié. Exemple : Hits UInt32 DEFAULT 0 est représenté en interne sous la forme Hits UInt32 DEFAULT toUInt32(0). Une expression de valeur par défaut expr peut faire référence à des colonnes de table quelconques et à des constantes. ClickHouse vérifie que les modifications de la structure de la table n’introduisent pas de boucles dans le calcul de l’expression. Pour INSERT, il vérifie que les expressions peuvent être résolues, c’est-à-dire que toutes les colonnes à partir desquelles elles peuvent être calculées ont bien été fournies.

DEFAULT

DEFAULT expr Valeur par défaut standard. Si la valeur d’une telle colonne n’est pas spécifiée dans une requête INSERT, elle est calculée à partir de expr. Exemple :

MATERIALIZED

MATERIALIZED expr Expression matérialisée. Les valeurs de ces colonnes sont automatiquement calculées d’après l’expression matérialisée spécifiée lors de l’insertion des lignes. Il n’est pas possible de spécifier explicitement des valeurs lors des INSERT. De plus, les colonnes avec une valeur par défaut de ce type ne sont pas incluses dans le résultat de SELECT *. Cela permet de préserver l’invariant selon lequel le résultat d’un SELECT * peut toujours être réinséré dans la table à l’aide de INSERT. Ce comportement peut être désactivé avec le paramètre asterisk_include_materialized_columns. Exemple :

EPHEMERAL

EPHEMERAL [expr] Colonne éphémère. Les colonnes de ce type ne sont pas stockées dans la table et il n’est pas possible d’effectuer un SELECT dessus. La seule utilité des colonnes éphémères est de servir à construire les expressions de valeur par défaut d’autres colonnes. Un INSERT sans colonnes explicitement spécifiées ignorera les colonnes de ce type. Cela permet de préserver l’invariant selon lequel le résultat d’un SELECT * peut toujours être réinséré dans la table à l’aide de INSERT. Exemple :

ALIAS

ALIAS expr Colonnes calculées (synonyme). Les colonnes de ce type ne sont pas stockées dans la table et il n’est pas possible d’y INSERT des valeurs. Lorsque des requêtes SELECT font explicitement référence à des colonnes de ce type, la valeur est calculée au moment de la requête à partir de expr. Par défaut, SELECT * exclut les colonnes ALIAS. Ce comportement peut être désactivé avec le paramètre asterisk_include_alias_columns. Lorsque vous utilisez la requête ALTER pour ajouter de nouvelles colonnes, les anciennes données de ces colonnes ne sont pas écrites. À la place, lors de la lecture d’anciennes données qui n’ont pas de valeurs pour les nouvelles colonnes, les expressions sont calculées à la volée par défaut. Cependant, si l’évaluation des expressions nécessite d’autres colonnes qui ne sont pas indiquées dans la requête, ces colonnes seront également lues, mais uniquement pour les blocs de données qui en ont besoin. Si vous ajoutez une nouvelle colonne à une table mais modifiez ensuite son expression par défaut, les valeurs utilisées pour les anciennes données changeront (pour les données dont les valeurs n’ont pas été stockées sur le disque). Notez que lors de l’exécution des fusions en arrière-plan, les données des colonnes absentes dans l’une des parties en cours de fusion sont écrites dans la partie fusionnée. Il n’est pas possible de définir des valeurs par défaut pour les éléments des structures de données imbriquées.

Modificateurs NULL ou NOT NULL

Les modificateurs NULL et NOT NULL placés après le type de données dans une définition de colonne permettent ou non que celui-ci soit Nullable. Si le type n’est pas Nullable et que NULL est spécifié, il sera traité comme Nullable ; si NOT NULL est spécifié, ce ne sera pas le cas. Par exemple, INT NULL équivaut à Nullable(INT). Si le type est Nullable et que les modificateurs NULL ou NOT NULL sont spécifiés, une exception sera levée. Voir aussi le paramètre data_type_default_nullable.

Clé primaire

Vous pouvez définir une clé primaire lors de la création d’une table. La clé primaire peut être définie de deux façons :
Dans la liste des colonnes
Hors de la liste des colonnes
Vous ne pouvez pas combiner ces deux méthodes dans une seule requête.

Spécifier les contraintes de table

En plus de la description des colonnes, des contraintes peuvent être définies :

CONSTRAINT

boolean_expr_1 peut être n’importe quelle expression booléenne. Si des contraintes sont définies pour la table, chacune d’elles sera vérifiée pour chaque ligne de la requête INSERT. Si une contrainte n’est pas respectée, le serveur renverra une exception indiquant le nom de la contrainte et l’expression vérifiée. L’ajout d’un grand nombre de contraintes peut nuire aux performances des requêtes INSERT volumineuses. Les contraintes existantes dans toutes les tables peuvent être consultées dans la table system.constraints.

ASSUME

La clause ASSUME est utilisée pour définir une CONSTRAINT sur une table, supposée être vraie. Cette contrainte peut ensuite être utilisée par l’optimiseur pour améliorer les performances des requêtes SQL. Prenez cet exemple où ASSUME CONSTRAINT est utilisé lors de la création de la table users_a :
Ici, ASSUME CONSTRAINT sert à indiquer que la fonction length(name) est toujours égale à la valeur de la colonne name_len. Cela signifie que chaque fois que length(name) est appelée dans une requête, ClickHouse peut la remplacer par name_len, ce qui devrait être plus rapide, car cela évite d’appeler la fonction length(). Ensuite, lors de l’exécution de la requête SELECT name FROM users_a WHERE length(name) < 5;, ClickHouse peut l’optimiser en SELECT name FROM users_a WHERE name_len < 5; grâce à ASSUME CONSTRAINT. La requête peut ainsi s’exécuter plus rapidement, car il n’est plus nécessaire de calculer la longueur de name pour chaque ligne. ASSUME CONSTRAINT ne fait pas respecter la contrainte ; il informe simplement l’optimiseur que la contrainte est supposée vraie. Si la contrainte n’est pas réellement vraie, les résultats des requêtes peuvent être incorrects. Par conséquent, vous ne devez utiliser ASSUME CONSTRAINT que si vous êtes sûr que la contrainte est vraie.

Définir la durée de conservation avec TTL

Définit la durée de conservation des valeurs. Ne peut être spécifiée que pour les tables de la famille MergeTree. Pour une description détaillée, consultez TTL pour les colonnes et les tables.

Sélectionner les codecs de compression des colonnes

Par défaut, ClickHouse utilise la compression lz4 dans la version autogérée et zstd dans ClickHouse Cloud. Vous pouvez également définir la méthode de compression pour chaque colonne dans la requête CREATE TABLE :
Pour découvrir les codecs de compression à usage général, spécialisés et de chiffrement disponibles, consultez Codecs de compression des colonnes.

Créer des tables temporaires

ClickHouse prend en charge les tables temporaires, qui disparaissent à la fin de la session. Pour en savoir plus, consultez CREATE TEMPORARY TABLE.

Mettre à jour une table de façon atomique avec REPLACE TABLE

L’instruction REPLACE vous permet de mettre à jour une table de façon atomique. Pour plus de détails, consultez REPLACE TABLE.

Ajouter un commentaire à une table

Vous pouvez ajouter un commentaire à une table lors de sa création. Syntaxe
La clause COMMENT doit être spécifiée après toute clause propre au stockage, telle que PARTITION BY, ORDER BY et les SETTINGS propres au stockage.Après la clause COMMENT, seuls les SETTINGS propres aux requêtes (comme max_threads, etc.) seront analysés, et non les paramètres liés au stockage.Cela signifie que l’ordre correct des clauses est le suivant :
  • ENGINE
  • clauses de stockage
  • COMMENT
  • paramètres de requête (le cas échéant)
Exemple
Query
Response
Dernière modification le 14 août 2026