Parquet - ClickHouse Documentation

Ввод	Вывод	Псевдоним
✔	✔

Описание

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

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

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 даст корректное представление локального времени.

​Описание

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

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

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

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

​Настройки формата

Описание

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

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

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

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

Настройки формата