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

Описание

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

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

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

Тип Variant

ClickHouse читает столбцы, хранящиеся в Parquet в кодировании VARIANT (например, записанные Spark 4.0), в тип Dynamic. Столбец распознаётся как variant, если он представляет собой группу с аннотацией логического типа VARIANT (версия спецификации 1). Spark 4.0 записывает variant-столбцы без этой аннотации, поэтому группа, содержащая только поля metadata и value типа BYTE_ARRAY, также читается как variant. Это поведение можно отключить настройкой input_format_parquet_detect_variant_by_structure — тогда такая группа, как и раньше, читается как Tuple из двух исходных полей. Если же явно запросить для столбца тип Dynamic или JSON, он будет прочитан как variant независимо от этой настройки. Каждое значение сохраняет собственный тип. Примитивные типы variant читаются как соответствующие типы ClickHouse (например, int32 — как Int32, decimal8 — как Decimal(18, S), timestamp — как DateTime64(6, 'UTC'), timestamp_ntz — как DateTime64(6), binary и string — как String, uuid — как UUID). Variant-значение null читается как NULL, variant-объекты — как JSON, причём вложенные объекты разворачиваются в пути с точкой в качестве разделителя (поле со значением null считается отсутствующим). Variant-массивы, все элементы которых являются объектами, читаются как Array(JSON), а остальные variant-массивы — как Array(Dynamic). Тип верхнего уровня — Dynamic, а не JSON, поскольку variant-значение не обязательно является объектом. Variant-столбец также можно прочитать как JSON, явно запросив этот тип, например в структуре таблицы или в аргументе структуры табличной функции file. В этом случае каждое значение должно быть объектом, иначе будет сгенерировано исключение. Variant-значение null и null всего столбца читаются как пустой объект. Типизированные пути запрошенного типа JSON приводятся к своим типам, а пути, перечисленные в SKIP и SKIP REGEXP, пропускаются. Фрагментированные (shredded) variant-значения (группы с полем typed_value) пока не поддерживаются: при чтении такого столбца генерируется исключение, однако остальные столбцы файла по-прежнему можно прочитать. Если включена настройка input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference, автоматическое определение схемы пропускает такой столбец. Запись столбцов Dynamic или JSON в Parquet в виде VARIANT также не поддерживается.

Ссылки на файлы

Группа, помеченная логическим типом Parquet FILE, представляет собой ссылку на диапазон байтов, хранящийся встроенно или во внешнем файле. Она читается как именованный Tuple из полей, присутствующих в файле, каждое из которых имеет тип Nullable: uri, content_type и checksum — как Nullable(String), offset и size — как Nullable(Int64), а inline — как Nullable(String) с необработанными байтами. Ссылка на файл со значением null читается как кортеж, все элементы которого равны NULL. Как и в случае любого Tuple, можно прочитать лишь подмножество полей, запросив Tuple с меньшим числом элементов, либо отдельные поля как подстолбцы, например file.uri. Схема группы проверяется на корректность: она должна содержать только эти поля, все с модификатором OPTIONAL и с типами, определёнными спецификацией, иначе генерируется исключение. Значения на корректность не проверяются: значение, не образующее допустимую ссылку (например, offset без uri), возвращается в том виде, в каком оно сохранено. ClickHouse не разрешает ссылки, то есть не читает внешние файлы. При записи такой Tuple (имена элементов которого образуют непустое подмножество полей FILE, offset и size — целые числа, а остальные элементы имеют тип String или FixedString) записывается как группа с аннотацией FILE, если включена настройка output_format_parquet_write_file_logical_type. В противном случае он записывается как обычная группа.

Гео-типы (GeoParquet)

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

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

При чтении столбцы с геометрией сопоставляются с соответствующими гео-типами данных ClickHouse:
  • Столбец, объявленный как Point, MultiPoint, LineString, Polygon, MultiLineString или MultiPolygon, считывается в соответствующий гео-тип ClickHouse.
  • Столбец с несколькими или неизвестными геометрическими типами считывается в тип Geometry, который представляет собой Variant, охватывающий все поддерживаемые гео-типы.
  • Для столбца с логическим типом GEOMETRY или GEOGRAPHY тип геометрии берётся из метаданных GeoParquet, если они есть в файле. В противном случае, если в GeospatialStatistics всех фрагментов столбца указан один и тот же двумерный тип геометрии, столбец считывается в соответствующий гео-тип, а если нет — в Geometry. Если гео-тип запрошен явно, значения декодируются непосредственно в этот тип.
  • В ClickHouse нет отдельного типа для географических данных, поэтому столбцы GEOGRAPHY считываются в те же гео-типы, что и GEOMETRY (координатами служат долгота и широта), а алгоритм интерполяции рёбер (параметр algorithm) не сохраняется. CRS (параметр crs, по умолчанию OGC:CRS84) также не сохраняется. Геометрические объекты с координатами Z или M не поддерживаются.
  • Порядок сортировки логических типов GEOMETRY и GEOGRAPHY не определён, поэтому статистика min/max и индекс столбцов для таких столбцов игнорируются. При включённой настройке input_format_parquet_spatial_filter_push_down ограничивающий прямоугольник из GeospatialStatistics используется для пропуска групп строк.
  • Если запрошенный тип столбца — String, метаданные GeoParquet и логический тип игнорируются, и возвращается исходная закодированная геометрическая полезная нагрузка — байты WKB или WKT, в зависимости от того, какое кодирование указано для столбца GeoParquet. Это также верно, если для настройки input_format_parquet_allow_geoparquet_parser установлено значение 0 и гео-тип явно не запрошен.

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

При записи столбцы верхнего уровня типов Point, MultiPoint, LineString, Polygon, MultiLineString или MultiPolygon кодируются как BYTE_ARRAY (WKB), а соответствующие JSON-метаданные geo добавляются в нижний колонтитул файла Parquet. Верхнеуровневый Geometry Variant тоже кодируется как полезная нагрузка BYTE_ARRAY в формате WKB (его вложенные значения преобразуются в WKB и сохраняются в столбце Nullable(String)), однако по умолчанию метаданные geo для него не записываются, поэтому при чтении он возвращается как String. По умолчанию эти столбцы записываются как BYTE_ARRAY со статистикой min/max. Если включена настройка output_format_parquet_geometry_logical_type, все эти столбцы аннотируются логическим типом GEOMETRY с CRS по умолчанию (OGC:CRS84), а метаданные их фрагментов столбцов, как того требует спецификация, содержат GeospatialStatistics (ограничивающий прямоугольник и геометрические типы), но не содержат ни статистики min/max, ни индекса столбца; при этом столбец Geometry описывается в метаданных geo с пустым списком геометрических типов, поэтому при чтении он возвращается как Geometry. По умолчанию эта настройка отключена, поскольку считыватели, не поддерживающие этот логический тип (например, Arrow C++ и pyarrow до версии 20), вообще не могут открыть такой файл. Другие связанные с 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.

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