Parquet

Входной формат	Выходной формат	Псевдоним
✔	✔

Описание

Apache Parquet — это столбцовый формат хранения данных, широко распространённый в экосистеме Hadoop. ClickHouse поддерживает чтение и запись данных в этом формате.

Соответствие типов данных

В таблице ниже показано, как типы данных Parquet сопоставляются с типами данных ClickHouse.

Тип Parquet (логический, преобразованный или физический)	Тип данных 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`, `TIME`	DateTime64
`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)

При записи в файл Parquet типы данных, для которых нет соответствующего типа Parquet, преобразуются в ближайший доступный тип:

Тип данных ClickHouse	Тип Parquet
IPv4	`UINT_32`
IPv6	`FIXED_LEN_BYTE_ARRAY` (16 байт)
Date (16 бит)	`DATE` (32 бита)
DateTime (32 бита, секунды)	`TIMESTAMP` (64 бита, миллисекунды)
Int128/UInt128/Int256/UInt256	`FIXED_LEN_BYTE_ARRAY` (16/32 байта, порядок little-endian)

Массивы могут быть вложенными и могут иметь значение типа Nullable в качестве аргумента. Типы Tuple и Map также могут быть вложенными.

Типы данных столбцов таблицы ClickHouse могут отличаться от соответствующих полей вставляемых данных Parquet. При вставке данных ClickHouse интерпретирует типы данных согласно приведённой выше таблице, а затем приводит данные к тому типу данных, который установлен для столбца таблицы ClickHouse. Например, столбец Parquet UINT_32 может быть прочитан в столбец ClickHouse IPv4.

Для некоторых типов Parquet нет близкого по соответствию типа ClickHouse. Они читаются следующим образом:

TIME (время суток) читается как метка времени. Например, 10:23:13.000 становится 1970-01-01 10:23:13.000.
TIMESTAMP/TIME с isAdjustedToUTC=false — это локальное время по настенным часам (поля год, месяц, день, час, минута, секунда и доля секунды в локальном часовом поясе, независимо от того, какой конкретный часовой пояс считается локальным), аналогично SQL TIMESTAMP WITHOUT TIME ZONE. ClickHouse читает его так, как если бы это была метка времени в UTC. Например, 2025-09-29 18:42:13.000 (представляющее показания локальных настенных часов) становится 2025-09-29 18:42:13.000 (DateTime64(3, 'UTC'), представляя точку во времени). При преобразовании к String выводятся корректные год, месяц, день, час, минута, секунда и доля секунды, которые затем могут интерпретироваться как относящиеся к какому-либо локальному часовому поясу, а не к UTC. Противоинтуитивно, смена типа с DateTime64(3, 'UTC') на DateTime64(3) не поможет, так как оба типа представляют точку во времени, а не показание часов, но DateTime64(3) будет некорректно форматироваться с использованием локального часового пояса.
INTERVAL в настоящий момент читается как FixedString(12) с сырым двоичным представлением временного интервала в том виде, в котором он закодирован в файле Parquet.

Пример использования

Вставка данных

Используйте файл Parquet со следующими данными, сохранённый под именем football.parquet:

    ┌───────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 │
    └────────────┴────────┴───────────────────────┴─────────────────────┴─────────────────┴─────────────────┘

Вставьте данные:

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

Чтение данных

Прочитайте данные в формате Parquet:

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

Совет

Parquet — это двоичный формат, который не отображается в человекочитаемом виде в терминале. Используйте INTO OUTFILE для записи файлов в формате Parquet.

Для обмена данными с Hadoop вы можете использовать движок таблиц HDFS.

Параметры форматирования

