Passer au contenu principal
ClickHouse peut déterminer automatiquement la structure des données d’entrée dans presque tous les formats d’entrée. Ce document explique quand l’inférence de schéma est utilisée, comment elle fonctionne avec différents formats d’entrée et quels paramètres permettent de la contrôler.

​
Utilisation

L’inférence de schéma est utilisée lorsque ClickHouse doit lire des données dans un format spécifique et que la structure est inconnue.

​
Fonctions de table file, s3, url, hdfs, azureBlobStorage.

Ces fonctions de table incluent l’argument facultatif structure, qui définit la structure des données d’entrée. Si cet argument n’est pas spécifié ou s’il est défini sur auto, la structure sera inférée à partir des données. Exemple : Supposons que nous ayons un fichier hobbies.jsonl au format JSONEachRow dans le répertoire user_files, avec le contenu suivant :
ClickHouse peut lire ces données sans que vous ayez à préciser leur structure :
Remarque : le format JSONEachRow a été détecté automatiquement à partir de l’extension de fichier .jsonl. Vous pouvez afficher la structure détectée automatiquement à l’aide de la requête DESCRIBE :

​
Moteurs de table File, S3, URL, HDFS, azureBlobStorage

Si la liste des colonnes n’est pas spécifiée dans la requête CREATE TABLE, la structure de la table sera automatiquement inférée à partir des données. Exemple : Utilisons le fichier hobbies.jsonl. Nous pouvons créer une table avec le moteur File à partir des données de ce fichier :

​
clickhouse-local

clickhouse-local dispose d’un paramètre facultatif -S/--structure permettant de définir la structure des données d’entrée. Si ce paramètre n’est pas renseigné ou s’il est défini sur auto, la structure sera inférée à partir des données. Exemple : Utilisons le fichier hobbies.jsonl. Nous pouvons interroger les données de ce fichier avec clickhouse-local :

​
Utilisation de la structure de la table d’insertion

Lorsque les fonctions de table file/s3/url/hdfs sont utilisées pour insérer des données dans une table, il est possible d’utiliser la structure de la table d’insertion au lieu de l’extraire des données. Cela peut améliorer les performances d’insertion, car l’inférence de schéma peut prendre un certain temps. Cela est également utile lorsque la table possède un schéma optimisé, car aucune conversion de type ne sera alors effectuée. Il existe un paramètre spécial use_structure_from_insertion_table_in_table_functions qui contrôle ce comportement. Il a 3 valeurs possibles :
  • 0 - la fonction de table extraira la structure des données.
  • 1 - la fonction de table utilisera la structure de la table d’insertion.
  • 2 - ClickHouse déterminera automatiquement s’il est possible d’utiliser la structure de la table d’insertion ou de recourir à l’inférence de schéma. Valeur par défaut.
Exemple 1 : Créons la table hobbies1 avec la structure suivante :
Et insérez les données du fichier hobbies.jsonl :
Dans ce cas, toutes les colonnes du fichier sont insérées dans la table sans modification ; ClickHouse utilisera donc la structure de la table d’insertion au lieu de l’inférence de schéma. Exemple 2 : Créons la table hobbies2 avec la structure suivante :
Et insérez les données du fichier hobbies.jsonl :
Dans ce cas, toutes les colonnes de la requête SELECT sont présentes dans la table, donc ClickHouse utilisera la structure de la table d’insertion. Notez que cela ne fonctionne que pour les formats d’entrée qui prennent en charge la lecture d’un sous-ensemble de colonnes, comme JSONEachRow, TSKV, Parquet, etc. (cela ne fonctionne donc pas, par exemple, avec le format TSV). Exemple 3 : Créons la table hobbies3 avec la structure suivante :
Et insérez les données à partir du fichier hobbies.jsonl :
Dans ce cas, la colonne id est utilisée dans la requête SELECT, mais la table ne contient pas cette colonne (elle contient une colonne nommée identifier) ; ClickHouse ne peut donc pas utiliser la structure de la table d’insertion, et l’inférence de schéma sera utilisée. Exemple 4 : Créons la table hobbies4 avec la structure suivante :
Puis insérez des données depuis le fichier hobbies.jsonl :
Dans ce cas, certaines opérations sont appliquées à la colonne hobbies dans la requête SELECT avant son insertion dans la table ; ClickHouse ne peut donc pas utiliser la structure de la table d’insertion, et l’inférence de schéma sera utilisée.

