Parquet

Entrée	Sortie	Alias
✔	✔

Description

Apache Parquet 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 de ClickHouse.

Type Parquet (logique, converti ou physique)	Type de données ClickHouse
`BOOLEAN`	Bool
`UINT_8`	UInt8
`INT_8`	Int8
`UINT_16`	UInt16
`INT_16`	Int16/Enum16
`UINT_32`	UInt32
`INT_32`	Int32
`UINT_64`	UInt64
`INT_64`	Int64
`DATE`	Date32
`TIMESTAMP`	DateTime64
`TIME`	Time64
`FLOAT`	Float32
`DOUBLE`	Float64
`INT96`	DateTime64(9, ‘UTC’)
`BYTE_ARRAY`, `UTF8`, `ENUM`, `BSON`	String
`JSON`	JSON
`FIXED_LEN_BYTE_ARRAY`	FixedString
`DECIMAL`	Decimal
`LIST`	Array
`MAP`	Map
struct	Tuple
`FLOAT16`	Float32
`UUID`	FixedString(16)
`INTERVAL`	FixedString(12)
`Point` (GeoParquet)	Point
`MultiPoint` (GeoParquet)	MultiPoint
`LineString` (GeoParquet)	LineString
`Polygon` (GeoParquet)	Polygon
`MultiLineString` (GeoParquet)	MultiLineString
`MultiPolygon` (GeoParquet)	MultiPolygon
géométrie mixte/inconnue (GeoParquet)	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	`UINT_32`
IPv6	`FIXED_LEN_BYTE_ARRAY` (16 octets)
Date (16 bits)	`DATE` (32 bits)
DateTime (32 bits, secondes)	`TIMESTAMP` (64 bits, millisecondes)
Int128/UInt128/Int256/UInt256	`FIXED_LEN_BYTE_ARRAY` (16/32 octets, little-endian)
Point	`BYTE_ARRAY` (WKB) + métadonnées GeoParquet
MultiPoint	`BYTE_ARRAY` (WKB) + métadonnées GeoParquet
LineString	`BYTE_ARRAY` (WKB) + métadonnées GeoParquet
Polygon	`BYTE_ARRAY` (WKB) + métadonnées GeoParquet
MultiLineString	`BYTE_ARRAY` (WKB) + métadonnées GeoParquet
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 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. 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. Les colonnes géométriques sont stockées sous forme de payloads BYTE_ARRAY encodés en 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 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, 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 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 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, 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 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 :

    ┌───────date─┬─season─┬─home_team─────────────┬─away_team───────────┬─home_team_goals─┬─away_team_goals─┐
│ 2022-04-30 │   2021 │ Sutton United         │ Bradford City       │               1 │               4 │
│ 2022-04-30 │   2021 │ Swindon Town          │ Barrow              │               2 │               1 │
│ 2022-04-30 │   2021 │ Tranmere Rovers       │ Oldham Athletic     │               2 │               0 │
│ 2022-05-02 │   2021 │ Port Vale             │ Newport County      │               1 │               2 │
│ 2022-05-02 │   2021 │ Salford City          │ Mansfield Town      │               2 │               2 │
│ 2022-05-07 │   2021 │ Barrow                │ Northampton Town    │               1 │               3 │
│ 2022-05-07 │   2021 │ Bradford City         │ Carlisle United     │               2 │               0 │
│ 2022-05-07 │   2021 │ Bristol Rovers        │ Scunthorpe United   │               7 │               0 │
│ 2022-05-07 │   2021 │ Exeter City           │ Port Vale           │               0 │               1 │
│ 2022-05-07 │   2021 │ Harrogate Town A.F.C. │ Sutton United       │               0 │               2 │
│ 2022-05-07 │   2021 │ Hartlepool United     │ Colchester United   │               0 │               2 │
│ 2022-05-07 │   2021 │ Leyton Orient         │ Tranmere Rovers     │               0 │               1 │
│ 2022-05-07 │   2021 │ Mansfield Town        │ Forest Green Rovers │               2 │               2 │
│ 2022-05-07 │   2021 │ Newport County        │ Rochdale            │               0 │               2 │
│ 2022-05-07 │   2021 │ Oldham Athletic       │ Crawley Town        │               3 │               3 │
│ 2022-05-07 │   2021 │ Stevenage Borough     │ Salford City        │               4 │               2 │
│ 2022-05-07 │   2021 │ Walsall               │ Swindon Town        │               0 │               3 │
    └────────────┴────────┴───────────────────────┴─────────────────────┴─────────────────┴─────────────────┘

Insérez les données :

INSERT INTO football FROM INFILE 'football.parquet' FORMAT Parquet;

Lecture des données

Lisez les données au format Parquet :

SELECT *
FROM football
INTO OUTFILE 'football.parquet'
FORMAT Parquet

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.

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`, `MultiPoint`, `LineString`, `Polygon`, `MultiLineString`, `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.

Référence SQL

Types de données

Moteurs

Fonctions

Formats

Paramètres

Tables système

Lacs de données

Description

Correspondance des types de données

Entiers larges

Types géo (GeoParquet)

Comportement en lecture

Comportement d’écriture

Exemple d’utilisation

Insertion de données

Lecture des données

Paramètres de format

​Description

​Correspondance des types de données

​Entiers larges

​Types géo (GeoParquet)

​Comportement en lecture

​Comportement d’écriture

​Exemple d’utilisation

​Insertion de données

​Lecture des données

​Paramètres de format

Description

Correspondance des types de données

Entiers larges

Types géo (GeoParquet)

Comportement en lecture

Comportement d’écriture

Exemple d’utilisation

Insertion de données

Lecture des données

Paramètres de format