Настройка	Описание	По умолчанию
`input_format_parquet_case_insensitive_column_matching`	Не учитывать регистр при сопоставлении столбцов Parquet со столбцами CH.	`0`
`input_format_parquet_preserve_order`	Избегайте изменения порядка строк при чтении из файлов Parquet. Обычно это сильно замедляет чтение.	`0`
`input_format_parquet_filter_push_down`	При чтении файлов Parquet пропускать целые группы строк на основе выражений WHERE/PREWHERE и статистики min/max в метаданных файлов Parquet.	`1`
`input_format_parquet_bloom_filter_push_down`	При чтении файлов Parquet пропускать целые группы строк на основе выражений WHERE и фильтра Блума в метаданных Parquet.	`0`
`input_format_parquet_allow_missing_columns`	Разрешать отсутствующие столбцы при чтении входных данных в формате Parquet	`1`
`input_format_parquet_local_file_min_bytes_for_seek`	Минимальный объём данных в байтах при локальном чтении файла, начиная с которого используется seek вместо чтения с игнорированием (ignore) во входном формате Parquet	`8192`
`input_format_parquet_enable_row_group_prefetch`	Включить предварительную выборку групп строк при разборе Parquet. В настоящее время предварительная выборка поддерживается только для однопоточного разбора.	`1`
`input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference`	Пропускать столбцы с неподдерживаемыми типами при определении схемы для формата Parquet	`0`
`input_format_parquet_max_block_size`	Максимальный размер блока для считывателя Parquet.	`65409`
`input_format_parquet_prefer_block_bytes`	Средний размер блока в байтах, выдаваемый читателем Parquet	`16744704`
`input_format_parquet_enable_json_parsing`	При чтении файлов Parquet интерпретировать столбцы JSON как столбцы типа ClickHouse JSON Column.	`1`
`output_format_parquet_row_group_size`	Целевое количество строк в группе.	`1000000`
`output_format_parquet_row_group_size_bytes`	Целевой размер группы строк в байтах перед сжатием.	`536870912`
`output_format_parquet_string_as_string`	Используйте тип Parquet String вместо Binary для столбцов типа String.	`1`
`output_format_parquet_fixed_string_as_fixed_byte_array`	Используйте тип Parquet FIXED_LEN_BYTE_ARRAY вместо Binary для столбцов типа FixedString.	`1`
`output_format_parquet_version`	Версия формата Parquet для выходных данных. Поддерживаемые версии: 1.0, 2.4, 2.6 и 2.latest (по умолчанию)	`2.latest`
`output_format_parquet_compression_method`	Метод сжатия для формата вывода Parquet. Поддерживаемые кодеки: snappy, lz4, brotli, zstd, gzip, none (без сжатия)	`zstd`
`output_format_parquet_compliant_nested_types`	В схеме файла Parquet используйте имя 'element' вместо 'item' для элементов списка. Это исторический артефакт реализации библиотеки Arrow. Как правило, повышает совместимость, за исключением, возможно, некоторых старых версий Arrow.	`1`
`output_format_parquet_use_custom_encoder`	Используйте более быстрый кодировщик Parquet.	`1`
`output_format_parquet_parallel_encoding`	Выполнять кодирование Parquet в нескольких потоках. Требует включения параметра output_format_parquet_use_custom_encoder.	`1`
`output_format_parquet_data_page_size`	Целевой размер страницы в байтах до сжатия.	`1048576`
`output_format_parquet_batch_size`	Проверять размер страницы через каждые указанное количество строк. Рассмотрите возможность уменьшения значения, если средний размер значений в столбцах превышает несколько КБ.	`1024`
`output_format_parquet_write_page_index`	Добавить возможность записи индекса страниц в файлы Parquet.	`1`
`input_format_parquet_import_nested`	Устаревший параметр, ничего не делает.	`0`
`input_format_parquet_local_time_as_utc`	true	Определяет тип данных, используемый при определении схемы (schema inference) для временных меток Parquet с isAdjustedToUTC=false. Если true: DateTime64(..., 'UTC'), если false: DateTime64(...). Ни один из вариантов не является полностью корректным, так как в ClickHouse нет типа данных для локального времени по настенным часам (wall-clock time). Как ни парадоксально, значение 'true', вероятно, является менее некорректным вариантом, поскольку форматирование временной метки 'UTC' как String будет соответствовать правильному локальному времени.

Описание​

Соответствие типов данных​

Пример использования​

Вставка данных​

Чтение данных​

Параметры форматирования​