​
Cache d’inférence de schéma

Pour la plupart des formats d’entrée, l’inférence de schéma lit une partie des données pour en déterminer la structure, et ce processus peut prendre un certain temps. Pour éviter de réinférer le même schéma chaque fois que ClickHouse lit les données du même fichier, le schéma inféré est mis en cache et, lors d’un nouvel accès au même fichier, ClickHouse utilise le schéma du cache. Il existe des paramètres spéciaux qui contrôlent ce cache :
  • schema_inference_cache_max_elements_for_{file/s3/hdfs/url/azure} - le nombre maximal de schémas mis en cache pour la fonction de table correspondante. La valeur par défaut est 4096. Ces paramètres doivent être définis dans la configuration du serveur.
  • schema_inference_use_cache_for_{file,s3,hdfs,url,azure} - permet d’activer ou de désactiver l’utilisation du cache pour l’inférence de schéma. Ces paramètres peuvent être utilisés dans les requêtes.
Le schéma du fichier peut être modifié en changeant les données ou les paramètres de format. Pour cette raison, le cache d’inférence de schéma identifie le schéma à partir de la source du fichier, du nom du format, des paramètres de format utilisés et de la date de dernière modification du fichier. Remarque : certains fichiers accessibles par URL dans la fonction de table url peuvent ne pas contenir d’informations sur la date de dernière modification ; dans ce cas, il existe un paramètre spécial schema_inference_cache_require_modification_time_for_url. Désactiver ce paramètre permet d’utiliser le schéma du cache sans date de dernière modification pour ces fichiers. Il existe également une table système schema_inference_cache contenant tous les schémas actuellement présents dans le cache, ainsi que la requête système SYSTEM CLEAR SCHEMA CACHE [FOR File/S3/URL/HDFS] qui permet de vider le cache d’inférence de schéma pour toutes les sources ou pour une source spécifique. Exemples : Essayons d’inférer la structure d’un jeu de données d’exemple depuis S3 github-2022.ndjson.gz et voyons comment fonctionne le cache d’inférence de schéma :
Comme vous pouvez le voir, la seconde requête s’est exécutée presque instantanément. Essayons de modifier certains paramètres qui peuvent affecter le schéma inféré :
Comme vous pouvez le voir, le schéma mis en cache n’a pas été utilisé pour le même fichier, car le paramètre susceptible d’affecter le schéma inféré a été modifié. Vérifions le contenu de la table system.schema_inference_cache :
Comme vous pouvez le constater, il existe deux schémas différents pour le même fichier. Nous pouvons vider le cache des schémas à l’aide d’une requête SYSTEM :

​
Formats textuels

Pour les formats textuels, ClickHouse lit les données ligne par ligne, extrait les valeurs des colonnes selon le format, puis utilise des parseurs récursifs et des heuristiques pour déterminer le type de chaque valeur. Le nombre maximal de lignes et d’octets lus dans les données lors de l’inférence de schéma est contrôlé par les paramètres input_format_max_rows_to_read_for_schema_inference (25000 par défaut) et input_format_max_bytes_to_read_for_schema_inference (32Mb par défaut). Par défaut, tous les types inférés sont Nullable, mais vous pouvez modifier ce comportement en définissant schema_inference_make_columns_nullable (voir des exemples dans la section paramètres).

​
Formats JSON

