HiveText

Documentation sur le format HiveText

Entrée	Sortie	Alias
✔	✔

​

Description

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.

Les paramètres de délimiteurs imbriqués n’ont aucun effet sur l’entrée

Les paramètres input_format_hive_text_collection_items_delimiter et input_format_hive_text_map_keys_delimiter sont acceptés pour des raisons de compatibilité, mais ne sont actuellement pas utilisés lors de l’analyse. Ils sont toutefois utilisés lors de l’écriture de valeurs imbriquées en sortie.

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.

​

Exemple d’utilisation

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.

​

Lecture d’un fichier HiveText

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

hive_data.txt

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 :

Query

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;

Response

┌─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.

​

Nombre variable de colonnes

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 :

hive_extras.txt

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

Query

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;

Response

┌─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.

​

Sortie

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.

Sortie compatible avec Hive, mais pas d’aller-retour complet via le format d’entrée

La sortie cible le LazySimpleSerDe par défaut de Hive et n’est pas symétrique avec l’entrée HiveText de ClickHouse :

• Les valeurs Array, Map et Tuple imbriquées sont écrites avec les séparateurs imbriqués de Hive (sans crochets), mais le format d’entrée analyse chaque champ selon les règles CSV/avec crochets et ignore input_format_hive_text_collection_items_delimiter / input_format_hive_text_map_keys_delimiter. Ainsi, une sortie imbriquée telle que SELECT [1, 2] FORMAT HiveText n’est pas relue par INSERT ... FORMAT HiveText — seuls les champs scalaires de niveau supérieur peuvent effectuer un aller-retour, et uniquement avec le délimiteur de ligne \n par défaut (voir le point suivant).
• L’aller-retour exige également le délimiteur de ligne \n par défaut. Lorsque format_hive_text_rows_delimiter est modifié, la sortie sépare les lignes avec l’octet configuré, mais le format d’entrée reste le CSVRowInputFormat basé sur les sauts de ligne et il n’existe aucun input_format_hive_text_rows_delimiter correspondant. Ainsi, une sortie scalaire sur plusieurs lignes telle que SELECT number FROM numbers(3) FORMAT HiveText SETTINGS format_hive_text_rows_delimiter=';' (qui produit 0;1;2;) n’est pas relue par INSERT ... FORMAT HiveText sous forme de trois lignes.
• Seul le sous-ensemble LazySimpleSerDe par défaut, sans échappement, est implémenté. Les champs sont écrits sans échappement (il n’existe aucun équivalent de l’option Hive ROW FORMAT DELIMITED ... ESCAPED BY), et NULL est toujours écrit sous la forme \N (il n’existe aucun équivalent de NULL DEFINED AS). Une String qui contient elle-même un séparateur actif de champ, de ligne ou imbriqué est donc écrite littéralement et sera mal interprétée lors de la réanalyse — ce qui correspond au comportement de Hive avec une serde sans échappement. Pour la même raison, une String dont la valeur est littéralement \N (par exemple SELECT '\\N'::String FORMAT HiveText) est écrite avec les mêmes deux octets qu’un véritable NULL, de sorte que les deux sont indiscernables côté Hive.

Query

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

​

Paramètres de format

Paramètre	Description	Par défaut
input_format_hive_text_fields_delimiter	Délimiteur entre les champs dans Hive Text File	\x01
input_format_hive_text_collection_items_delimiter	Délimiteur entre les éléments d’une collection (Array ou Map) dans Hive Text File. Utilisé par le format de sortie ; accepté, mais actuellement non utilisé lors de l’analyse de l’entrée.	\x02
input_format_hive_text_map_keys_delimiter	Délimiteur entre une paire clé/valeur d’une Map dans Hive Text File. Utilisé par le format de sortie ; accepté, mais actuellement non utilisé lors de l’analyse de l’entrée.	\x03
input_format_hive_text_allow_variable_number_of_columns	Ignore les colonnes supplémentaires dans l’entrée Hive Text (si le fichier comporte plus de colonnes que prévu) et traite les champs manquants comme des valeurs par défaut	1
format_hive_text_rows_delimiter	Délimiteur à la fin de chaque ligne dans la sortie Hive Text	\n