> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentation sur le format HiveText

# HiveText

| Entrée | Sortie | Alias |
| ------ | ------ | ----- |
| ✔      | ✔      |       |

<div id="description">
  ## Description
</div>

`HiveText` lit et écrit le format de sérialisation texte utilisé par les tables [Apache Hive](https://hive.apache.org/)
(format produit par le `LazySimpleSerDe` de Hive). Il s'agit d'un format texte
délimité, semblable à [`CSV`](/fr/reference/formats/CSV/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`](#format-settings).

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`](/fr/reference/settings/formats/date-time#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`](/fr/reference/data-types/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`.

<Info>
  **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`](#format-settings) et
  [`input_format_hive_text_map_keys_delimiter`](#format-settings)
  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.
</Info>

Par défaut, les lignes peuvent contenir un nombre variable de champs (voir
[`input_format_hive_text_allow_variable_number_of_columns`](#format-settings)) :
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.

<div id="example-usage">
  ## Exemple d’utilisation
</div>

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`](#format-settings), afin de rendre les fichiers d’entrée
plus faciles à lire.

<div id="reading-data">
  ### Lecture d’un fichier HiveText
</div>

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

```text title="hive_data.txt" theme={null}
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` :

```sql title="Query" theme={null}
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 title="Response" theme={null}
┌─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`.

<div id="variable-number-of-columns">
  ### Nombre variable de colonnes
</div>

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 :

```text title="hive_extras.txt" theme={null}
1,2,3,4,5
6,7,8
```

```sql title="Query" theme={null}
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 title="Response" theme={null}
┌─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.

<div id="output">
  ## Sortie
</div>

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`](#format-settings)). Les valeurs des types imbriqués
([`Array`](/fr/reference/data-types/array), [`Map`](/fr/reference/data-types/map)
et [`Tuple`](/fr/reference/data-types/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`](#format-settings)
(`\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`](#format-settings) (`\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`](/fr/reference/settings/formats/date-time#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`](/fr/reference/settings/formats/bool#bool_true_representation)
et [`bool_false_representation`](/fr/reference/settings/formats/bool#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`](/fr/reference/settings/formats/format-csv#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`](/fr/reference/settings/formats/format-csv#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`.

<Info>
  **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`](/fr/reference/data-types/array), [`Map`](/fr/reference/data-types/map)
    et [`Tuple`](/fr/reference/data-types/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`](#format-settings) /
    [`input_format_hive_text_map_keys_delimiter`](#format-settings). 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`](#format-settings) 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.
</Info>

```sql title="Query" theme={null}
SELECT '20240305', tuple(123567, 'e01001', map('action1', 33333, 'act2', 5555)) FORMAT HiveText;
```

<div id="format-settings">
  ## Paramètres de format
</div>

| 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`       |