Описание
Соответствие типов данных
При записи файла Parquet типы данных, для которых нет соответствующего типа Parquet, преобразуются в ближайший доступный тип:
Массивы могут быть вложенными и принимать значение типа
Nullable в качестве аргумента. Типы Tuple и Map также могут быть вложенными.
Широкие целые числа
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. Мы читаем их следующим образом:
TIME(время суток) читается как временная метка. Например,10:23:13.000становится1970-01-01 10:23:13.000.TIMESTAMP/TIMEсisAdjustedToUTC=false— это локальное wall-clock time (поля года, месяца, дня, часа, минуты, секунды и долей секунды в локальном часовом поясе, независимо от того, какой именно часовой пояс считается локальным), то же, что и SQLTIMESTAMP 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)
BYTE_ARRAY, закодированной в WKB (или в WKT при чтении), а JSON-ключ geo в метаданных Parquet на уровне файла описывает кодирование, тип геометрии и CRS для каждого такого столбца.
Поведение при чтении
- Столбец, объявленный как
Point,MultiPoint,LineString,Polygon,MultiLineStringилиMultiPolygon, считывается в соответствующий гео-тип ClickHouse. - Столбец с несколькими или неизвестными геометрическими типами считывается в тип
Geometry, который представляет собойVariant, охватывающий все поддерживаемые гео-типы. - Если запрошенный тип столбца —
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 для него не записываются, поэтому при чтении результат не распознаётся как столбец с геометрией 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 также не поддерживается для столбцов с геометрией.
Пример использования
Вставка данных
football.parquet:
Чтение данных
Parquet:
движок таблицы HDFS.