> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Документация по формату Parquet # Parquet | Ввод | Вывод | Псевдоним | | - | - | - | | ✔ | ✔ | | ## Описание [Apache Parquet](https://parquet.apache.org/) — столбцовый формат хранения данных, широко распространённый в экосистеме Hadoop. ClickHouse поддерживает чтение и запись в этом формате. ## Соответствие типов данных В таблице ниже показано, как типы данных Parquet соотносятся с [типами данных](/ru/reference/data-types/index) ClickHouse. | Тип Parquet (логический, преобразованный или физический) | Тип данных ClickHouse | | - | - | | `BOOLEAN` | [Bool](/ru/reference/data-types/boolean) | | `UINT_8` | [UInt8](/ru/reference/data-types/int-uint) | | `INT_8` | [Int8](/ru/reference/data-types/int-uint) | | `UINT_16` | [UInt16](/ru/reference/data-types/int-uint) | | `INT_16` | [Int16](/ru/reference/data-types/int-uint)/[Enum16](/ru/reference/data-types/enum) | | `UINT_32` | [UInt32](/ru/reference/data-types/int-uint) | | `INT_32` | [Int32](/ru/reference/data-types/int-uint) | | `UINT_64` | [UInt64](/ru/reference/data-types/int-uint) | | `INT_64` | [Int64](/ru/reference/data-types/int-uint) | | `DATE` | [Date32](/ru/reference/data-types/date) | | `TIMESTAMP` | [DateTime64](/ru/reference/data-types/datetime64) | | `TIME` | [Time64](/ru/reference/data-types/time64) | | `FLOAT` | [Float32](/ru/reference/data-types/float) | | `DOUBLE` | [Float64](/ru/reference/data-types/float) | | `INT96` | [DateTime64(9, 'UTC')](/ru/reference/data-types/datetime64) | | `BYTE_ARRAY`, `UTF8`, `ENUM`, `BSON` | [String](/ru/reference/data-types/string) | | `JSON` | [JSON](/ru/reference/data-types/newjson) | | `FIXED_LEN_BYTE_ARRAY` | [FixedString](/ru/reference/data-types/fixedstring) | | `DECIMAL` | [Decimal](/ru/reference/data-types/decimal) | | `LIST` | [Array](/ru/reference/data-types/array) | | `MAP` | [Map](/ru/reference/data-types/map) | | struct | [Tuple](/ru/reference/data-types/tuple) | | `FLOAT16` | [Float32](/ru/reference/data-types/float) | | `UUID` | [FixedString(16)](/ru/reference/data-types/fixedstring) | | `INTERVAL` | [FixedString(12)](/ru/reference/data-types/fixedstring) | | `Point` (GeoParquet) | [Point](/ru/reference/data-types/geo#point) | | `MultiPoint` (GeoParquet) | [MultiPoint](/ru/reference/data-types/geo#multipoint) | | `LineString` (GeoParquet) | [LineString](/ru/reference/data-types/geo#linestring) | | `Polygon` (GeoParquet) | [Polygon](/ru/reference/data-types/geo#polygon) | | `MultiLineString` (GeoParquet) | [MultiLineString](/ru/reference/data-types/geo#multilinestring) | | `MultiPolygon` (GeoParquet) | [MultiPolygon](/ru/reference/data-types/geo#multipolygon) | | смешанная/неизвестная геометрия (GeoParquet) | [Geometry](/ru/reference/data-types/geo#geometry) | При записи файла Parquet типы данных, для которых нет соответствующего типа Parquet, преобразуются в ближайший доступный тип: | Тип данных ClickHouse | Тип Parquet | | - | - | | [IPv4](/ru/reference/data-types/ipv4) | `UINT_32` | | [IPv6](/ru/reference/data-types/ipv6) | `FIXED_LEN_BYTE_ARRAY` (16 байт) | | [Date](/ru/reference/data-types/date) (16 бит) | `DATE` (32 бита) | | [DateTime](/ru/reference/data-types/datetime) (32 бита, секунды) | `TIMESTAMP` (64 бита, миллисекунды) | | [Int128/UInt128/Int256/UInt256](/ru/reference/data-types/int-uint) | `FIXED_LEN_BYTE_ARRAY` (16/32 байта, little-endian) | | [Point](/ru/reference/data-types/geo#point) | `BYTE_ARRAY` (WKB) + метаданные GeoParquet | | [MultiPoint](/ru/reference/data-types/geo#multipoint) | `BYTE_ARRAY` (WKB) + метаданные GeoParquet | | [LineString](/ru/reference/data-types/geo#linestring) | `BYTE_ARRAY` (WKB) + метаданные GeoParquet | | [Polygon](/ru/reference/data-types/geo#polygon) | `BYTE_ARRAY` (WKB) + метаданные GeoParquet | | [MultiLineString](/ru/reference/data-types/geo#multilinestring) | `BYTE_ARRAY` (WKB) + метаданные GeoParquet | | [MultiPolygon](/ru/reference/data-types/geo#multipolygon) | `BYTE_ARRAY` (WKB) + метаданные GeoParquet | Массивы могут быть вложенными и принимать значение типа `Nullable` в качестве аргумента. Типы `Tuple` и `Map` также могут быть вложенными. ### Широкие целые числа По умолчанию ClickHouse записывает `Int128`, `UInt128`, `Int256` и `UInt256` как значения `FIXED_LEN_BYTE_ARRAY(16/32)` без аннотаций в порядке little-endian. Это устаревшее представление остается используемым по умолчанию, чтобы файлы можно было читать в более ранних версиях ClickHouse. Установите `output_format_parquet_wide_integer_as_decimal = 1`, чтобы вместо этого использовать стандартное представление Parquet `DECIMAL`: | Тип ClickHouse | Логический тип Parquet | Физический тип | Кодирование значений | | - | - | - | - | | `UInt128` | `DECIMAL(39, 0)` | `FIXED_LEN_BYTE_ARRAY(17)` | Нулевой знаковый байт, за которым следует 16-байтное беззнаковое значение в порядке big-endian | | `UInt256` | `DECIMAL(78, 0)` | `FIXED_LEN_BYTE_ARRAY(33)` | Нулевой знаковый байт, за которым следует 32-байтное беззнаковое значение в порядке big-endian | | `Int128` | `DECIMAL(39, 0)` | `FIXED_LEN_BYTE_ARRAY(17)` | 16-байтное значение в дополнительном коде в порядке big-endian с расширением знака до 17 байт | | `Int256` | `DECIMAL(77, 0)` | `FIXED_LEN_BYTE_ARRAY(33)` | 32-байтное значение в дополнительном коде в порядке big-endian с расширением знака до 33 байт | Десятичное представление обеспечивает числовое упорядочивание в стандартной статистике фрагментов столбцов и индексах страниц Parquet, что позволяет ClickHouse отсекать группы строк и страницы по минимальным и максимальным значениям. ClickHouse читает оба варианта кодирования. Для десятичной точности 39 вывод схемы возвращает `Decimal(39, 0)`, основанный на `Decimal256`; укажите явную структуру `Int128` или `UInt128`, чтобы получить тип широкого целого числа. Десятичная точность 77 или 78 превышает диапазон ClickHouse `Decimal256`, поэтому для чтения таких файлов требуется явная совместимая структура `Int256` или `UInt256`. При явной структуре широкого целого числа ClickHouse принимает стандартные десятичные значения, хранящиеся как `BYTE_ARRAY` или `FIXED_LEN_BYTE_ARRAY` любой допустимой ширины, и проверяет диапазон каждого значения после удаления расширения знака. Некоторые клиенты Parquet поддерживают десятичную точность только до 38, в то время как высокоуровневые десятичные типы Arrow поддерживают точность только до 76. Такие клиенты могут отклонить представление с точностью 77/78, хотя его схема и физическая ширина в 33 байта соответствуют Parquet. Оставьте настройку отключенной, если файлы должны читаться более ранними версиями ClickHouse или клиентами с меньшими ограничениями точности десятичных чисел. Типы данных столбцов таблицы ClickHouse могут отличаться от соответствующих полей вставляемых данных Parquet. При вставке данных ClickHouse интерпретирует типы данных в соответствии с таблицей выше, а затем [приводит](/ru/reference/functions/regular-functions/type-conversion-functions#CAST) данные к типу данных, заданному для столбца таблицы ClickHouse. Например, столбец Parquet `UINT_32` можно прочитать в столбец ClickHouse [IPv4](/ru/reference/data-types/ipv4). Для некоторых типов Parquet нет близко соответствующего типа ClickHouse. Мы читаем их следующим образом: * `TIMESTAMP` с `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. ## Гео-типы (GeoParquet) ClickHouse поддерживает чтение и запись столбцов с геометрией в соответствии со спецификацией [GeoParquet](https://geoparquet.org/). Столбцы с геометрией хранятся в виде полезной нагрузки `BYTE_ARRAY`, закодированной в [WKB](https://libgeos.org/specifications/wkb/) (или в WKT при чтении), а JSON-ключ `geo` в метаданных Parquet на уровне файла описывает кодирование, тип геометрии и CRS для каждого такого столбца. ### Поведение при чтении При чтении столбцы с геометрией сопоставляются с соответствующими [гео-типами данных ClickHouse](/ru/reference/data-types/geo): * Столбец, объявленный как `Point`, `MultiPoint`, `LineString`, `Polygon`, `MultiLineString` или `MultiPolygon`, считывается в соответствующий гео-тип ClickHouse. * Столбец с несколькими или неизвестными геометрическими типами считывается в тип [`Geometry`](/ru/reference/data-types/geo#geometry), который представляет собой `Variant`, охватывающий все поддерживаемые гео-типы. * Если запрошенный тип столбца — `String`, метаданные GeoParquet игнорируются, и возвращается исходная закодированная геометрическая полезная нагрузка — байты WKB или WKT, в зависимости от того, какая кодировка указана для столбца GeoParquet. Это также верно, если для настройки [`input_format_parquet_allow_geoparquet_parser`](/ru/reference/settings/formats/input-format#input_format_parquet_allow_geoparquet_parser) установлено значение `0`. ### Поведение при записи При записи столбцы верхнего уровня типов `Point`, `MultiPoint`, `LineString`, `Polygon`, `MultiLineString` или `MultiPolygon` кодируются как `BYTE_ARRAY` (WKB), а соответствующие JSON-метаданные `geo` добавляются в нижний колонтитул файла Parquet. Верхнеуровневый [`Geometry`](/ru/reference/data-types/geo#geometry) `Variant` тоже кодируется как полезная нагрузка `BYTE_ARRAY` в формате WKB (его вложенные значения преобразуются в WKB и сохраняются в столбце `Nullable(String)`), однако метаданные `geo` для него не записываются, поэтому при чтении результат не распознаётся как столбец с геометрией GeoParquet. Другие связанные с `geo` типы, такие как [`Ring`](/ru/reference/data-types/geo#ring), записываются в своём собственном базовом представлении без метаданных GeoParquet. Это поведение можно полностью отключить, установив [`output_format_parquet_geometadata`](/ru/reference/settings/formats/output-format#output_format_parquet_geometadata) в `0`; в этом случае даже поддерживаемые гео-типы записываются в своём собственном базовом представлении (`Point` как `Tuple(Float64, Float64)`, `LineString` как `Array(Point)`, `Polygon` как `Array(Array(Point))` и т. д.), и метаданные GeoParquet не записываются. Столбцы с геометрией должны находиться в корне схемы или быть вложены в `Tuple` (`struct`); вложение в `Array` или `Map` не поддерживается. `Nullable` также не поддерживается для столбцов с геометрией. ## Пример использования ### Вставка данных Используйте файл Parquet со следующими данными с именем `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 │ └────────────┴────────┴───────────────────────┴─────────────────────┴─────────────────┴─────────────────┘ ``` Вставьте данные: ```sql theme={null} INSERT INTO football FROM INFILE 'football.parquet' FORMAT Parquet; ``` ### Чтение данных Прочитайте данные в формате `Parquet`: ```sql theme={null} SELECT * FROM football INTO OUTFILE 'football.parquet' FORMAT Parquet ``` Parquet — это бинарный формат, который не отображается в терминале в удобочитаемом виде. Используйте `INTO OUTFILE` для вывода файлов Parquet. Для обмена данными с Hadoop можно использовать [`движок таблицы HDFS`](/ru/reference/engines/table-engines/integrations/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_dictionary_filter_push_down` | При чтении файлов Parquet (с ридером v3) пропускать целые группы строк на основе выражений WHERE/PREWHERE и содержимого страниц словаря для условий равенства и `IN`, если все страницы данных фрагмента столбца закодированы словарём. Значение — максимальный размер страницы словаря (в байтах), при котором применяется эта оптимизация; установите `0`, чтобы отключить её. Имеет приоритет над bloom filter, если доступны оба. | `1048576` | | `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` | | `input_format_parquet_allow_geoparquet_parser` | При чтении файлов Parquet распознавать метаданные GeoParquet `geo` и декодировать столбцы с геометрией (WKB или WKT в соответствии с объявленной кодировкой столбца) как гео-типы данных ClickHouse. Если `0`, столбцы с геометрией возвращаются в исходном физическом представлении (`String`). | `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_wide_integer_as_decimal` | Записывать `Int128`, `UInt128`, `Int256` и `UInt256` как стандартные значения Parquet `DECIMAL` в формате big-endian вместо устаревших массивов байтов фиксированной длины в формате little-endian. | `0` | | `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` | | `output_format_parquet_geometadata` | Записывать метаданные GeoParquet `geo` в нижний колонтитул файла Parquet и кодировать геостолбцы верхнего уровня в ClickHouse ([`Point`](/ru/reference/data-types/geo#point), [`MultiPoint`](/ru/reference/data-types/geo#multipoint), [`LineString`](/ru/reference/data-types/geo#linestring), [`Polygon`](/ru/reference/data-types/geo#polygon), [`MultiLineString`](/ru/reference/data-types/geo#multilinestring), [`MultiPolygon`](/ru/reference/data-types/geo#multipolygon)) в формате WKB. Если `0`, эти столбцы записываются с использованием их нативного внутреннего представления (например, `Point` как `Tuple(Float64, Float64)`), и метаданные GeoParquet не добавляются. | `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 даст корректное представление локального времени. |