Dans les formats JSON, ClickHouse analyse les valeurs conformément à la spécification JSON, puis tente de déterminer le type de données le plus approprié pour chacune d’elles. Voyons comment cela fonctionne, quels types peuvent être inférés et quels paramètres spécifiques peuvent être utilisés dans les formats JSON. Exemples Ici et dans la suite, la table function format sera utilisée dans les exemples. Integers, Floats, Bools, Strings :
Dates, DateTimes :
Arrays :
Si un tableau contient null, ClickHouse utilisera les types des autres éléments du tableau :
Si un tableau contient des valeurs de types différents et que le paramètre input_format_json_infer_array_of_dynamic_from_array_of_different_types est activé (activé par défaut), il aura le type Array(Dynamic) :
Tuples nommés : Lorsque le paramètre input_format_json_try_infer_named_tuples_from_objects est activé, ClickHouse tentera, lors de l’inférence de schéma, d’inférer un Tuple nommé à partir d’objets JSON. Le Tuple nommé obtenu contiendra tous les éléments de tous les objets JSON correspondants présents dans les données d’échantillon.
Tuples non nommés : Si le paramètre input_format_json_infer_array_of_dynamic_from_array_of_different_types est désactivé, les Arrays dont les éléments sont de types différents sont traités comme des Tuples non nommés dans les formats JSON.
Si certaines valeurs sont null ou vides, nous utilisons les types des valeurs correspondantes présentes dans les autres lignes :
Maps : En JSON, il est possible de lire des objets dont les valeurs sont du même type que le type Map. Remarque : cela ne fonctionne que lorsque les paramètres input_format_json_read_objects_as_strings et input_format_json_try_infer_named_tuples_from_objects sont désactivés.
Types complexes Nested :
Si ClickHouse ne peut pas déterminer le type d’une clé parce que les données ne contiennent que des valeurs nulles/objets vides/tableaux vides, le type String sera utilisé si le paramètre input_format_json_infer_incomplete_types_as_strings est activé ; sinon, une exception sera levée :

​
Paramètres JSON

input_format_json_try_infer_numbers_from_strings
L’activation de ce paramètre permet de déduire des nombres à partir de valeurs de type chaîne. Ce paramètre est désactivé par défaut. Exemple :
input_format_json_try_infer_named_tuples_from_objects
L’activation de ce paramètre permet d’inférer des tuples nommés à partir d’objets JSON. Le tuple nommé obtenu contiendra tous les éléments de tous les objets JSON correspondants présents dans l’échantillon de données. Cela peut être utile lorsque les données JSON ne sont pas clairsemées, de sorte que l’échantillon de données contienne toutes les clés d’objet possibles. Ce paramètre est activé par défaut. Exemple
Query
Response
Query
Response
input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects
L’activation de ce paramètre permet d’utiliser le type String pour les chemins ambigus lors de l’inférence de tuples nommés à partir d’objets JSON (lorsque input_format_json_try_infer_named_tuples_from_objects est activé), au lieu de lever une exception. Cela permet de lire des objets JSON comme des tuples nommés même en présence de chemins ambigus. Désactivé par défaut. Exemples Avec le paramètre désactivé :
Query
Response
Lorsque ce paramètre est activé :
Query
Response
input_format_json_read_objects_as_strings
L’activation de ce paramètre permet de lire les objets JSON imbriqués sous forme de chaînes. Ce paramètre peut être utilisé pour lire des objets JSON imbriqués sans utiliser le type JSON object. Ce paramètre est activé par défaut. Remarque : l’activation de ce paramètre ne prend effet que si le paramètre input_format_json_try_infer_named_tuples_from_objects est désactivé.
input_format_json_read_numbers_as_strings
L’activation de ce paramètre permet de lire les valeurs numériques sous forme de chaînes. Ce paramètre est activé par défaut. Exemple
input_format_json_read_bools_as_numbers
L’activation de ce paramètre permet de lire les valeurs booléennes comme des nombres. Ce paramètre est activé par défaut. Exemple :
input_format_json_read_bools_as_strings
L’activation de ce paramètre permet de lire les valeurs Bool sous forme de chaînes de caractères. Ce paramètre est activé par défaut. Exemple :
input_format_json_read_arrays_as_strings
L’activation de ce paramètre permet de lire les valeurs des tableaux JSON sous forme de chaînes de caractères. Ce paramètre est activé par défaut. Exemple
input_format_json_infer_incomplete_types_as_strings
L’activation de ce paramètre permet d’utiliser le type String pour les clés JSON qui ne contiennent que Null/{}/[] dans l’échantillon de données lors de l’inférence de schéma. Dans les formats JSON, toute valeur peut être lue comme String si tous les paramètres correspondants sont activés (ils le sont tous par défaut), ce qui permet d’éviter des erreurs comme Cannot determine type for column 'column_name' by first 25000 rows of data, most likely this column contains only Nulls or empty Arrays/Maps lors de l’inférence de schéma en utilisant le type String pour les clés dont le type est inconnu. Exemple :
Query
Response

