Parquet

В этом документе описана поддержка чтения и записи файлов Parquet в Doris. Она применяется к следующим функциям:

• Чтение и запись данных в Catalog.
• Чтение данных с помощью Table Valued Functions.
• Чтение данных с помощью Broker Load.
• Запись данных во время Export.
• Запись данных с помощью Outfile.

Декодирование временных меток INT96

Parquet INT96 хранит поля даты и времени без указания часового пояса. Поэтому FileScannerV2 по умолчанию сохраняет исходное значение локального времени, не сдвигая его в соответствии с часовым поясом SQL-сеанса. Например, исходное значение 2021-01-01 10:11:00 остаётся 10:11:00 при сопоставлении с DATETIMEV2, в том числе при сканировании Catalog, использовании табличных функций и Broker Load.

Это поведение относится только к INT96. Значения Parquet INT64 с логическим типом timestamp по-прежнему подчиняются семантике логического типа. Если устаревшие средства записи Hive нормализовали значения INT96 с использованием известного часового пояса, настройте hive.parquet.time-zone в Hive Catalog. Внешние табличные функции для файлов также принимают это свойство. Другие точки входа FileScannerV2 сохраняют исходное локальное время INT96, за исключением Hudi: в нативном и JNI-сканировании он намеренно сохраняет прежнее поведение часового пояса SQL-сеанса и игнорирует hive.parquet.time-zone.

Когда столбец INT96 сопоставляется с TIMESTAMPTZ, Doris сохраняет момент времени UTC, не применяя часовой пояс совместимости.

Сопоставление типа UUID

Поддерживается чтение FIXED_LEN_BYTE_ARRAY(16) с аннотацией UUID при обычном или словарном кодировании в каноническом порядке байтов от старшего к младшему. В версии dev обычные Parquet TVF и Iceberg Catalog напрямую сопоставляют столбцы с аннотацией UUID с нативным UUID, независимо от устаревших параметров двоичного сопоставления. Parquet TVF в Doris 4.1.5 по-прежнему возвращают канонические строки UUID или VARBINARY в соответствии с enable_mapping_varbinary; UUID в Iceberg в этой версии сопоставляется с VARBINARY(16).

При записи столбца Doris UUID, включая вложенный элемент UUID в ARRAY, MAP или STRUCT, создаётся FIXED_LEN_BYTE_ARRAY(16) с логической аннотацией UUID, поэтому другие движки, распознающие эту аннотацию, восстанавливают значение как UUID. Версия dev восстанавливает нативный UUID при чтении таких файлов, включая вложенные элементы UUID.

Полное сопоставление типов UUID для OUTFILE и EXPORT см. в разделе Сопоставление типов столбцов для экспортируемых файлов.

Поддерживаемые форматы сжатия

• uncompressed
• snappy
• lz4
• zstd
• gzip
• lzo
• brotli

Запись индексов страниц (версия Dev)

Doris может по желанию записывать метаданные Parquet ColumnIndex и OffsetIndex при экспорте с помощью OUTFILE или EXPORT, а также при вставке в таблицы Hive и Iceberg, хранящиеся в формате Parquet. Средство чтения, поддерживающее эти индексы, может находить подходящие страницы по значению и сохранять согласованность строк между столбцами. Существующие файлы не изменяются.

Установите следующие переменные сеанса перед оператором записи. Они применяются только к выводу Parquet и не включают фильтрацию по индексам страниц на стороне чтения.

Переменная	Тип	По умолчанию	Поведение
enable_parquet_write_page_index	Boolean	true	Записывает индексы страниц для новых файлов Parquet. ColumnIndex зависит от наличия статистики для столбца; OffsetIndex записывает расположение страниц данных и позиции строк.
parquet_write_data_page_size	Integer, байты	1048576 (1 MiB)	Целевой размер несжатой страницы данных в диапазоне от 1 до 2147483647. Применяется независимо от того, включена или отключена запись индексов. Не задаёт размер группы строк или страницы словаря.

Размер страницы является целевым: отдельное значение или пакет записи могут превысить его. Для LZ4 в кадрах Hadoop, используемого в выводе Hive/Iceberg lz4, Doris ограничивает это значение 131072 байтами (128 KiB), чтобы сохранить совместимость со средствами чтения Hadoop. Вывод Raw LZ4 не подпадает под это ограничение, специфичное для кодека.

Например, подготовив доступный для записи бакет S3 и учётные данные согласно разделу OUTFILE, экспортируйте результат запроса с индексами и целевым размером страницы 256 KiB. Замените заполнители хранилища собственной конфигурацией:

SET enable_parquet_write_page_index = true;
SET parquet_write_data_page_size = 262144;

SELECT 1 AS id, 'example' AS label
INTO OUTFILE 's3://example-bucket/export/result_'
FORMAT AS PARQUET
PROPERTIES (
    "s3.endpoint" = "https://s3.example.com",
    "s3.region" = "us-east-1",
    "s3.access_key" = "<access_key>",
    "s3.secret_key" = "<secret_key>"
);

