HiveText

HiveText lit et écrit le format de sérialisation texte utilisé par les tables Apache Hive (format produit par le LazySimpleSerDe de Hive). Il s'agit d'un format texte délimité, semblable à CSV, dans lequel les champs sont séparés par le délimiteur Hive par défaut \x01 (Ctrl-A). Le délimiteur de champ est configurable via input_format_hive_text_fields_delimiter.

Lorsqu'il est utilisé comme format d'entrée, les données n'ont pas de ligne d'en-tête : les valeurs sont associées aux colonnes de la table de destination selon leur position, de sorte que les noms et les types des colonnes sont repris de la table (ou d'une structure explicitement fournie) plutôt qu'inférés à partir des données. Lors de la lecture, ClickHouse analyse les dates et heures en mode best-effort (voir date_time_input_format), complète les champs de fin omis avec les valeurs par défaut des colonnes et ignore les champs qu'il ne reconnaît pas.

Dans un champ, les valeurs sont analysées à l'aide des mêmes règles d'échappement que CSV, plutôt que des délimiteurs imbriqués de Hive. En particulier, une colonne de type Array est lue à partir de la représentation entre crochets (par exemple, "['a','b','c']"), et non à partir de valeurs séparées par le délimiteur de collection Hive \x02.

Par défaut, les lignes peuvent contenir un nombre variable de champs (voir input_format_hive_text_allow_variable_number_of_columns) : pour les lignes comportant moins de champs que la table, les colonnes manquantes sont remplies avec des valeurs par défaut, et pour les lignes comportant des champs supplémentaires en fin de ligne, ces champs sont ignorés.

Les exemples ci-dessous remplacent le délimiteur de champ par défaut par une virgule (,) à l’aide de input_format_hive_text_fields_delimiter, afin de rendre les fichiers d’entrée plus faciles à lire.

Soit un fichier hive_data.txt avec des champs séparés par des virgules :

1,3
3,5,9

Nous créons une table qui définit les noms et les types des colonnes, puis nous y insérons le fichier avec FORMAT HiveText :

CREATE TABLE test_tbl (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_tbl FROM INFILE 'hive_data.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_tbl;

┌─a─┬─b─┬─c─┐
│ 1 │ 3 │ 0 │
│ 3 │ 5 │ 9 │
└───┴───┴───┘

Notez que la première ligne, 1,3, ne contient que deux champs ; la colonne manquante c est donc renseignée avec sa valeur par défaut 0.

Avec la valeur par défaut input_format_hive_text_allow_variable_number_of_columns = 1, les lignes qui comportent plus de champs que la table n’a de colonnes voient simplement les champs supplémentaires en fin de ligne ignorés :

1,2,3,4,5
6,7,8

CREATE TABLE test_extras (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_extras FROM INFILE 'hive_extras.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_extras ORDER BY a;

┌─a─┬─b─┬─c─┐
│ 1 │ 2 │ 3 │
│ 6 │ 7 │ 8 │
└───┴───┴───┘

Définir input_format_hive_text_allow_variable_number_of_columns = 0 à la place impose un nombre strict de champs, et une ligne comportant moins de champs que la table déclenche une exception d’analyse.

Lorsqu'il est utilisé comme format de sortie, HiveText écrit chaque ligne sans guillemets : les champs de niveau supérieur sont séparés par le délimiteur de champs (\x01 par défaut) et les lignes sont séparées par le délimiteur de lignes (\n par défaut, configurable via format_hive_text_rows_delimiter). Les valeurs des types imbriqués (Array, Map et Tuple) sont écrites sans crochets et séparées par le séparateur Hive correspondant à leur niveau d'imbrication, comme le fait LazySimpleSerDe de Hive. Les trois premiers séparateurs sont le délimiteur de champs configurable, input_format_hive_text_collection_items_delimiter (\x02 par défaut, utilisé pour les éléments de tableau, les entrées de map et les éléments de tuple) et input_format_hive_text_map_keys_delimiter (\x03 par défaut, utilisé entre une clé de map et sa valeur) ; les niveaux plus profonds utilisent par défaut des caractères de contrôle consécutifs (\x04, \x05, et ainsi de suite, jusqu'à huit niveaux). Un arbre de types imbriqué assez profondément pour nécessiter un séparateur au-delà de ces huit niveaux est rejeté avec une exception NOT_IMPLEMENTED, car le LazySimpleSerDe de Hive ne dispose pas non plus de séparateur pour ce cas. Les types de données qui n'ont pas de représentation textuelle naturelle dans Hive ne sont pas pris en charge en sortie et génèrent une exception NOT_IMPLEMENTED. Cela inclut AggregateFunction, Dynamic, Variant, LowCardinality et Object, ainsi que les types à représentation numérique Enum, Time, Time64 et Interval — Hive ne dispose d'aucun type correspondant pour ces derniers, qui sont donc rejetés plutôt que d'être écrits sous forme de leurs valeurs numériques sous-jacentes brutes. Les types numériques de grande taille Int128, UInt128, Int256 et UInt256 sont rejetés pour la même raison : le plus grand entier pris en charge par Hive est BIGINT (64 bits), et même DECIMAL de Hive, avec sa précision maximale de 38, ne peut pas couvrir leur plage de valeurs. De même, les valeurs Decimal dont la précision est supérieure à 38 (c'est-à-dire Decimal256) dépassent la précision maximale de DECIMAL dans Hive et sont rejetées. De même, les clés de Map doivent être d'un type primitif : Hive déclare les maps sous la forme MAP<primitive_type, data_type> ; par conséquent, une Map dont le type de clé est un Array, une Map ou un Tuple (ce que ClickHouse autorise) est rejetée avec une exception NOT_IMPLEMENTED, car aucun schéma Hive ne pourrait relire de telles valeurs. Le littéral de map vide map() est rejeté pour la même raison : son type est Map(Nothing, Nothing), et Nothing n'est pas un type qu'une déclaration Hive MAP<key_type, data_type> pourrait désigner. Toutes ces vérifications sont appliquées dès le départ aux types de colonnes déclarés, avant l'écriture de toute ligne : une requête dont l'en-tête contient un type non pris en charge à n'importe quel endroit de son arbre de types est rejetée, même lorsque les valeurs réelles n'atteindraient jamais la sérialisation non prise en charge (par exemple, un Nullable d'un type non pris en charge ne contenant que des valeurs NULL, ou un Array/Map vide dont le type d'élément n'est pas pris en charge), car le schéma déclaré du fichier ne pourrait toujours correspondre à aucune table Hive.

Date, Date32, DateTime et DateTime64 sont toujours écrits au format texte simple de date et d'horodatage de Hive (yyyy-MM-dd et yyyy-MM-dd HH:mm:ss[.fffffffff]), indépendamment du paramètre date_time_output_format, afin que la sortie reste analysable par Hive même lorsque ce paramètre vaut unix_timestamp ou iso.

Pour la même raison, les valeurs Bool sont toujours écrites sous la forme true/false, indépendamment des paramètres bool_true_representation et bool_false_representation, et les valeurs NULL sont toujours écrites sous la forme de la séquence nulle par défaut de Hive \N, indépendamment du paramètre format_csv_null_representation. Cela garantit que la sortie reste lisible par le LazySimpleSerDe de Hive, quels que soient ces paramètres de texte génériques. De même, le format d'entrée HiveText interprète toujours \N comme NULL, indépendamment du paramètre format_csv_null_representation, afin que l'aller-retour des valeurs scalaires de niveau supérieur n'en dépende pas.

Les valeurs non finies Float32 et Float64 sont écrites avec les graphies Java de Hive NaN, Infinity et -Infinity, plutôt qu’avec les jetons habituels de ClickHouse nan/inf/-inf, afin que l’analyseur FLOAT/DOUBLE de Hive les relise en tant que mêmes valeurs plutôt que comme NULL.

SELECT '20240305', tuple(123567, 'e01001', map('action1', 33333, 'act2', 5555)) FORMAT HiveText;