​
CSV

Dans le format CSV, ClickHouse extrait les valeurs de colonne à partir de la ligne en fonction des délimiteurs. ClickHouse s’attend à ce que tous les types, à l’exception des nombres et des chaînes, soient entourés de guillemets doubles. Si la valeur est entre guillemets doubles, ClickHouse essaie d’analyser le contenu entre guillemets à l’aide du parseur récursif, puis essaie de déterminer le type de données le plus approprié. Si la valeur n’est pas entre guillemets doubles, ClickHouse essaie de l’analyser comme un nombre, et si la valeur n’est pas un nombre, ClickHouse la traite comme une chaîne. Si vous ne voulez pas que ClickHouse essaie de déterminer des types complexes à l’aide de certains parseurs et heuristiques, vous pouvez désactiver le paramètre input_format_csv_use_best_effort_in_schema_inference et ClickHouse traitera alors toutes les colonnes comme des Strings. Si le paramètre input_format_csv_detect_header est activé, ClickHouse essaiera de détecter l’en-tête avec les noms de colonnes (et éventuellement les types) lors de l’inférence du schéma. Ce paramètre est activé par défaut. Exemples : Entiers, Floats, Bools, Strings:
Chaînes sans guillemets :
Dates, DateTimes :
Tableaux :
Si un tableau contient la valeur NULL, ClickHouse utilisera les types des autres éléments du tableau :
Maps :
Nested, tableaux et Maps :
Si ClickHouse ne peut pas déterminer le type entre guillemets parce que les données ne contiennent que des valeurs NULL, ClickHouse le traitera comme String :
Exemple avec le paramètre input_format_csv_use_best_effort_in_schema_inference désactivé :
Exemples de détection automatique de l’en-tête (lorsque input_format_csv_detect_header est activé) : Noms uniquement :
Noms et types :
Notez que l’en-tête ne peut être détecté que s’il existe au moins une colonne d’un type autre que String. Si toutes les colonnes sont de type String, l’en-tête n’est pas détecté :

​
Paramètres CSV

input_format_csv_try_infer_numbers_from_strings
L’activation de ce paramètre permet d’inférer des nombres à partir de valeurs de chaîne de caractères. Ce paramètre est désactivé par défaut. Exemple :

​
TSV/TSKV