Полученные файлы содержат метаданные индексов страниц для подходящих столбцов. Для Hive или Iceberg установите те же переменные сеанса перед INSERT INTO или INSERT OVERWRITE; целевая таблица уже должна быть настроена на запись в формате Parquet. Для EXPORT установите их перед отправкой задания.

По умолчанию запись индексов включена (true), что сохраняет существующее поведение записи в dev-версии. Чтобы не включать индексы страниц в последующий вывод, установите параметр перед записью:

SET enable_parquet_write_page_index = false;

Чтобы восстановить значения по умолчанию в текущем сеансе:

SET enable_parquet_write_page_index = true;
SET parquet_write_data_page_size = 1048576;

Индексы увеличивают объём метаданных и нагрузку при записи. Меньшие страницы могут улучшить выборочное чтение, особенно когда значения сгруппированы, но также создают больше записей индекса и заголовков страниц. Преимущества зависят от используемого движка и распределения данных; включение индексов не гарантирует ускорения запросов. Средства чтения по-прежнему могут читать файлы без использования необязательных индексов. Эти параметры не изменяют версию формата Parquet или версию страниц данных.

Параметры

Совместимость временных меток и дат (начиная с 4.1.5)

Начиная с версии 4.1.5, чтение и запись Parquet сохраняют различие между локальным временем на часах и моментами времени. Логическая временная метка без часового пояса сопоставляется с DATETIME, логическая временная метка с isAdjustedToUTC=true — с TIMESTAMPTZ. Ни свойство совместимости Catalog, ни enable_mapping_timestamp_tz=false в файловом TVF не могут восстановить сопоставление с DATETIME для последнего случая.

Parquet INT96 не содержит аннотации часового пояса и определяется как DATETIME(6). Hive Catalog и файловые TVF принимают необязательное свойство hive.parquet.time-zone для указания часового пояса средства записи INT96. По умолчанию используется пустая строка, сохраняющая локальное время на часах. Используйте часовой пояс IANA или смещение UTC от -12:00 до +14:00. Допускаются UTC и GMT; короткие псевдонимы, такие как CST и PRC, отклоняются. Указывайте его только если часовой пояс средства записи известен, например, "hive.parquet.time-zone" = "Asia/Shanghai".

Начиная с версии 4.1.5, для Outfile и Export, записывающих логические временные метки INT64, параметр enable_int96_timestamps по умолчанию имеет значение false. Устанавливайте его в true только для потребителей, которым требуется INT96. Запись таблиц Hive использует другой вариант совместимости; см. Hive Catalog.

Файлы DATE, записанные старым кодированием Doris и содержащие даты от 0000-01-01 до 0000-02-28, требуют миграции с учётом средства записи. Одного обновления средства чтения недостаточно для их исправления. См. раздел Миграция файлов DATE с нулевым годом.

Переменные сеанса

• enable_parquet_lazy_mat (2.1+, 3.0+)

  Определяет, включает ли Parquet Reader отложенную материализацию. По умолчанию включено.

• hive_parquet_use_column_names (2.1.6+, 3.0.3+)

  При чтении типов данных Parquet из таблиц Hive Doris по умолчанию читает данные из столбцов файла Parquet, имена которых совпадают с именами столбцов таблицы Hive. Если для этой переменной задано значение false, Doris читает данные из файла Parquet в порядке столбцов таблицы Hive независимо от имён столбцов. Это аналогично переменной parquet.column.index.access в Hive. Параметр применяется только к именам столбцов верхнего уровня и не действует для столбцов внутри Struct.

Конфигурация BE

• parquet_metadata_size_limit (начиная с 4.1.5)

  Максимальный размер сериализованных метаданных footer для нативного Parquet V2 Reader. По умолчанию — 268435456 байт (256 MiB); значение должно быть больше 0, поддерживаются динамические обновления. Этот параметр не связан с ограничением Page Header. При превышении возвращается сообщение Parquet v2 footer size ... exceeds metadata limit .... См. Конфигурация BE.

• enable_parquet_page_index (2.1.5+, 3.0+)

  Определяет, использует ли Parquet Reader Page Index для фильтрации данных. Параметр предназначен только для отладки на случай, если индекс страниц иногда фильтрует неправильные данные. Значение по умолчанию — false.

• parquet_header_max_size_mb (2.1+, 3.0+)

  Максимальный размер буфера, выделяемого при чтении заголовка страницы Parquet. По умолчанию — 1M.

• parquet_rowgroup_max_buffer_mb (2.1+, 3.0+)

  Максимальный размер буфера, выделяемого при чтении группы строк Parquet. По умолчанию — 128M.

• parquet_column_max_buffer_mb (2.1+, 3.0+)

  Максимальный размер буфера, выделяемого при чтении столбца в группе строк Parquet. По умолчанию — 8M.