> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentation sur le format Parquet

# Parquet

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

## Description

[Apache Parquet](https://parquet.apache.org/) est un format de stockage colonnaire largement répandu dans l’écosystème Hadoop. ClickHouse prend en charge la lecture et l’écriture de ce format.

## Correspondance des types de données

Le tableau ci-dessous indique la correspondance entre les types de données Parquet et les [types de données](/docs/fr/reference/data-types/index.md) de ClickHouse.

| Type Parquet (logique, converti ou physique) | Type de données ClickHouse |
| - | - |
| `BOOLEAN` | [Bool](/docs/fr/reference/data-types/boolean.md) |
| `UINT_8` | [UInt8](/docs/fr/reference/data-types/int-uint.md) |
| `INT_8` | [Int8](/docs/fr/reference/data-types/int-uint.md) |
| `UINT_16` | [UInt16](/docs/fr/reference/data-types/int-uint.md) |
| `INT_16` | [Int16](/docs/fr/reference/data-types/int-uint.md)/[Enum16](/docs/fr/reference/data-types/enum.md) |
| `UINT_32` | [UInt32](/docs/fr/reference/data-types/int-uint.md) |
| `INT_32` | [Int32](/docs/fr/reference/data-types/int-uint.md) |
| `UINT_64` | [UInt64](/docs/fr/reference/data-types/int-uint.md) |
| `INT_64` | [Int64](/docs/fr/reference/data-types/int-uint.md) |
| `DATE` | [Date32](/docs/fr/reference/data-types/date.md) |
| `TIMESTAMP` | [DateTime64](/docs/fr/reference/data-types/datetime64.md) |
| `TIME` | [Time64](/docs/fr/reference/data-types/time64.md) |
| `FLOAT` | [Float32](/docs/fr/reference/data-types/float.md) |
| `DOUBLE` | [Float64](/docs/fr/reference/data-types/float.md) |
| `INT96` | [DateTime64(9, 'UTC')](/docs/fr/reference/data-types/datetime64.md) |
| `BYTE_ARRAY`, `UTF8`, `ENUM`, `BSON` | [String](/docs/fr/reference/data-types/string.md) |
| `JSON` | [JSON](/docs/fr/reference/data-types/newjson.md) |
| `FIXED_LEN_BYTE_ARRAY` | [FixedString](/docs/fr/reference/data-types/fixedstring.md) |
| `DECIMAL` | [Decimal](/docs/fr/reference/data-types/decimal.md) |
| `LIST` | [Array](/docs/fr/reference/data-types/array.md) |
| `MAP` | [Map](/docs/fr/reference/data-types/map.md) |
| struct | [Tuple](/docs/fr/reference/data-types/tuple.md) |
| `FLOAT16` | [Float32](/docs/fr/reference/data-types/float.md) |
| `UUID` | [FixedString(16)](/docs/fr/reference/data-types/fixedstring.md) |
| `INTERVAL` | [FixedString(12)](/docs/fr/reference/data-types/fixedstring.md) |
| `Point` (GeoParquet) | [Point](/docs/fr/reference/data-types/geo.md#point) |
| `MultiPoint` (GeoParquet) | [MultiPoint](/docs/fr/reference/data-types/geo.md#multipoint) |
| `LineString` (GeoParquet) | [LineString](/docs/fr/reference/data-types/geo.md#linestring) |
| `Polygon` (GeoParquet) | [Polygon](/docs/fr/reference/data-types/geo.md#polygon) |
| `MultiLineString` (GeoParquet) | [MultiLineString](/docs/fr/reference/data-types/geo.md#multilinestring) |
| `MultiPolygon` (GeoParquet) | [MultiPolygon](/docs/fr/reference/data-types/geo.md#multipolygon) |
| géométrie mixte/inconnue (GeoParquet) | [Geometry](/docs/fr/reference/data-types/geo.md#geometry) |

Lors de l’écriture d’un fichier Parquet, les types de données qui n’ont pas de type Parquet correspondant sont convertis vers le type disponible le plus proche :

| Type de données ClickHouse | Type Parquet |
| - | - |
| [IPv4](/docs/fr/reference/data-types/ipv4.md) | `UINT_32` |
| [IPv6](/docs/fr/reference/data-types/ipv6.md) | `FIXED_LEN_BYTE_ARRAY` (16 octets) |
| [Date](/docs/fr/reference/data-types/date.md) (16 bits) | `DATE` (32 bits) |
| [DateTime](/docs/fr/reference/data-types/datetime.md) (32 bits, secondes) | `TIMESTAMP` (64 bits, millisecondes) |
| [Int128/UInt128/Int256/UInt256](/docs/fr/reference/data-types/int-uint.md) | `FIXED_LEN_BYTE_ARRAY` (16/32 octets, little-endian) |
| [Point](/docs/fr/reference/data-types/geo.md#point) | `BYTE_ARRAY` (WKB) + métadonnées GeoParquet |
| [MultiPoint](/docs/fr/reference/data-types/geo.md#multipoint) | `BYTE_ARRAY` (WKB) + métadonnées GeoParquet |
| [LineString](/docs/fr/reference/data-types/geo.md#linestring) | `BYTE_ARRAY` (WKB) + métadonnées GeoParquet |
| [Polygon](/docs/fr/reference/data-types/geo.md#polygon) | `BYTE_ARRAY` (WKB) + métadonnées GeoParquet |
| [MultiLineString](/docs/fr/reference/data-types/geo.md#multilinestring) | `BYTE_ARRAY` (WKB) + métadonnées GeoParquet |
| [MultiPolygon](/docs/fr/reference/data-types/geo.md#multipolygon) | `BYTE_ARRAY` (WKB) + métadonnées GeoParquet |

Les tableaux peuvent être imbriqués et accepter comme argument une valeur de type `Nullable`. Les types `Tuple` et `Map` peuvent également être imbriqués.

### Entiers larges

Par défaut, ClickHouse écrit `Int128`, `UInt128`, `Int256` et `UInt256` comme valeurs `FIXED_LEN_BYTE_ARRAY(16/32)` non annotées en ordre little-endian. Cette représentation héritée reste la valeur par défaut afin que les fichiers puissent être lus par les anciennes versions de ClickHouse.

Définissez `output_format_parquet_wide_integer_as_decimal = 1` pour utiliser à la place la représentation `DECIMAL` standard de Parquet :

| Type ClickHouse | Type logique Parquet | Type physique | Encodage des valeurs |
| - | - | - | - |
| `UInt128` | `DECIMAL(39, 0)` | `FIXED_LEN_BYTE_ARRAY(17)` | Un octet de signe nul suivi de la valeur non signée de 16 octets en ordre big-endian |
| `UInt256` | `DECIMAL(78, 0)` | `FIXED_LEN_BYTE_ARRAY(33)` | Un octet de signe nul suivi de la valeur non signée de 32 octets en ordre big-endian |
| `Int128` | `DECIMAL(39, 0)` | `FIXED_LEN_BYTE_ARRAY(17)` | La valeur en complément à deux de 16 octets en ordre big-endian, étendue par signe à 17 octets |
| `Int256` | `DECIMAL(77, 0)` | `FIXED_LEN_BYTE_ARRAY(33)` | La valeur en complément à deux de 32 octets en ordre big-endian, étendue par signe à 33 octets |

La représentation décimale fournit un ordre numérique pour les statistiques standard des fragments de colonnes et les index de pages Parquet, ce qui permet à ClickHouse d'utiliser l'élagage min/max des groupes de lignes et des pages. ClickHouse lit les deux encodages. Pour une précision décimale de 39, l'inférence de schéma renvoie `Decimal(39, 0)`, basé sur `Decimal256` ; spécifiez une structure `Int128` ou `UInt128` explicite pour retrouver un type d'entier large. Une précision décimale de 77 ou 78 dépasse la plage de `Decimal256` de ClickHouse ; la lecture de ces fichiers nécessite donc une structure `Int256` ou `UInt256` compatible explicite. Avec une structure d'entier large explicite, ClickHouse accepte les valeurs décimales standard stockées sous forme de `BYTE_ARRAY` ou de `FIXED_LEN_BYTE_ARRAY` de toute largeur valide, et vérifie que chaque valeur est dans la plage après suppression de l'extension de signe.

Certains clients Parquet ne prennent en charge qu'une précision décimale allant jusqu'à 38, tandis que les types décimaux de haut niveau d'Arrow ne prennent en charge qu'une précision allant jusqu'à 76. Ces clients peuvent rejeter la représentation de précision 77/78, même si son schéma et sa largeur physique de 33 octets sont conformes à Parquet. Laissez ce paramètre désactivé lorsque les fichiers doivent être lus par des versions plus anciennes de ClickHouse ou par des clients ayant des limites décimales inférieures.

Les types de données des colonnes d'une table ClickHouse peuvent différer de ceux des champs correspondants dans les données Parquet insérées. Lors de l'insertion de données, ClickHouse interprète les types de données conformément au tableau ci-dessus, puis [convertit](/docs/fr/reference/functions/regular-functions/type-conversion-functions.md#CAST) les données vers le type défini pour la colonne de la table ClickHouse. Par exemple, une colonne Parquet `UINT_32` peut être lue dans une colonne ClickHouse [IPv4](/docs/fr/reference/data-types/ipv4.md).

Pour certains types Parquet, il n'existe pas de type ClickHouse vraiment proche. Nous les lisons comme suit :

* `TIMESTAMP` avec `isAdjustedToUTC=false` correspond à une heure locale d'horloge (champs année, mois, jour, heure, minute, seconde et fraction de seconde dans un fuseau horaire local, indépendamment du fuseau horaire précis considéré comme local), comme en SQL `TIMESTAMP WITHOUT TIME ZONE`. ClickHouse le lit au contraire comme s'il s'agissait d'un timestamp UTC. Par exemple, `2025-09-29 18:42:13.000` (représentant la lecture d'une horloge locale) devient `2025-09-29 18:42:13.000` (`DateTime64(3, 'UTC')` représentant un point dans le temps). S'il est converti en String, il affiche correctement l'année, le mois, le jour, l'heure, la minute, la seconde et la fraction de seconde, qui peuvent ensuite être interprétés comme appartenant à un fuseau horaire local plutôt qu'à UTC. De manière contre-intuitive, changer le type de `DateTime64(3, 'UTC')` en `DateTime64(3)` ne résoudrait pas le problème, car les deux types représentent un point dans le temps plutôt qu'une lecture d'horloge, mais `DateTime64(3)` serait formaté de manière incorrecte avec le fuseau horaire local.
* `INTERVAL` est actuellement lu comme `FixedString(12)`, avec la représentation binaire brute de l'intervalle de temps telle qu'elle est encodée dans le fichier Parquet.

## Types géo (GeoParquet)

ClickHouse prend en charge la lecture et l’écriture des colonnes géométriques conformément à la spécification [GeoParquet](https://geoparquet.org/). Les colonnes géométriques sont stockées sous forme de payloads `BYTE_ARRAY` encodés en [WKB](https://libgeos.org/specifications/wkb/) (ou en WKT à la lecture), avec une clé JSON `geo` dans les métadonnées Parquet au niveau du fichier, qui décrit l’encodage, le type de géométrie et le CRS de chaque colonne géométrique.

### Comportement en lecture

À la lecture, les colonnes géométriques sont associées aux [types de données Geo](/docs/fr/reference/data-types/geo.md) ClickHouse correspondants :

* Une colonne déclarée comme `Point`, `MultiPoint`, `LineString`, `Polygon`, `MultiLineString` ou `MultiPolygon` est lue dans le type Geo ClickHouse correspondant.
* Une colonne contenant plusieurs types de géométrie ou des types de géométrie inconnus est lue dans le type [`Geometry`](/docs/fr/reference/data-types/geo#geometry), qui est un `Variant` de tous les types Geo pris en charge.
* Si le type de colonne demandé est `String`, les métadonnées GeoParquet sont ignorées et la charge utile géométrique brute encodée est renvoyée telle quelle — en octets WKB ou WKT, selon l’encodage déclaré par la colonne GeoParquet. Cela vaut également si le paramètre [`input_format_parquet_allow_geoparquet_parser`](/docs/fr/reference/settings/formats/input-format#input_format_parquet_allow_geoparquet_parser) est défini sur `0`.

### Comportement d’écriture

Lors de l’écriture, les colonnes de premier niveau de type `Point`, `MultiPoint`, `LineString`, `Polygon`, `MultiLineString` ou `MultiPolygon` sont encodées en `BYTE_ARRAY` (WKB), et les métadonnées JSON `geo` appropriées sont ajoutées au footer du fichier Parquet. Un [`Geometry`](/docs/fr/reference/data-types/geo#geometry) `Variant` de premier niveau est lui aussi encodé sous la forme d’une charge utile `BYTE_ARRAY` WKB (ses sous-valeurs sont converties en WKB et stockées dans une colonne `Nullable(String)`), mais aucune métadonnée `geo` n’est émise le concernant ; le résultat n’est donc pas reconnu à la lecture comme une colonne de géométrie GeoParquet. Les autres types liés à la géométrie, tels que [`Ring`](/docs/fr/reference/data-types/geo#ring), sont écrits à l’aide de leur représentation native sous-jacente, sans métadonnées GeoParquet. Ce comportement peut être entièrement désactivé en définissant [`output_format_parquet_geometadata`](/docs/fr/reference/settings/formats/output-format#output_format_parquet_geometadata) sur `0`. Dans ce cas, même les types geo pris en charge sont écrits à l’aide de leur représentation native sous-jacente (`Point` comme `Tuple(Float64, Float64)`, `LineString` comme `Array(Point)`, `Polygon` comme `Array(Array(Point))`, etc.), et aucune métadonnée GeoParquet n’est émise.

Les colonnes géométriques doivent se trouver à la racine du schéma ou être imbriquées dans `Tuple` (`struct`) ; leur imbrication dans `Array` ou `Map` n’est pas prise en charge. `Nullable` n’est pas non plus pris en charge pour les colonnes géométriques.

## Exemple d’utilisation

### Insertion de données

À partir d’un fichier Parquet contenant les données suivantes, nommé `football.parquet` :

```text theme={null}
    ┌───────date─┬─season─┬─home_team─────────────┬─away_team───────────┬─home_team_goals─┬─away_team_goals─┐
 1. │ 2022-04-30 │   2021 │ Sutton United         │ Bradford City       │               1 │               4 │
 2. │ 2022-04-30 │   2021 │ Swindon Town          │ Barrow              │               2 │               1 │
 3. │ 2022-04-30 │   2021 │ Tranmere Rovers       │ Oldham Athletic     │               2 │               0 │
 4. │ 2022-05-02 │   2021 │ Port Vale             │ Newport County      │               1 │               2 │
 5. │ 2022-05-02 │   2021 │ Salford City          │ Mansfield Town      │               2 │               2 │
 6. │ 2022-05-07 │   2021 │ Barrow                │ Northampton Town    │               1 │               3 │
 7. │ 2022-05-07 │   2021 │ Bradford City         │ Carlisle United     │               2 │               0 │
 8. │ 2022-05-07 │   2021 │ Bristol Rovers        │ Scunthorpe United   │               7 │               0 │
 9. │ 2022-05-07 │   2021 │ Exeter City           │ Port Vale           │               0 │               1 │
10. │ 2022-05-07 │   2021 │ Harrogate Town A.F.C. │ Sutton United       │               0 │               2 │
11. │ 2022-05-07 │   2021 │ Hartlepool United     │ Colchester United   │               0 │               2 │
12. │ 2022-05-07 │   2021 │ Leyton Orient         │ Tranmere Rovers     │               0 │               1 │
13. │ 2022-05-07 │   2021 │ Mansfield Town        │ Forest Green Rovers │               2 │               2 │
14. │ 2022-05-07 │   2021 │ Newport County        │ Rochdale            │               0 │               2 │
15. │ 2022-05-07 │   2021 │ Oldham Athletic       │ Crawley Town        │               3 │               3 │
16. │ 2022-05-07 │   2021 │ Stevenage Borough     │ Salford City        │               4 │               2 │
17. │ 2022-05-07 │   2021 │ Walsall               │ Swindon Town        │               0 │               3 │
    └────────────┴────────┴───────────────────────┴─────────────────────┴─────────────────┴─────────────────┘
```

Insérez les données :

```sql theme={null}
INSERT INTO football FROM INFILE 'football.parquet' FORMAT Parquet;
```

### Lecture des données

Lisez les données au format `Parquet` :

```sql theme={null}
SELECT *
FROM football
INTO OUTFILE 'football.parquet'
FORMAT Parquet
```

> [!TIP]
>
> Parquet est un format binaire qui ne s’affiche pas dans le terminal sous une forme lisible par l’humain. Utilisez `INTO OUTFILE` pour écrire des fichiers Parquet.

Pour échanger des données avec Hadoop, vous pouvez utiliser le [`moteur de table HDFS`](/docs/fr/reference/engines/table-engines/integrations/hdfs).

## Paramètres de format

| Paramètre | Description | Par défaut |
| - | - | - |
| `input_format_parquet_case_insensitive_column_matching` | Ignorer la casse lors de la correspondance entre les colonnes Parquet et les colonnes CH. | `0` |
| `input_format_parquet_preserve_order` | Éviter de réordonner les lignes lors de la lecture de fichiers Parquet. Cela ralentit généralement considérablement la lecture. | `0` |
| `input_format_parquet_filter_push_down` | Lors de la lecture de fichiers Parquet, ignorer des groupes de lignes entiers en fonction des expressions WHERE/PREWHERE et des statistiques min/max figurant dans les métadonnées Parquet. | `1` |
| `input_format_parquet_bloom_filter_push_down` | Lors de la lecture de fichiers Parquet, ignorer des groupes de lignes entiers en fonction des expressions WHERE et du bloom filter dans les métadonnées Parquet. | `0` |
| `input_format_parquet_dictionary_filter_push_down` | Lors de la lecture de fichiers Parquet (avec le lecteur v3), ignorer des groupes de lignes entiers en fonction des expressions WHERE/PREWHERE et du contenu des pages de dictionnaire, pour les conditions d’égalité et `IN`, lorsque toutes les pages de données d’un fragment de colonne sont encodées avec un dictionnaire. La valeur correspond à la taille maximale de page de dictionnaire (en octets) pour laquelle cette optimisation est appliquée ; définissez-la sur `0` pour la désactiver. Prend le pas sur le bloom filter lorsque les deux sont disponibles. | `1048576` |
| `input_format_parquet_allow_missing_columns` | Autoriser les colonnes manquantes lors de la lecture de formats d'entrée Parquet | `1` |
| `input_format_parquet_local_file_min_bytes_for_seek` | Nombre minimal d'octets requis pour qu'une lecture locale (fichier) effectue un seek, au lieu d'une lecture avec ignoré, dans le format d'entrée Parquet | `8192` |
| `input_format_parquet_enable_row_group_prefetch` | Activer le préchargement des groupes de lignes lors de l'analyse de Parquet. Actuellement, seule l'analyse monothread permet le préchargement. | `1` |
| `input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference` | Ignorer les colonnes dont les types ne sont pas pris en charge lors de l’inférence du schéma pour le format Parquet | `0` |
| `input_format_parquet_max_block_size` | Taille de bloc maximale pour le lecteur Parquet. | `65409` |
| `input_format_parquet_prefer_block_bytes` | Nombre moyen d’octets par bloc en sortie du lecteur Parquet | `16744704` |
| `input_format_parquet_enable_json_parsing` | Lors de la lecture de fichiers Parquet, analyser les colonnes JSON en tant que colonne JSON ClickHouse. | `1` |
| `input_format_parquet_allow_geoparquet_parser` | Lors de la lecture de fichiers Parquet, reconnaît les métadonnées `geo` de GeoParquet et décode les colonnes de géométrie (WKB ou WKT, selon l’encodage déclaré de la colonne) en types de données géographiques ClickHouse. Si `0`, les colonnes de géométrie sont exposées dans leur représentation physique brute (`String`). | `1` |
| `output_format_parquet_row_group_size` | Taille cible du groupe de lignes, en nombre de lignes. | `1000000` |
| `output_format_parquet_row_group_size_bytes` | Taille cible du groupe de lignes en octets, avant la compression. | `536870912` |
| `output_format_parquet_string_as_string` | Utiliser le type String de Parquet au lieu de Binary pour les colonnes de type String. | `1` |
| `output_format_parquet_fixed_string_as_fixed_byte_array` | Utiliser le type FIXED\_LEN\_BYTE\_ARRAY de Parquet au lieu de Binary pour les colonnes FixedString. | `1` |
| `output_format_parquet_wide_integer_as_decimal` | Écrire `Int128`, `UInt128`, `Int256` et `UInt256` sous forme de valeurs `DECIMAL` Parquet standard au format big-endian plutôt que sous forme de tableaux d’octets fixes legacy au format little-endian. | `0` |
| `output_format_parquet_compression_method` | Méthode de compression du format de sortie Parquet. Codecs pris en charge : snappy, lz4, brotli, zstd, gzip, none (sans compression) | `zstd` |
| `output_format_parquet_parallel_encoding` | Effectue l’encodage Parquet sur plusieurs threads. | `1` |
| `output_format_parquet_data_page_size` | Taille de page cible en octets, avant compression. | `1048576` |
| `output_format_parquet_batch_size` | Vérifie la taille de la page toutes les N lignes. Envisagez de la réduire si vous avez des colonnes dont la taille moyenne des valeurs dépasse quelques Ko. | `1024` |
| `output_format_parquet_write_page_index` | Ajoute la possibilité d’écrire l’index de page dans les fichiers Parquet. | `1` |
| `output_format_parquet_geometadata` | Écrire les métadonnées GeoParquet `geo` dans le footer du fichier Parquet et encoder les colonnes geo ClickHouse de premier niveau ([`Point`](/docs/fr/reference/data-types/geo#point), [`MultiPoint`](/docs/fr/reference/data-types/geo#multipoint), [`LineString`](/docs/fr/reference/data-types/geo#linestring), [`Polygon`](/docs/fr/reference/data-types/geo#polygon), [`MultiLineString`](/docs/fr/reference/data-types/geo#multilinestring), [`MultiPolygon`](/docs/fr/reference/data-types/geo#multipolygon)) au format WKB. Si `0`, ces colonnes sont écrites à l’aide de leur représentation native sous-jacente (par ex. `Point` comme `Tuple(Float64, Float64)`) et aucune métadonnée GeoParquet n’est générée. | `1` |
| `input_format_parquet_import_nested` | Paramètre obsolète, sans effet. | `0` |
| `input_format_parquet_local_time_as_utc` | true | Détermine le type de données utilisé par l’inférence de schéma pour les timestamps Parquet avec isAdjustedToUTC=false. Si true : DateTime64(..., 'UTC'), si false : DateTime64(...). Aucun de ces deux comportements n’est entièrement correct, car ClickHouse ne dispose pas d’un type de données pour l’heure locale sur l’horloge. De façon contre-intuitive, 'true' est probablement l’option la moins incorrecte, car le formatage du timestamp 'UTC' en String produira une représentation correcte de l’heure locale. |