Dans les formats TSV/TSKV, ClickHouse extrait la valeur de la colonne à partir de la ligne en fonction des délimiteurs de tabulation, puis analyse la valeur extraite à l’aide du parseur récursif afin de déterminer le type le plus approprié. Si le type ne peut pas être déterminé, ClickHouse traite cette valeur comme String. Si vous ne souhaitez pas que ClickHouse tente de déterminer des types complexes à l’aide de certains parseurs et heuristiques, vous pouvez désactiver le paramètre input_format_tsv_use_best_effort_in_schema_inference et ClickHouse traitera alors toutes les colonnes comme des Strings. Si le paramètre input_format_tsv_detect_header est activé, ClickHouse essaiera de détecter l’en-tête contenant les noms de colonnes (et éventuellement les types) lors de l’inférence du schéma. Ce paramètre est activé par défaut. Exemples : Entiers, Floats, Bools, Strings:
Dates, DateTimes:
tableaux :
Si un tableau contient NULL, ClickHouse utilisera les types des autres éléments du tableau :
Tuples :
Maps :
Nested tableaux, Tuples et Maps :
Si ClickHouse ne peut pas déterminer le type parce que les données ne contiennent que des valeurs NULL, ClickHouse le traitera comme String :
Exemple avec le paramètre input_format_tsv_use_best_effort_in_schema_inference désactivé :
Exemples de détection automatique de l’en-tête (lorsque input_format_tsv_detect_header est activé) : Noms uniquement :
Noms et types :
Notez que l’en-tête ne peut être détecté que s’il existe au moins une colonne d’un type autre que String. Si toutes les colonnes sont de type String, l’en-tête n’est pas détecté :

​
Valeurs

Dans le format Values, ClickHouse extrait la valeur de la colonne depuis la ligne, puis l’analyse à l’aide du parseur récursif, de la même façon que les littéraux sont analysés. Exemples : Integers, Floats, Bools, Strings :
Dates, DateTimes :
Arrays :
Si un tableau contient null, ClickHouse utilisera les types des autres éléments du tableau :
Tuples :
Maps :
Nested Arrays, Tuples et Maps :
Si ClickHouse ne peut pas déterminer le type, car les données ne contiennent que des valeurs NULL, une exception sera levée :
Exemple avec le paramètre input_format_tsv_use_best_effort_in_schema_inference désactivé :

​
CustomSeparated

Dans le format CustomSeparated, ClickHouse extrait d’abord toutes les valeurs des colonnes de la ligne selon les délimiteurs spécifiés, puis tente d’inférer le type de données de chaque valeur en fonction de la règle d’échappement. Si le paramètre input_format_custom_detect_header est activé, ClickHouse essaiera de détecter l’en-tête contenant les noms de colonnes (et éventuellement les types) lors de l’inférence du schéma. Ce paramètre est activé par défaut. Exemple
Exemple de détection automatique de l’en-tête (lorsque input_format_custom_detect_header est activé) :

​
Template

Dans le format Template, ClickHouse extrait d’abord de la ligne les valeurs de toutes les colonnes selon le modèle spécifié, puis essaie d’inférer le type de données de chaque valeur en fonction de sa règle d’échappement. Exemple Supposons que nous ayons un fichier resultset avec le contenu suivant :
Et un fichier row_format avec le contenu suivant :
Nous pouvons ensuite exécuter les requêtes suivantes :

​
Regexp

Comme avec Template, dans le format Regexp, ClickHouse extrait d’abord de la ligne toutes les valeurs des colonnes selon l’expression régulière spécifiée, puis tente d’inférer le type de données de chaque valeur selon la règle d’échappement spécifiée. Exemple

​
Paramètres des formats texte

​
input_format_max_rows_to_read_for_schema_inference/input_format_max_bytes_to_read_for_schema_inference

Ces paramètres contrôlent la quantité de données à lire lors de l’inférence du schéma. Plus le nombre de lignes ou d’octets lus est élevé, plus l’inférence du schéma prend du temps, mais plus les chances de déterminer correctement les types sont élevées (en particulier lorsque les données contiennent beaucoup de valeurs NULL). Valeurs par défaut :
  • 25000 pour input_format_max_rows_to_read_for_schema_inference.
  • 33554432 (32 Mb) pour input_format_max_bytes_to_read_for_schema_inference.

​
column_names_for_schema_inference

