Перейти к основному содержанию

​
Описание

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

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

В таблице ниже показано, как типы данных Parquet соотносятся с типами данных ClickHouse. При записи файла Parquet типы данных, для которых нет соответствующего типа Parquet, преобразуются в ближайший доступный тип: Массивы могут быть вложенными и принимать значение типа 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.

​
Гео-типы (GeoParquet)

ClickHouse поддерживает чтение и запись столбцов с геометрией в соответствии со спецификацией GeoParquet. Столбцы с геометрией хранятся в виде полезной нагрузки BYTE_ARRAY, закодированной в WKB (или в WKT при чтении), а JSON-ключ geo в метаданных Parquet на уровне файла описывает кодирование, тип геометрии и CRS для каждого такого столбца.

​
Поведение при чтении

При чтении столбцы с геометрией сопоставляются с соответствующими гео-типами данных ClickHouse:
  • Столбец, объявленный как Point, LineString, Polygon, MultiLineString или MultiPolygon, считывается в соответствующий гео-тип ClickHouse.
  • Столбец с несколькими или неизвестными геометрическими типами считывается в тип Geometry, который представляет собой Variant, охватывающий все поддерживаемые гео-типы.
  • Если запрошенный тип столбца — String, метаданные GeoParquet игнорируются, и возвращается исходная закодированная геометрическая полезная нагрузка — байты WKB или WKT, в зависимости от того, какая кодировка указана для столбца GeoParquet. Это также верно, если для настройки input_format_parquet_allow_geoparquet_parser установлено значение 0.

​
Поведение при записи

При записи столбцы верхнего уровня типов Point, LineString, Polygon, MultiLineString или MultiPolygon кодируются как BYTE_ARRAY (WKB), а соответствующие JSON-метаданные geo добавляются в нижний колонтитул файла Parquet. Верхнеуровневый Geometry Variant тоже кодируется как полезная нагрузка BYTE_ARRAY в формате WKB (его вложенные значения преобразуются в WKB и сохраняются в столбце Nullable(String)), однако метаданные geo для него не записываются, поэтому при чтении результат не распознаётся как столбец геометрии GeoParquet. Другие связанные с geo типы, такие как Ring, записываются в своём собственном базовом представлении без метаданных GeoParquet. Это поведение можно полностью отключить, установив 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:
Вставьте данные:

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

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

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

Последнее изменение 29 июня 2026 г.