Parquet

Документация по формату 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 — это локальное wall-clock time (поля года, месяца, дня, часа, минуты, секунды и долей секунды в локальном часовом поясе, независимо от того, какой именно часовой пояс считается локальным), то же, что и 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 со столбцами ClickHouse.	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 и bloom filter в метаданных Parquet.	0
input_format_parquet_allow_missing_columns	Разрешить отсутствие столбцов при чтении входного формата Parquet	1
input_format_parquet_local_file_min_bytes_for_seek	Минимальное количество байтов для локального чтения (из файла), при котором выполняется seek вместо чтения с пропуском во входном формате 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-столбцы как JSON-столбцы ClickHouse.	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_compression_method	Метод сжатия для выходного формата Parquet. Поддерживаемые кодеки: snappy, lz4, brotli, zstd, gzip, none (без сжатия)	zstd
output_format_parquet_parallel_encoding	Выполнять кодирование Parquet в несколько потоков.	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	Определяет тип данных, используемый при определении схемы для временных меток Parquet с isAdjustedToUTC=false. Если true: DateTime64(…, ‘UTC’), если false: DateTime64(…). Ни один из вариантов не является полностью корректным, так как в ClickHouse нет типа данных для локального wall-clock time. Как ни странно, вариант ‘true’, вероятно, менее некорректен, потому что форматирование временной метки ‘UTC’ как String даст корректное представление локального времени.