La liste des noms de colonnes à utiliser pour l’inférence du schéma dans les formats sans noms de colonnes explicites. Les noms spécifiés seront utilisés à la place des noms par défaut c1,c2,c3,.... Format : column1,column2,column3,.... Exemple

​
schema_inference_hints

La liste des noms et types de colonnes à utiliser pour l’inférence du schéma à la place des types déterminés automatiquement. Format : ‘column_name1 column_type1, column_name2 column_type2, …’. Ce paramètre peut être utilisé pour spécifier les types de colonnes qui n’ont pas pu être déterminés automatiquement ou pour optimiser le schéma. Exemple

​
schema_inference_make_columns_nullable $

Contrôle si les types inférés sont rendus Nullable lors de l’inférence de schéma pour les formats ne contenant pas d’information sur la nullabilité. Valeurs possibles :
  • 0 - le type inféré ne sera jamais Nullable,
  • 1 - tous les types inférés seront Nullable,
  • 2 ou ‘auto’ - pour les formats texte, le type inféré sera Nullable uniquement si la colonne contient NULL dans un échantillon analysé lors de l’inférence du schéma ; pour les formats fortement typés (Parquet, ORC, Arrow), les informations de nullabilité sont extraites des métadonnées du fichier,
  • 3 - pour les formats texte, utilisez Nullable ; pour les formats fortement typés, utilisez les métadonnées du fichier.
Par défaut : 3. Exemples

​
input_format_try_infer_integers

Ce paramètre ne s’applique pas au type de données JSON.
S’il est activé, ClickHouse essaiera d’inférer des entiers plutôt que des nombres à virgule flottante lors de l’inférence du schéma pour les formats texte. Si tous les nombres de la colonne dans les données d’échantillon sont des entiers, le type résultant sera Int64 ; si au moins un nombre est à virgule flottante, le type résultant sera Float64. Si les données d’échantillon ne contiennent que des entiers et qu’au moins l’un d’eux est positif et dépasse Int64, ClickHouse inférera UInt64. Activé par défaut. Exemples

​
input_format_try_infer_datetimes

S’il est activé, ClickHouse essaiera d’inférer le type DateTime ou DateTime64 à partir des champs de type chaîne lors de l’inférence du schéma pour les formats texte. Si tous les champs d’une colonne dans les données d’exemple ont pu être interprétés avec succès comme des valeurs datetime, le type résultant sera DateTime ou DateTime64(9) (si au moins une valeur datetime comportait une partie fractionnaire), si au moins un champ n’a pas pu être interprété comme une valeur datetime, le type résultant sera String. Activé par défaut. Exemples

​
input_format_try_infer_datetimes_only_datetime64

S’il est activé, ClickHouse inférera toujours DateTime64(9) lorsque input_format_try_infer_datetimes est activé, même si les valeurs de date et d’heure ne comportent pas de partie fractionnaire. Désactivé par défaut. Exemples
Remarque : lors de l’inférence du schéma, l’analyse des valeurs DateTime respecte le paramètre date_time_input_format

​
input_format_try_infer_dates

S’il est activé, ClickHouse essaiera d’inférer le type Date à partir des champs de chaîne lors de l’inférence du schéma pour les formats texte. Si tous les champs d’une colonne dans les données d’échantillon ont été correctement interprétés comme des dates, le type résultant sera Date, si au moins un champ n’a pas pu être interprété comme une date, le type résultant sera String. Activé par défaut. Exemples

​
input_format_try_infer_exponent_floats

S’il est activé, ClickHouse essaiera d’inférer les nombres à virgule flottante en notation exponentielle pour les formats texte (sauf JSON, où les nombres en notation exponentielle sont toujours inférés). Désactivé par défaut. Exemple

​
Formats auto-descriptifs

