ORC

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

• Чтение и запись данных в Catalog.
• Чтение данных с помощью табличных функций (Table Valued Functions).
• Чтение данных с помощью Broker Load.
• Запись данных при экспорте с помощью Export.
• Запись данных с помощью Outfile.

Точность дробной части секунды во временных метках

Временные метки ORC могут хранить наносекунды, тогда как DATETIMEV2 и TIMESTAMPTZ в Doris поддерживают точность до микросекунд. При сканировании Catalog, использовании табличных функций и загрузке через Broker Load FileScannerV2 округляет дробную часть секунды в ORC до ближайшей микросекунды по правилу round half up:

Значение ORC	Значение Doris
2024-01-01 00:00:00.123456499	2024-01-01 00:00:00.123456
2024-01-01 00:00:00.123456500	2024-01-01 00:00:00.123457
2024-01-01 00:00:00.999999500	2024-01-01 00:00:01.000000

Это правило применяется при сопоставлении как с DATETIMEV2, так и с TIMESTAMPTZ, включая перенос в следующую секунду. При декодировании строк, преобразовании статистики и проталкивании предикатов используются согласованные границы. Если точности статистики ORC недостаточно для точного представления округлённой границы, Doris расширяет границу отсечения с запасом. Если предикат для временной метки, например !=, невозможно представить безопасно, Doris пропускает соответствующий поисковый аргумент и вычисляет предикат на декодированных строках. Это может снизить эффективность отсечения по данному предикату, но предотвращает ошибочный пропуск подходящих строк.

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

Doris записывает столбец UUID, в том числе элемент UUID, вложенный в ARRAY, MAP или STRUCT, как BINARY, содержащий каноническое 16-байтовое значение с порядком байтов big-endian, и добавляет атрибут doris.logical_type=uuid, обозначающий нативный тип UUID. В ORC нет стандартного типа UUID, поэтому инструменты, отличные от Doris, видят обычный двоичный столбец без семантики UUID. Если для OUTFILE явно задано свойство ORC schema, объявляйте столбцы UUID как binary; другие типы, например string, отклоняются.

При чтении столбца BINARY с атрибутом doris.logical_type=uuid восстанавливается нативный тип UUID, в том числе для вложенных элементов; это поддерживается обоими средствами чтения файлов. Поэтому табличная функция возвращает для таких столбцов тип uuid, array<uuid> или struct<k:uuid>. В версии dev тип BINARY без этого атрибута сопоставляется с VARBINARY, а STRING остаётся STRING.

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

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

• без сжатия (uncompressed)
• snappy
• lz4
• zstd
• lzo
• zlib

Параметры

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

Начиная с 4.1.5, тип ORC TIMESTAMP представляет локальное время без часового пояса, а TIMESTAMP_INSTANT представляет момент времени и сопоставляется с TIMESTAMPTZ. При чтении наносекунды округляются до микросекунд. Значения вне допустимого диапазона и недопустимые значения наносекунд приводят к ошибкам.

При записи в ORC некоторые отрицательные временные метки с дробной частью, непосредственно предшествующие началу эпохи Unix, невозможно представить без потери данных. Doris возвращает ошибку ORC cannot represent pre-epoch timestamp fractions in [-0.999, 0) seconds without data loss; use Parquet for these values. Для данных, содержащих такие значения, используйте Parquet.

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

Переменные сессии

• enable_orc_lazy_mat (2.1+, 3.0+)

  Управляет включением отложенной материализации в ORC Reader. Значение по умолчанию: true.

• hive_orc_use_column_names (2.1.6+, 3.0.3+)

  При чтении типов данных ORC из таблиц Hive Doris по умолчанию читает данные из столбцов ORC-файла, имена которых совпадают с именами столбцов таблицы Hive. Если для этой переменной задано значение false, Doris читает данные из ORC-файла в соответствии с порядком столбцов в таблице Hive независимо от их имён. Это аналогично переменной orc.force.positional.evolution в Hive. Этот параметр применяется только к именам столбцов верхнего уровня и не действует на столбцы внутри Structs.

• orc_tiny_stripe_threshold_bytes (2.1.8+, 3.0.3+)

  Если размер Stripe в ORC-файле в байтах меньше orc_tiny_stripe_threshold, такой Stripe считается Tiny Stripe. Для нескольких последовательных Tiny Stripe выполняется оптимизация чтения: они считываются за один раз, чтобы уменьшить число операций IO. Чтобы отключить эту оптимизацию, можно задать значение 0. Значение по умолчанию: 8M.

• orc_once_max_read_bytes (2.1.8+, 3.0.3+)

  При использовании оптимизации чтения Tiny Stripe несколько Tiny Stripe объединяются в одну операцию IO. Этот параметр задаёт максимальное число байтов в каждом запросе IO. Его значение не должно быть меньше orc_tiny_stripe_threshold. Значение по умолчанию: 8M.

• orc_max_merge_distance_bytes (2.1.8+, 3.0.3+)

  При оптимизации чтения Tiny Stripe два считываемых Tiny Stripe могут не следовать непосредственно друг за другом. Если расстояние между ними превышает значение этого параметра, они не объединяются в одну операцию IO. Значение по умолчанию: 1M.

• orc_tiny_stripe_amplification_factor (3.1.0+)

  Если в ORC-файле много столбцов, а запрос использует лишь несколько из них, оптимизация Tiny Stripe может приводить к существенному увеличению объёма считываемых данных. Оптимизация чтения Tiny Stripe применяется, когда отношение числа фактически считываемых байтов к общему размеру Stripe превышает значение этого параметра. Значение по умолчанию: 0.4, минимальное значение: 0.

• check_orc_init_sargs_success (3.1.0+)

  Проверяет, успешно ли выполнено проталкивание предикатов ORC; используется для отладки. Значение по умолчанию: false.

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

• orc_natural_read_size_mb (2.1+, 3.0+)

  Максимальное число байтов, считываемых ORC Reader за один раз. Значение по умолчанию: 8 MB.