Les formats auto-descriptifs contiennent dans les données elles-mêmes des informations sur leur structure : il peut s’agir d’un en-tête avec une description, d’un arbre binaire de types ou d’une sorte de table. Pour inférer automatiquement un schéma à partir de fichiers dans de tels formats, ClickHouse lit une partie des données contenant des informations sur les types et les convertit en schéma de table ClickHouse.

​
Formats avec le suffixe -WithNamesAndTypes

ClickHouse prend en charge certains formats texte avec le suffixe -WithNamesAndTypes. Ce suffixe signifie que les données contiennent deux lignes supplémentaires indiquant les noms et les types de colonnes avant les données proprement dites. Lors de l’inférence du schéma pour ces formats, ClickHouse lit les deux premières lignes et en extrait les noms et les types de colonnes. Exemple

​
Formats JSON avec métadonnées

Certains formats d’entrée JSON (JSON, JSONCompact, JSONColumnsWithMetadata) contiennent des métadonnées incluant les noms et les types des colonnes. Lors de l’inférence du schéma pour ces formats, ClickHouse lit ces métadonnées. Exemple

​
Avro

Avec le format Avro, ClickHouse lit le schéma à partir des données et le convertit en schéma ClickHouse à l’aide des correspondances de types suivantes : Les autres types Avro ne sont pas pris en charge.

​
Parquet

Dans le format Parquet, ClickHouse lit le schéma à partir des données et le convertit en schéma ClickHouse à l’aide des correspondances de types suivantes : Les autres types Parquet ne sont pas pris en charge.

​
Arrow

Au format Arrow, ClickHouse lit le schéma à partir des données et le convertit en schéma ClickHouse grâce aux correspondances de types suivantes : Les autres types Arrow ne sont pas pris en charge.

​
ORC

Dans le format ORC, ClickHouse lit le schéma à partir des données et le convertit en schéma ClickHouse à l’aide des correspondances de types suivantes : Les autres types ORC ne sont pas pris en charge.

​
Native

Le format Native est utilisé en interne dans ClickHouse et intègre le schéma aux données. Lors de l’inférence de schéma, ClickHouse lit le schéma à partir des données sans aucune transformation.

​
Formats avec schéma externe

Ces formats nécessitent un schéma décrivant les données dans un fichier distinct, rédigé dans un langage de schéma spécifique. Pour inférer automatiquement un schéma à partir de fichiers dans ces formats, ClickHouse lit le schéma externe depuis un fichier distinct et le convertit en schéma de table ClickHouse.

​
Protobuf

Pour l’inférence de schéma au format Protobuf, ClickHouse utilise les correspondances de types suivantes :

​
CapnProto

Pour l’inférence de schéma du format CapnProto, ClickHouse utilise les correspondances de types suivantes :

​
Formats binaires fortement typés

Dans ces formats, chaque valeur sérialisée contient des informations sur son type (et éventuellement sur son nom), mais aucune information n’est fournie sur l’ensemble de la table. Lors de l’inférence de schéma pour ces formats, ClickHouse lit les données ligne par ligne (jusqu’à input_format_max_rows_to_read_for_schema_inference lignes ou input_format_max_bytes_to_read_for_schema_inference octets) et extrait le type (et éventuellement le nom) de chaque valeur à partir des données, puis convertit ces types en types ClickHouse.

​
MsgPack

Dans le format MsgPack, il n’existe pas de délimiteur entre les lignes. Pour utiliser l’inférence de schéma avec ce format, vous devez spécifier le nombre de colonnes de la table à l’aide du paramètre input_format_msgpack_number_of_columns. ClickHouse utilise les correspondances de types suivantes : Par défaut, tous les types inférés sont encapsulés dans Nullable, mais ce comportement peut être modifié à l’aide du paramètre schema_inference_make_columns_nullable.

​
BSONEachRow

Dans BSONEachRow, chaque ligne de données est présentée sous forme de document BSON. Lors de l’inférence de schéma, ClickHouse lit les documents BSON un par un et en extrait les valeurs, les noms et les types, puis convertit ces types en types ClickHouse selon les correspondances de types suivantes : Par défaut, tous les types inférés sont dans Nullable, mais ce comportement peut être modifié à l’aide du paramètre schema_inference_make_columns_nullable.

​
Formats à schéma constant

Les données de ces formats ont toujours le même schéma.

​
LineAsString

Dans ce format, ClickHouse lit toute la ligne des données dans une seule colonne de type String. Le type inféré pour ce format est toujours String et le nom de la colonne est line. Exemple

​
JSONAsString

Dans ce format, ClickHouse lit l’intégralité de l’objet JSON des données dans une seule colonne de type String. Le type inféré pour ce format est toujours String, et le nom de la colonne est json. Exemple

​
JSONAsObject

Dans ce format, ClickHouse lit l’intégralité de l’objet JSON des données dans une seule colonne de type JSON. Pour ce format, le type inféré est toujours JSON et le nom de la colonne est json. Exemple

​
Modes d’inférence de schéma

L’inférence de schéma à partir de l’ensemble des fichiers de données peut fonctionner selon 2 modes distincts : default et union. Le mode est contrôlé par le paramètre schema_inference_mode.

​
Mode par défaut

En mode par défaut, ClickHouse part du principe que tous les fichiers ont le même schéma et essaie de l’inférer en lisant les fichiers un par un jusqu’à ce qu’il y parvienne. Exemple : Supposons que nous ayons 3 fichiers data1.jsonl, data2.jsonl et data3.jsonl avec le contenu suivant : data1.jsonl:
data2.jsonl :
data3.jsonl:
Essayons d’utiliser l’inférence de schéma sur ces 3 fichiers :
Query
Response
Comme on peut le constater, nous n’avons pas field3 du fichier data3.jsonl. Cela s’explique par le fait que ClickHouse a d’abord tenté d’inférer le schéma à partir du fichier data1.jsonl, mais a échoué car le champ field2 ne contenait que des valeurs NULL, puis a tenté d’inférer le schéma à partir de data2.jsonl et a réussi ; les données du fichier data3.jsonl n’ont donc pas été lues.

​
Mode union

En mode union, ClickHouse part du principe que les fichiers peuvent avoir des schémas différents ; il en infère donc les schémas, puis les fusionne en un schéma commun. Supposons que nous ayons 3 fichiers data1.jsonl, data2.jsonl et data3.jsonl avec le contenu suivant : data1.jsonl:
data2.jsonl:
data3.jsonl:
Essayons d’appliquer l’inférence de schéma à ces 3 fichiers :
Query
Response
Comme on peut le voir, nous avons tous les champs de tous les fichiers. Remarque :
  • Comme certains fichiers peuvent ne pas contenir certaines colonnes du schéma résultant, le mode union est pris en charge uniquement pour les formats qui permettent la lecture d’un sous-ensemble de colonnes (comme JSONEachRow, Parquet, TSVWithNames, etc.) et ne fonctionnera pas avec les autres formats (comme CSV, TSV, JSONCompactEachRow, etc.).
  • Si ClickHouse ne parvient pas à inférer le schéma de l’un des fichiers, une exception sera levée.
  • Si vous avez beaucoup de fichiers, la lecture du schéma de chacun d’eux peut prendre beaucoup de temps.

​
Détection automatique du format

Si le format des données n’est pas indiqué et ne peut pas être déterminé à partir de l’extension du fichier, ClickHouse essaiera de détecter le format du fichier à partir de son contenu. Exemples : Supposons que data contienne les éléments suivants :
Nous pouvons examiner et interroger ce fichier sans préciser le format ni la structure :
ClickHouse ne peut détecter qu’un nombre limité de formats, et cette détection prend un certain temps. Il est donc toujours préférable de spécifier explicitement le format.
Dernière modification le 2 juillet 2026