Перейти к содержимому
Последнее обновление

Paimon Catalog

Doris поддерживает доступ к метаданным таблиц Paimon через различные службы метаданных, а также чтение и запись данных Paimon.

Быстрый старт с Apache Doris и Apache Paimon.

Сценарии применения​

СценарийОписание
Ускорение запросовИспользуйте распределённый вычислительный движок Doris для прямого доступа к данным Paimon и ускорения запросов.
Интеграция данныхЧитайте данные Paimon и записывайте их во внутренние таблицы Doris или выполняйте операции ZeroETL с помощью вычислительного движка Doris.
Обратная запись данныхИспользуйте Doris SQL для создания и изменения таблиц Paimon, добавления или перезаписи данных, а также изменений на уровне строк в таблицах с первичным ключом.

Настройка Catalog​

Синтаксис​

CREATE CATALOG [IF NOT EXISTS] catalog_name PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = '<paimon_catalog_type>',
    'warehouse' = '<paimon_warehouse>'
    {MetaStoreProperties},
    {StorageProperties},
    {PaimonProperties},
    {CommonProperties}
);

  • <paimon_catalog_type>

    Тип Paimon Catalog. Поддерживаются следующие варианты:

    • filesystem: По умолчанию. Прямой доступ к метаданным, хранящимся в файловой системе.

    • hms: Использование Hive Metastore в качестве службы метаданных.

    • dlf: Использование Alibaba Cloud DLF в качестве службы метаданных.

    • jdbc: Подключение к реляционной базе данных через интерфейс JDBC для использования в качестве службы метаданных (поддерживается начиная с версии 4.1.0).

  • <paimon_warehouse>

    Путь к хранилищу Paimon. Этот параметр обязателен, когда <paimon_catalog_type> имеет значение filesystem.

    Путь warehouse должен указывать на уровень выше пути Database. Например, если путь к таблице: s3://bucket/path/to/db1/table1, то значение warehouse должно быть: s3://bucket/path/to/.

  • {MetaStoreProperties}

    В разделе MetaStoreProperties указываются сведения для подключения и аутентификации в службе метаданных Metastore. Подробности см. в разделе [Поддерживаемые службы метаданных].

  • {StorageProperties}

    В разделе StorageProperties указываются сведения для подключения и аутентификации в системе хранения. Подробности см. в разделе [Поддерживаемые системы хранения].

  • {PaimonProperties}

    В разделе PaimonProperties указываются свойства, относящиеся к Paimon.

    При доступе к метаданным Paimon Doris частично использует Paimon Java SDK, поэтому некоторые пользовательские параметры может потребоваться передать в Paimon Java SDK. Для этого можно использовать следующие префиксы:

    paimon.s3.xxx
    paimon.s3a.xxx
    paimon.fs.xxx

    Эти параметры будут автоматически преобразованы и переданы далее. Несколько примеров:

    Входной параметрПреобразованный параметр для Paimon Java SDK
    "paimon.s3.list.version" = "1""fs.s3a.list.version" = "1"
    "paimon.s3.paging.maximum" = "100""fs.s3a.paging.maximum" = "100"
    "paimon.fs.s3.read.ahead.buffer.size" = "1""fs.s3a.read.ahead.buffer.size" = "1"
    "paimon.s3a.replication.factor" = "3""fs.s3a.replication.factor" = "3"

    Параметры чтения Paimon

    Doris поддерживает следующие параметры пакетного чтения ограниченного набора данных Paimon. Задавайте значения по умолчанию для запросов во всём Catalog с помощью paimon.table-option.<option-key> или переопределяйте их для отдельной ссылки на таблицу с помощью table@options('<option-key>'='<value>'). Эти настройки влияют только на чтение в Doris и никогда не изменяют физические метаданные таблицы Paimon.

    Параметр PaimonЗначение по умолчанию в PaimonЗначения, принимаемые DorisДействие
    read.batch-size1024Целое число от 1 до 65536Число строк, запрашиваемых в каждом пакете средства чтения Paimon JNI. Явно заданное значение сохраняется при открытии средства чтения в Doris.
    file-reader-async-threshold10 MBРазмер памяти от 1 MB до 1 GBПорог размера файла, при котором средство чтения Paimon JNI переключается на асинхронное чтение.
    file-index.read.enabledtrueЛогическое значениеВключает отсечение данных по файловым индексам Paimon при чтении.
    source.split.target-size128 MBПоложительный размер памятиЦелевой размер, используемый Paimon при объединении файлов данных в блоки сканирования Doris.
    source.split.open-file-cost4 MBНеотрицательный размер памятиОценка стоимости открытия файла при объединении файлов Paimon в блоки сканирования.
    scan.manifest.parallelismЧисло доступных процессоровЦелое число от 1 до 256Запрашиваемый параллелизм чтения манифестов. Во время выполнения Doris независимо ограничивает каждую ветвь планирования наименьшим из следующих значений: это значение, 256 и число процессоров, доступных соответствующему FE или BE.
    scan.plan-sort-partitionfalseЛогическое значениеСортирует разделы при планировании сканирования Paimon.

    Например, следующие настройки Catalog переопределяют значения, хранящиеся в физической таблице Paimon, и становятся значениями по умолчанию для запросов Doris:

    CREATE CATALOG paimon_hms PROPERTIES (
        "type" = "paimon",
        "paimon.catalog.type" = "hms",
        "hive.metastore.uris" = "thrift://127.0.0.1:9083",
        "warehouse" = "s3://bucket/paimon-warehouse",
        "paimon.table-option.read.batch-size" = "4096",
        "paimon.table-option.file-reader-async-threshold" = "32 MB",
        "paimon.table-option.source.split.target-size" = "64 MB",
        "paimon.table-option.scan.manifest.parallelism" = "1"
    );

    Запрос может переопределить эти значения по умолчанию без изменения Catalog или метаданных таблицы Paimon:

    SELECT *
    FROM paimon_hms.db_name.table_name@options(
        'read.batch-size' = '8192',
        'source.split.target-size' = '32 MB'
    );

    У каждой ссылки на таблицу есть независимый набор параметров. Например, два псевдонима одной таблицы могут использовать разные размеры пакета в одном операторе:

    SELECT small.id
    FROM paimon_hms.db_name.table_name@options('read.batch-size' = '1') small
    JOIN paimon_hms.db_name.table_name@options('read.batch-size' = '8192') large
      ON small.id = large.id;

    Приоритет от высшего к низшему:

    relation @options > Doris Catalog property > physical Paimon table option > Paimon default

    Doris проверяет итоговое значение после применения этого порядка приоритетов. Поэтому допустимое значение в Catalog или ссылке на таблицу может заменить недопустимое значение физической таблицы. Если итоговое значение по-прежнему недопустимо, Doris отклоняет запрос до начала соответствующего этапа планирования или чтения. Ограничения для манифестов также применяются до планирования манифестов для разделов, сбора числа строк и статистики, резервных ветвей и системных таблиц.

    Первые пять параметров в таблице не влияют на метаданные и позволяют повторно использовать кэшированную проекцию разделов для последнего снимка. scan.manifest.parallelism и scan.plan-sort-partition влияют на планирование метаданных, поэтому Doris выполняет планирование с учётом действующего дескриптора таблицы для конкретной ссылки на неё. Значения, заданные для отдельного запроса, не изменяют размер глобального для JVM исполнителя Paimon.

    Doris отклоняет неизвестные или недопустимые свойства paimon.table-option.* при выполнении CREATE CATALOG и ALTER CATALOG. ALTER CATALOG проверяет всю предлагаемую конфигурацию перед её применением, поэтому при неудачном изменении продолжает действовать прежняя конфигурация Catalog. Catalog, сохранённые более ранней версией Doris, по-прежнему можно загрузить, но неподдерживаемые или недопустимые устаревшие свойства чтения игнорируются и не применяются. Их сохранённые значения сохраняются для совместимости с образами состояния и журналом изменений.

    Параметры снимка и начальной позиции выбирают контекст ссылки на таблицу и должны задаваться через @options, как описано в разделе Time Travel; их нельзя использовать как значения по умолчанию для Catalog. Doris также исключает scan.max-splits-per-task, который относится к перечислителю источника Flink в Paimon, scan.fallback-branch, а также параметры потоковой обработки, размещения данных, записи и компактации. Настраивайте Bucket, Primary Key, Partition, Merge Engine и другие физические характеристики через свойства таблицы Paimon, в том числе с помощью Doris CREATE TABLE ... PROPERTIES.

    Согласованность в пределах оператора

    В пределах одного оператора Doris использует один и тот же снимок и одно поколение таблицы Paimon для привязки схемы, загрузки разделов, сбора числа строк и статистики, планирования системных таблиц и сканирования данных. Снимок или тег, выбранный через @options, использует схему, соответствующую этой исторической версии, включая вложенные поля STRUCT, MAP и ARRAY. Каждое выполнение подготовленного оператора получает новое состояние оператора, поэтому изменения, зафиксированные между выполнениями, видны в соответствии с селекторами и настройками кэша нового выполнения.

    Для безопасной эксплуатации сообщения DEBUG о конфигурации сканера Paimon содержат только размер пакета и число проецируемых полей. Doris не выводит полную карту параметров сканера, которая может содержать учётные данные. Показатель профиля PaimonJniAsyncReaderThreadCount опрашивается раз в секунду для всех сканеров, поэтому его значение может отставать на одну секунду. Этот опрос не влияет на выполнение или планирование запросов. Очистка ресурсов средства чтения и IOManager выполняется независимо и допускает безопасное повторение после частичного сбоя закрытия.

    Paimon JNI IOManager

    Для таблиц Paimon с первичным ключом чтение со слиянием через JNI может требовать сортировки и слияния данных из нескольких файлов. Можно включить Paimon IOManager, чтобы этот процесс мог выгружать промежуточные данные на локальный диск BE. Это снижает нагрузку на память при чтении со слиянием больших объёмов данных.

    СвойствоОбязательноПо умолчаниюОписание
    paimon.jni.enable_jni_io_managerНетfalseВключает Paimon IOManager для чтения через JNI. Остальные свойства IOManager действуют только тогда, когда это свойство имеет значение true.
    paimon.jni.io_manager.tmp_dirНет<storage_root_path>/paimon_jni_scanner_io_tmpЛокальные каталоги, используемые Paimon IOManager для временных файлов выгрузки. Несколько каталогов можно разделять запятыми или двоеточиями. Если свойство не задано, Doris создаёт по одному каталогу в каждом пути хранения BE.
    paimon.jni.io_manager.impl_classНетРеализация Paimon по умолчаниюПолное имя класса пользовательской реализации org.apache.paimon.disk.IOManager. Класс должен быть доступен в classpath сканера Paimon JNI на каждом BE.

    Следующий пример включает IOManager и позволяет Doris выбрать временные каталоги на основе путей хранения BE:

    CREATE CATALOG paimon_hms PROPERTIES (
        "type" = "paimon",
        "paimon.catalog.type" = "hms",
        "hive.metastore.uris" = "thrift://127.0.0.1:9083",
        "warehouse" = "s3://bucket/paimon-warehouse",
        "paimon.jni.enable_jni_io_manager" = "true"
    );

    Включение IOManager не приводит к выгрузке на диск при каждом чтении со слиянием. Paimon выгружает данные только тогда, когда число средств чтения для слияния превышает его sort-spill-threshold. Это не динамический параметр чтения Doris. Настраивайте его в физической таблице Paimon, если требуется изменить поведение выгрузки.

    Чтобы использовать выделенные диски для выгрузки, задайте локальные пути, которые существуют или могут быть созданы на каждом BE:

    "paimon.jni.io_manager.tmp_dir" = "/mnt/ssd1/paimon_io:/mnt/ssd2/paimon_io"

    Doris создаёт IOManager для каждого сканера JNI и закрывает его вместе со сканером. Убедитесь, что настроенные каталоги доступны для записи и имеют достаточно места для параллельных запросов. Если настроен класс пользовательской реализации, он должен предоставлять открытый конструктор, принимающий String[], открытый конструктор, принимающий String, или открытый конструктор без аргументов. Ошибка загрузки класса или создания его экземпляра приводит к сбою запроса.

    Эти свойства влияют только на чтение таблиц данных Paimon через JNI. На нативное чтение они не влияют. Параметр paimon.table-option.file-reader-async-threshold действует независимо: он управляет порогом асинхронного чтения файлов Paimon и не включает IOManager и не настраивает каталоги выгрузки.

  • {CommonProperties}

    В разделе CommonProperties указываются общие свойства. См. раздел [Общие свойства] в Обзоре Catalog.

Кэш метаданных​

Для повышения производительности доступа к внешним источникам данных Apache Doris кэширует метаданные Paimon. К метаданным относятся схемы таблиц для определённых снимков, идентификатор последнего снимка и производные проекции разделов.

подсказка

В версиях до Doris 4.1.x кэширование метаданных в основном управляется глобальными параметрами конфигурации FE. Подробности см. в разделе Кэш метаданных. Начиная с Doris 4.1.x внешний кэш метаданных Paimon Catalog настраивается с помощью унифицированных ключей meta.cache.*. Ниже описаны компоненты кэша текущей версии; в Doris 4.1.x и 4.2.x используется другой набор компонентов, описанный в версии 4.x этой страницы.

Настройка свойств кэша​

Каждый компонент кэша использует унифицированный формат ключа конфигурации: meta.cache.<engine>.<entry>.{enable,ttl-second,capacity,max-weight}. Для Paimon значение <engine> равно paimon. Параметр meta.cache.paimon.table.ttl-second управляет TTL кэша последнего снимка и кэша схем таблиц.

СвойствоПримерЗначение
enabletrue/falseВключает этот компонент кэша.
ttl-second600, 0, -10 отключает компонент (вступает в силу немедленно, можно использовать для просмотра последних данных); -1 означает отсутствие срока действия; другие положительные целые числа задают TTL в секундах с момента обращения.
capacity10000Максимальное число записей в кэше. 0 отключает компонент.
max-weight1GBПоддерживается начиная с Doris 4.1.4. Необязательное ограничение оценочного объёма памяти, удерживаемой компонентом кэша. Должно быть положительным; 0 отклоняется. Принимается только компонентами, отмеченными ниже.

Условия действия: Компонент действует при enable=true, ttl-second != 0 и capacity > 0. Ограничение памяти на уровне всего FE, Catalog или отдельного компонента дополнительно регулирует добавление записей по оценочному объёму памяти; см. Управление памятью внешнего кэша метаданных.

Модули кэша​

Следующий компонент имеет собственные ключи конфигурации и принимает max-weight:

Компонент (<entry>)Префикс ключа свойстваENTRY_NAMEКэшируемое содержимое и влияниеВключение / TTL / ёмкость по умолчанию
partition_viewmeta.cache.paimon.partition_view.paimon.partition-viewПроекции разделов, полученные из снимка таблицы. Влияние: сокращает повторное сканирование разделов при планировании.true / 86400 с / 1000

Следующие кэши не имеют токена <entry> и подчиняются только ограничениям памяти на уровне Catalog и всего FE:

ENTRY_NAMEКэшируемое содержимоеTTL / ёмкость
paimon-schema-atСхема таблицы для определённого снимкаБез срока действия / 10000
paimon-latest-snapshotИдентификатор последнего снимка таблицыmeta.cache.paimon.table.ttl-second (86400 с) / 1000

Схема столбцов таблиц Paimon кэшируется общим движком default (meta.cache.default.schema.*).

Сопоставление и преобразование устаревших параметров​

Устаревший ключ свойстваУнифицированный ключОписание
schema.cache.ttl-secondmeta.cache.default.schema.ttl-secondСрок действия кэша схем таблиц

Рекомендации​

  • Доступ к последним данным в реальном времени: Чтобы каждый запрос видел последний снимок таблиц Paimon, установите meta.cache.paimon.table.ttl-second в 0. 
    -- Disable the latest-snapshot cache to detect the latest snapshots of Paimon tables
    ALTER CATALOG paimon_ctl SET PROPERTIES ("meta.cache.paimon.table.ttl-second" = "0");
  • Оптимизация производительности: Успешное изменение свойств Catalog удаляет затронутые кэши метаданных и пересоздаёт их с новой конфигурацией при следующем обращении. Изменение meta.cache.max-weight или schema.cache.ttl-second удаляет все кэши Catalog; изменение meta.cache.<engine>.<entry>.* удаляет кэши соответствующего движка. Уже выполняющиеся запросы не затрагиваются. Когда действует ограничение памяти на уровне всего FE или Catalog, собственный CachingCatalog SDK Paimon по умолчанию отключается, чтобы избежать второго, неучтённого кэша метаданных; явно заданное свойство paimon.cache-enabled имеет приоритет.

Наблюдаемость​

Метрики кэша доступны в системной таблице information_schema.catalog_meta_cache_statistics. В ENTRY_NAME отображаются имена, перечисленные в таблице выше, а строка движка default представляет общий кэш схем таблиц:

SELECT engine_name, entry_name,
       effective_enabled, ttl_second, capacity,
       estimated_size, hit_rate, max_weight, estimated_weight
FROM information_schema.catalog_meta_cache_statistics
WHERE catalog_name = 'paimon_ctl'
ORDER BY engine_name, entry_name;

См. документацию этой системной таблицы: catalog_meta_cache_statistics.

Поддерживаемые версии Paimon​

Текущая используемая версия Paimon: 1.4.2.

Поддерживаемые форматы Paimon​

  • Поддерживается чтение Paimon Deletion Vector

Поддерживаемые службы метаданных​

Примечание: Поддерживаемые типы служб и параметры немного различаются в разных версиях Doris. См. раздел [Примеры].

Поддерживаемые системы хранения​

Примечание: Поддерживаемые типы служб и параметры немного различаются в разных версиях Doris. См. раздел [Примеры].

Поддерживаемые форматы данных​

Сопоставление типов столбцов​

Полную таблицу сопоставления для Doris 4.2, правила точности и неподдерживаемые типы см. в разделе Сопоставление типов данных Paimon и Doris.

Doris сохраняет точное написание заключённых в кавычки имён столбцов верхнего уровня и вложенных полей STRUCT в обоих вариантах работы сканера Paimon JNI. Имена, содержащие разделители, такие как запятые (region,code), знаки решётки (nested#value), двоеточия (colon:name), пробелы или символы Unicode, не требуют дополнительного экранирования помимо обычного заключения идентификаторов SQL в кавычки. При чтении столбцы сопоставляются без учёта регистра, поэтому запросы к столбцам, имена которых содержат прописные буквы или смешанный регистр (например, UserId), работают обычным образом.

Примечание о версиях

В версиях ветки 4.0 до 4.0.8 столбцы при чтении определялись по точному совпадению имён, поэтому таблицы Paimon и Iceberg с именами столбцов в смешанном регистре могли возвращать данные неверного столбца или приводить к сбою запроса. Это исправлено в 4.0.8.

Начиная с 4.1.5 явные команды REFRESH TABLE, REFRESH DATABASE и REFRESH CATALOG также инвалидируют соответствующие кэши метаданных Paimon. После внешних изменений схемы или удаления и повторного создания таблицы используйте команду обновления для повторной загрузки метаданных. Уже запущенные запросы сохраняют выбранный снимок.

Примеры​

Hive Metastore​

Версия 3.1+
CREATE CATALOG test_paimon_on_hms_hdfs_catalog PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = 'hms',
    'warehouse' = 'hdfs://127.0.0.1:8320/user/hive/warehouse',
    'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8320',
    'hadoop.username' = 'doris'
);
Версии 2.1 & 3.0

Доступ к HMS без аутентификации Kerberos

CREATE CATALOG paimon_hms_on_hdfs_catalog PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = 'hms',
    'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
    'warehouse' = 'hdfs://127.0.0.1:8320/user/paimon/warehouse/paimon-hms-hdfs-warehouse',
    'hadoop.username' = 'doris',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8320'
);

Доступ к HMS с включённой аутентификацией Kerberos

CREATE CATALOG paimon_hms_on_hdfs_kerberos_hdfs_catalog PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = 'hms',
    'warehouse' = 'hdfs://127.0.0.1:8520/paimon-hms-hdfs-warehouse',
    'hive.metastore.uris' = 'thrift://127.0.0.1:9583',
    'hive.metastore.kerberos.principal' = 'hive/hadoop-master@LABS.TERADATA.COM',
    'hive.metastore.sasl.enabled' = 'true',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8520',
    'hadoop.security.auth_to_local' = 'RULE:[2:\$1@\$0](.*@LABS.TERADATA.COM)s/@.*//
        RULE:[2:\$1@\$0](.*@OTHERLABS.TERADATA.COM)s/@.*//
        RULE:[2:\$1@\$0](.*@OTHERREALM.COM)s/@.*//
        DEFAULT',
    'hadoop.security.authentication' = 'kerberos',
    'hadoop.kerberos.principal' = 'hive/presto-master.docker.cluster@LABS.TERADATA.COM',
    'hadoop.kerberos.keytab' = '/keytabs/hive-presto-master.keytab'
);

Хранилище метаданных Aliyun DLF​

Версия 3.1+
CREATE CATALOG paimon_dlf_catalog PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = 'dlf',
    'warehouse' = 'oss://bucket/p2_regression_case',
    'dlf.uid' = '772905',
    'dlf.catalog_id' = 'p2_regression_case',
    'dlf.region' = 'cn-beijing',
    'dlf.endpoint' = 'dlf.cn-beijing.aliyuncs.com',
    'dlf.access_key' = '<ak>',
    'dlf.secret_key' = '<sk>'
);
Версии 2.1 & 3.0
CREATE CATALOG paimon_dlf_catalog PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = 'dlf',
    'warehouse' = 'oss://bucket/paimon-dlf-oss-warehouse',
    'dlf.uid' = '7716890',
    'dlf.catalog.id' = 'p2_regression_case',
    'dlf.region' = 'cn-beijing',
    'dlf.endpoint' = 'dlf.cn-beijing.aliyuncs.com',
    'dlf.access_key' = '<ak>',
    'dlf.secret_key' = '<sk>'
);

Хранилище метаданных FileSystem​

Версия 3.1+

Доступ к службам HMS и HDFS без аутентификации Kerberos

CREATE CATALOG ctl_test_paimon_catalog PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = 'filesystem',
    'warehouse' = 'hdfs://127.0.0.1:8020/user/doris/paimon1',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8020'
);
Версии 2.1 & 3.0

Доступ к службам HMS и HDFS без аутентификации Kerberos

CREATE CATALOG ctl_test_paimon_catalog PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = 'filesystem',
    'warehouse' = 'hdfs://127.0.0.1:8020/user/doris/paimon1',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8020'
);

Paimon JDBC Catalog​

Примечание

Это экспериментальная функция, поддерживаемая начиная с версии 4.1.0.

Версия 4.1+

Использование PostgreSQL для хранения метаданных с хранилищем S3

CREATE CATALOG paimon_jdbc_postgresql PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = 'jdbc',
    'paimon.jdbc.uri' = 'jdbc:postgresql://127.0.0.1:5432/paimon_db',
    'paimon.jdbc.user' = 'paimon_user',
    'paimon.jdbc.password' = 'password',
    'paimon.jdbc.driver_class' = 'org.postgresql.Driver',
    'paimon.jdbc.driver_url' = '<jdbc_driver_jar>',
    'warehouse' = 's3://bucket/warehouse',
    's3.access_key' = '<ak>',
    's3.secret_key' = '<sk>',
    's3.endpoint' = 'https://s3.us-east-1.amazonaws.com',
    's3.region' = 'us-east-1'
);

Операции записи​

Doris может создавать и изменять таблицы Paimon и записывать в них данные. Каждая успешная запись фиксируется как снимок Paimon. Если оператор завершается с ошибкой, Doris не публикует частичный снимок.

Перед началом работы​

Перед записью данных проверьте следующее:

  • На всех узлах FE и BE должна работать сборка Doris с поддержкой записи в Paimon. Не записывайте данные в Paimon во время поэтапного обновления, пока продолжают работать узлы BE со старой версией.
  • Учётные данные Catalog должны давать права на обновление хранилища метаданных, а также на создание, запись, переименование и удаление файлов в хранилище данных. Конкретные права зависят от хранилища метаданных и системы хранения.
  • Запись применима только к обычным таблицам данных Paimon. Системные таблицы Paimon и ссылки на таблицы с выбором ветви, тега, снимка или временной метки доступны только для чтения.

Поддерживаемый SQL​

ОперацияПоддержка и примечания
DDL баз данныхCREATE DATABASE и DROP DATABASE
DDL таблицCREATE TABLE, CREATE TABLE AS SELECT и DROP TABLE
Изменения схемыДобавление, удаление, переименование, изменение порядка и модификация столбцов
Добавление данныхINSERT INTO ... VALUES и INSERT INTO ... SELECT
Перезапись данныхINSERT OVERWRITE для всей таблицы, статических и динамических разделов
Изменения на уровне строкDELETE, UPDATE и MERGE INTO для таблиц с первичным ключом с учётом приведённых ниже ограничений

Быстрый старт​

Следующий пример создаёт таблицу с первичным ключом и записывает в неё данные. Параметры таблицы Paimon задаются в PROPERTIES; не добавляйте предложение Doris DISTRIBUTE BY.

SWITCH paimon_ctl;
CREATE DATABASE IF NOT EXISTS sales;
USE sales;

CREATE TABLE orders (
    order_id BIGINT NOT NULL,
    customer STRING NULL,
    amount DECIMAL(12, 2) NULL,
    status STRING NULL
) ENGINE=paimon
PROPERTIES (
    'primary-key' = 'order_id',
    'bucket' = '2',
    'bucket-key' = 'order_id'
);

INSERT INTO orders VALUES
    (1, 'Alice', 99.90, 'NEW'),
    (2, 'Bob', 35.00, 'NEW');

UPDATE orders
SET status = 'PAID'
WHERE order_id = 1;

DELETE FROM orders
WHERE order_id = 2;

SELECT * FROM orders ORDER BY order_id;

Результат:

+----------+----------+--------+--------+
| order_id | customer | amount | status |
+----------+----------+--------+--------+
|        1 | Alice    |  99.90 | PAID   |
+----------+----------+--------+--------+

Можно изменить схему таблицы через Doris, а затем продолжить запись с новой схемой:

ALTER TABLE orders ADD COLUMN note STRING NULL;
ALTER TABLE orders RENAME COLUMN note order_note;

Вставка и перезапись данных​

INSERT INTO добавляет строки в таблицу, поддерживающую только добавление, или объединяет строки в соответствии с параметрами Paimon таблицы с первичным ключом. Источником могут быть VALUES, внутренняя таблица Doris или другая внешняя таблица.

INSERT INTO paimon_ctl.sales.orders
SELECT order_id, customer, amount, status
FROM internal.sales.new_orders;

Для несекционированной таблицы INSERT OVERWRITE заменяет все существующие строки. Поэтому пустые входные данные приводят к пустой таблице.

INSERT OVERWRITE TABLE paimon_ctl.sales.orders
SELECT order_id, customer, amount, status
FROM internal.sales.orders_snapshot;

Для секционированной таблицы используйте одну из следующих форм:

-- Replace only the specified partition. The SELECT list omits the static partition column.
INSERT OVERWRITE TABLE paimon_ctl.sales.daily_orders
PARTITION (order_date = '2026-10-08')
SELECT order_id, customer, amount, status
FROM internal.sales.daily_orders_stage;

-- Dynamic overwrite replaces the partitions present in the input and keeps other partitions.
INSERT OVERWRITE TABLE paimon_ctl.sales.daily_orders
SELECT order_id, customer, amount, status, order_date
FROM internal.sales.daily_orders_stage;

Таблица с первичным ключом допускает вставку с пропуском неключевых столбцов только тогда, когда её merge-engine имеет значение partial-update. Для таблицы, поддерживающей только добавление, пропущенные столбцы получают значение по умолчанию или NULL, если это разрешено.

Удаление, обновление и слияние данных​

Изменения на уровне строк требуют таблицы Paimon с первичным ключом. Для таблицы с механизмом слияния deduplicate, используемым по умолчанию, Doris поддерживает следующие операции:

DELETE FROM paimon_ctl.sales.orders
WHERE order_id = 10;

UPDATE paimon_ctl.sales.orders
SET amount = amount * 0.9,
    status = 'DISCOUNTED'
WHERE order_id = 20;

MERGE INTO paimon_ctl.sales.orders t
USING internal.sales.order_changes s
ON t.order_id = s.order_id
WHEN MATCHED AND s.action = 'DELETE' THEN DELETE
WHEN MATCHED THEN UPDATE SET
    customer = s.customer,
    amount = s.amount,
    status = s.status
WHEN NOT MATCHED THEN INSERT (order_id, customer, amount, status)
    VALUES (s.order_id, s.customer, s.amount, s.status);

Следующие ограничения обусловлены тем, как Paimon применяет изменения строк:

  • UPDATE не может изменять столбец первичного ключа или столбец, настроенный через sequence.field.
  • UPDATE, включая действие обновления в MERGE, поддерживает только механизм слияния deduplicate и не поддерживает changelog-producer=input.
  • Обновление столбца секционирования требует таблицы с динамическими бакетами (bucket=-1) и ignore-delete=false.
  • DELETE, включая действие удаления в MERGE, требует ignore-delete=false. Механизм слияния deduplicate, используемый по умолчанию, поддерживает это напрямую. Для таблицы partial-update необходимо задать partial-update.remove-record-on-delete=true, а для таблицы aggregation необходимо задать aggregation.remove-record-on-delete=true.
  • Таблицы с настроенным rowkind.field не поддерживают эти операторы изменения на уровне строк. Таблица с динамическими бакетами и настроенным cross-partition-upsert.index-ttl также их не поддерживает.
  • Оператор MERGE подчиняется соответствующим ограничениям UPDATE и DELETE для содержащихся в нём действий.

Для предсказуемых результатов обеспечьте уникальность строк источника MERGE по ключу сопоставления. Doris отклоняет оператор, если несколько строк источника соответствуют одной строке целевой таблицы.

Примечания по эксплуатации​

  • Настраивайте первичные ключи, разделы, бакеты, механизмы слияния, форматы файлов, компактацию и другие физические характеристики через свойства таблицы Paimon. Doris проверяет эти параметры через Paimon SDK.
  • В настоящее время Doris не предоставляет универсальную операцию ALTER TABLE ... SET TBLPROPERTIES для таблиц Paimon. Чтобы изменить свойства таблицы после создания, используйте другой движок Paimon, а затем выполните REFRESH TABLE или REFRESH CATALOG в Doris.
  • Обеспечьте достаточно места на локальном диске каждого BE для выгрузки при записи и достаточные права в хранилище для работы с временными файлами и фиксации изменений. Параметр BE paimon_jni_writer_memory_pool_limit_bytes ограничивает пул памяти, используемый каждым средством записи Paimon JNI; его значение по умолчанию составляет 512 MB.
  • После успешной записи или изменения схемы новые операторы Doris загружают зафиксированный снимок Paimon. Уже выполняющиеся операторы продолжают использовать снимок, выбранный при их запуске.

Операции запросов​

Базовый запрос​

После настройки Catalog можно выполнять запросы к данным таблиц в Catalog следующим образом:

-- 1. Switch to catalog, use database, and query
SWITCH paimon_ctl;
USE paimon_db;
SELECT * FROM paimon_tbl LIMIT 10;

-- 2. Use Paimon database directly
USE paimon_ctl.paimon_db;
SELECT * FROM paimon_tbl LIMIT 10;

-- 3. Use fully qualified name to query
SELECT * FROM paimon_ctl.paimon_db.paimon_tbl LIMIT 10;

Столбцы метаданных файлов​

Поддерживается начиная с версии 4.2.0.

Doris предоставляет два скрытых столбца метаданных для таблиц данных Paimon. С их помощью можно определить физический файл данных и строку, из которых получена каждая строка результата запроса.

СтолбецТипОписание
__paimon_file_pathSTRING NOT NULLИсходный путь к файлу необработанных данных, возвращаемый Paimon.
__paimon_row_indexBIGINT NOT NULLФизическая позиция строки в полном файле данных, отсчитываемая от нуля.

Предварительные условия: настройте Paimon Catalog, как описано в предыдущих примерах, и создайте таблицу данных Paimon со столбцом id, использующую файлы Parquet или ORC. Следующий запрос предполагает, что paimon_tbl уже содержит строки со значениями id, равными 1 и 2:

SELECT id, `__paimon_file_path`, `__paimon_row_index`
FROM paimon_ctl.paimon_db.paimon_tbl
ORDER BY `__paimon_file_path`, `__paimon_row_index`;

Пример результата (путь к файлу зависит от расположения таблицы):

+----+------------------------------------------+--------------------+
| id | __paimon_file_path                       | __paimon_row_index |
+----+------------------------------------------+--------------------+
|  1 | s3://bucket/warehouse/db/table/a.parquet |                  0 |
|  2 | s3://bucket/warehouse/db/table/a.parquet |                  1 |
+----+------------------------------------------+--------------------+

По умолчанию эти столбцы не отображаются в SELECT * и DESC.

Чтобы включить скрытые столбцы в SELECT * и DESC, включите show_hidden_columns для сеанса:

SET show_hidden_columns = true;

Связанные переменные сеанса:

ПеременнаяТипПо умолчаниюОбязательноДействие
show_hidden_columnsBOOLEANfalseНетВключает скрытые столбцы в SELECT * и DESC. Не требуется при явном обращении к этим столбцам.
enable_file_scanner_v2BOOLEANtrueНетДолжна оставаться включённой, если запрос обращается к этим столбцам метаданных.
force_jni_scannerBOOLEANfalseНетДолжна оставаться отключённой, поскольку средство чтения JNI не может формировать эти столбцы метаданных.

Позиция строки определяется относительно полного физического файла. Фильтрация по предикатам, обработка векторов удаления и разбиение сканирования не изменяют нумерацию оставшихся строк. Поэтому сочетание __paimon_file_path и __paimon_row_index позволяет найти физическую запись в текущем снимке таблицы. Перезапись файлов данных или компактация могут изменить оба значения, поэтому их нельзя использовать как стабильный логический идентификатор строки.

предупреждение

Эти столбцы доступны только тогда, когда каждый блок сканирования Paimon, участвующий в запросе, может быть прочитан как файл необработанных данных нативным средством чтения Parquet или ORC в FileScannerV2. Запрос, обращающийся к ним, завершается с ошибкой при сканировании через JNI или смешанном нативном/JNI-сканировании, при отключённом enable_file_scanner_v2, при включённом force_jni_scanner или когда выбранные файлы данных нельзя прочитать нативным средством чтения Parquet/ORC.

__paimon_file_path и __paimon_row_index являются зарезервированными именами, сравниваемыми без учёта регистра. Не используйте их как имена физических столбцов в таблице Paimon.

Пакетный инкрементальный запрос​

Начиная с версии 3.1.0

Поддерживаются пакетные инкрементальные запросы к Paimon, аналогично Flink.

Поддерживаются запросы инкрементальных данных в заданных интервалах снимков или временных меток. Левая граница интервала включается, правая исключается.

-- between snapshots [0, 5)
SELECT * FROM paimon_table@incr('startSnapshotId'='0', 'endSnapshotId'='5');

-- between snapshots [0, 5) with specified scan mode
SELECT * FROM paimon_table@incr('startSnapshotId'='0', 'endSnapshotId'='5', 'incrementalBetweenScanMode'='diff');

-- read from start timestamp
SELECT * FROM paimon_table@incr('startTimestamp'='1750844949000');

-- read between timestamp
SELECT * FROM paimon_table@incr('startTimestamp'='1750844949000', 'endTimestamp'='1750944949000');

Параметры:

ПараметрОписаниеПример
startSnapshotIdИдентификатор начального снимка, должен быть больше 0. Необходимо задавать вместе с endSnapshotId.'startSnapshotId'='3'
endSnapshotIdИдентификатор конечного снимка, должен быть больше startSnapshotId. Необходимо задавать вместе с startSnapshotId.'endSnapshotId'='10'
incrementalBetweenScanModeЗадаёт режим инкрементального чтения, по умолчанию auto; поддерживаются delta, changelog и diff'incrementalBetweenScanMode'='delta'
startTimestampВременная метка начального снимка, должна быть больше или равна 0. Единица измерения: миллисекунда.'startTimestamp'='1750844949000'
endTimestampВременная метка конечного снимка, должна быть больше startTimestamp. Необязательный параметр; если не задан, чтение выполняется от startTimestamp до последнего снимка. Единица измерения: миллисекунда.'endTimestamp'='1750944949000'
Примечание

startSnapshotId и endSnapshotId образуют параметр Paimon 'incremental-between'='3,10'

startTimestamp и endTimestamp образуют параметр Paimon 'incremental-between-timestamp'='1750844949000,1750944949000'

incrementalBetweenScanMode соответствует параметру Paimon incremental-between-scan-mode.

Подробности об этих параметрах см. в документации Paimon.

Time Travel​

Начиная с версии 3.1.0

Поддерживается чтение указанных снимков таблиц Paimon.

По умолчанию запросы чтения обращаются только к последней версии снимков.

Просмотреть снимки указанной таблицы Paimon можно через табличную функцию $snapshots:

Doris > SELECT snapshot_id,commit_time FROM paimon_tbl$snapshots;
+-------------+-------------------------+
| snapshot_id | commit_time             |
+-------------+-------------------------+
|           1 | 2025-08-17 06:05:52.740 |
|           2 | 2025-08-17 06:05:52.979 |
|           3 | 2025-08-17 06:05:53.240 |
|           4 | 2025-08-17 06:05:53.561 |
+-------------+-------------------------+

Можно использовать конструкции FOR TIME AS OF и FOR VERSION AS OF для чтения данных исторической версии по идентификатору снимка или времени его создания. Примеры:

-- Notice: Before 3.1.1, only support format like YYYY-MM-DD HH:MM:SS.SSS
-- After 3.1.2, support YYYY-MM-DD HH:MM:SS and YYYY-MM-DD
SELECT * FROM paimon_tbl FOR TIME AS OF "2025-08-17 06:05:52.740";
SELECT * FROM paimon_tbl FOR TIME AS OF "2025-08-17 06:05:52";
SELECT * FROM paimon_tbl FOR TIME AS OF "2025-08-17";

-- Notice: The timestamp must be precise down to the millisecond.
SELECT * FROM paimon_tbl FOR TIME AS OF 1755381952740;
-- Use snapshot id
SELECT * FROM paimon_tbl FOR VERSION AS OF 1;

Time Travel с @options​

Для селекторов, специфичных для Paimon, используйте @options в ссылке на таблицу в запросе. Doris принимает scan.snapshot-id, scan.tag-name, scan.version, scan.timestamp, scan.timestamp-millis, scan.watermark, scan.file-creation-time-millis, scan.creation-time-millis и scan.mode. Выбранный снимок или тег также определяет историческую схему; Doris не привязывает последнюю схему к историческим данным.

-- Read snapshot 1 with the schema stored for snapshot 1.
SELECT id, old_name
FROM paimon_tbl@options('scan.snapshot-id' = '1');

-- A retained tag remains readable even after its ordinary snapshot expires.
SELECT id, old_name
FROM paimon_tbl@options('scan.tag-name' = 'tag1');

В ссылке на таблицу можно задать только один параметр начальной позиции. scan.mode можно сочетать с позицией только тогда, когда Paimon определяет эту пару как совместимую; например, scan.mode='from-creation-timestamp' требует scan.creation-time-millis. Неизвестный или просроченный снимок, ветвь или тег приводят к явной ошибке, а не к незаметному переходу на последнюю версию таблицы. Синтаксис @options поддерживается для ссылок на таблицы в запросах и может сохраняться в определении представления, но его нельзя применять к ссылке на CTE или командам, не являющимся запросами, таким как SHOW.

Ветви и теги​

Начиная с версии 3.1.0

Поддерживается чтение ветвей и тегов указанных таблиц Paimon.

Для просмотра ветвей и тегов таблиц Paimon можно использовать системные таблицы $branches и $tags:

Doris > SELECT * FROM paimon_tbl$branches;
+-------------+-------------------------+
| branch_name | create_time             |
+-------------+-------------------------+
| b_1         | 2025-08-17 06:34:37.294 |
| b_2         | 2025-08-17 06:34:37.297 |
+-------------+-------------------------+

Doris > SELECT * FROM paimon_tbl$tags;
+----------+-------------+-----------+-------------------------+--------------+-------------+---------------+
| tag_name | snapshot_id | schema_id | commit_time             | record_count | create_time | time_retained |
+----------+-------------+-----------+-------------------------+--------------+-------------+---------------+
| t_1      |           1 |         0 | 2025-08-17 06:05:52.740 |            3 | NULL        | NULL          |
| t_2      |           2 |         0 | 2025-08-17 06:05:52.979 |            6 | NULL        | NULL          |
| t_3      |           3 |         0 | 2025-08-17 06:05:53.240 |            9 | NULL        | NULL          |
| t_4      |           4 |         0 | 2025-08-17 06:05:53.561 |           12 | NULL        | NULL          |
+----------+-------------+-----------+-------------------------+--------------+-------------+---------------+

Для совместимости с такими системами, как Spark/Trino, поддерживаются различные формы синтаксиса:

-- BRANCH
SELECT * FROM paimon_tbl@branch(branch1);
SELECT * FROM paimon_tbl@branch("name" = "branch1");

-- TAG
SELECT * FROM paimon_tbl@tag(tag1);
SELECT * FROM paimon_tbl@tag("name" = "tag1");
SELECT * FROM paimon_tbl FOR VERSION AS OF 'tag1';

Для синтаксиса FOR VERSION AS OF Doris автоматически определяет, является ли параметр временной меткой

Системные таблицы​

Начиная с версии 3.1.0

Doris поддерживает запросы к системным таблицам Paimon для получения метаданных таблиц. Системные таблицы позволяют просматривать историю снимков, файлы манифестов, файлы данных, разделы и другую информацию.

Для доступа к метаданным таблицы Paimon добавьте символ $ после имени таблицы, а затем имя системной таблицы:

SELECT * FROM my_table$system_table_name;

Системные таблицы audit_log, binlog, manifests, partitions, ro, row_tracking и table_indexes принимают @options в ссылке на таблицу. Выбранный снимок или тег применяется к строкам системной таблицы, а для системных таблиц, предоставляющих столбцы исходной таблицы, также используется соответствующая историческая схема исходной таблицы:

SELECT rowkind, id, old_name
FROM paimon_tbl$audit_log@options('scan.tag-name' = 'tag1');

Другие системные таблицы отклоняют @options, поскольку не могут гарантировать, что каждый этап, формирующий строки, использует выбранный снимок. Системные таблицы Paimon также отклоняют scan.file-creation-time-millis: незаметное игнорирование этого фильтра файлов могло бы вернуть строки за пределами запрошенного диапазона.

Примечание

Doris не поддерживает чтение глобальных системных таблиц Paimon; они поддерживаются только во Flink.

schemas​

Показывает информацию о текущей и исторических схемах таблицы. При изменении схемы таблицы с помощью операторов ALTER TABLE, CREATE TABLE AS или CREATE DATABASE AS каждое изменение создаёт запись в таблице schemas:

SELECT * FROM my_table$schemas;

Результат:

+-----------+--------------------------------------------------------------------------------------------------------------------+----------------+--------------+---------+---------+-------------------------+
| schema_id | fields                                                                                                             | partition_keys | primary_keys | options | comment | update_time             |
+-----------+--------------------------------------------------------------------------------------------------------------------+----------------+--------------+---------+---------+-------------------------+
|         0 | [{"id":0,"name":"k","type":"INT NOT NULL"},{"id":1,"name":"f0","type":"INT"},{"id":2,"name":"f1","type":"STRING"}] | []             | ["k"]        | {}      |         | 2025-03-04 22:48:41.666 |
+-----------+--------------------------------------------------------------------------------------------------------------------+----------------+--------------+---------+---------+-------------------------+

snapshots​

Показывает информацию обо всех действующих снимках таблицы, включая время создания снимка, пользователя, зафиксировавшего изменения, тип операции и т. д.:

SELECT * FROM my_table$snapshots;

Результат:

+-------------+-----------+--------------------------------------+---------------------+-------------+-------------------------+------------------------------------------------------+------------------------------------------------------+-------------------------+--------------------+--------------------+------------------------+----------------------+
| snapshot_id | schema_id | commit_user                          | commit_identifier   | commit_kind | commit_time             | base_manifest_list                                   | delta_manifest_list                                  | changelog_manifest_list | total_record_count | delta_record_count | changelog_record_count | watermark            |
+-------------+-----------+--------------------------------------+---------------------+-------------+-------------------------+------------------------------------------------------+------------------------------------------------------+-------------------------+--------------------+--------------------+------------------------+----------------------+
|           1 |         0 | d7ea4996-92c7-469f-b9ff-c76525954f1c | 9223372036854775807 | APPEND      | 2025-03-04 22:48:45.575 | manifest-list-dc5490ba-420c-445a-b6f7-6962d394935c-0 | manifest-list-dc5490ba-420c-445a-b6f7-6962d394935c-1 | NULL                    |                  1 |                  1 |                      0 | -9223372036854775808 |
|           2 |         0 | 34de47f6-31d1-4f06-b378-c85ef4fbca41 | 9223372036854775807 | APPEND      | 2025-07-01 23:11:35.406 | manifest-list-dca6aa5b-6fc6-4b4f-ac22-acfa15bbf171-0 | manifest-list-dca6aa5b-6fc6-4b4f-ac22-acfa15bbf171-1 | NULL                    |                  2 |                  1 |                      0 | -9223372036854775808 |
|           3 |         0 | 89f67183-a1f8-4ee9-b73c-3f7e992b79a7 | 9223372036854775807 | APPEND      | 2025-07-01 23:11:45.114 | manifest-list-6d624d1b-c774-4d95-905e-8258a7b89ecb-0 | manifest-list-6d624d1b-c774-4d95-905e-8258a7b89ecb-1 | NULL                    |                  3 |                  1 |                      0 | -9223372036854775808 |
|           4 |         0 | 31924a7c-1389-490c-adf1-3bb805b33cd7 | 9223372036854775807 | APPEND      | 2025-07-01 23:12:42.042 | manifest-list-09097a51-afde-485e-929b-d2cc39eb6eb2-0 | manifest-list-09097a51-afde-485e-929b-d2cc39eb6eb2-1 | NULL                    |                  5 |                  2 |                      0 | -9223372036854775808 |
|           5 |         0 | 1e90a80b-41cb-4242-b97c-889728f76810 | 9223372036854775807 | APPEND      | 2025-07-01 23:14:26.445 | manifest-list-b8471969-9c4d-41cd-b790-64f6efb2d142-0 | manifest-list-b8471969-9c4d-41cd-b790-64f6efb2d142-1 | NULL                    |                  6 |                  1 |                      0 | -9223372036854775808 |
|           6 |         0 | 1e90a80b-41cb-4242-b97c-889728f76810 | 9223372036854775807 | COMPACT     | 2025-07-01 23:14:29.317 | manifest-list-b8471969-9c4d-41cd-b790-64f6efb2d142-2 | manifest-list-b8471969-9c4d-41cd-b790-64f6efb2d142-3 | NULL                    |                  5 |                 -1 |                      0 | -9223372036854775808 |
+-------------+-----------+--------------------------------------+---------------------+-------------+-------------------------+------------------------------------------------------+------------------------------------------------------+-------------------------+--------------------+--------------------+------------------------+----------------------+

options​

Показывает текущие параметры конфигурации таблицы. Если параметр таблицы не указан в этой системной таблице, для него используется значение по умолчанию:

SELECT * FROM my_table$options;

Результат:

+------------------------+--------------------+
|         key            |        value       |
+------------------------+--------------------+
| snapshot.time-retained |         5 h        |
+------------------------+--------------------+

files​

Показывает информацию обо всех файлах данных, на которые ссылается текущий снимок, включая формат файла, число записей, размер файла и т. д.:

SELECT * FROM my_table$files;

Результат:

mysql> SELECT * FROM my_table$files;
+-----------+--------+------------------------------------------------------------------------------------------------------------------------+-------------+-----------+-------+--------------+--------------------+---------+---------+-------------------+---------------------+---------------------+---------------------+---------------------+-------------------------+-------------+
| partition | bucket | file_path                                                                                                              | file_format | schema_id | level | record_count | file_size_in_bytes | min_key | max_key | null_value_counts | min_value_stats     | max_value_stats     | min_sequence_number | max_sequence_number | creation_time           | file_source |
+-----------+--------+------------------------------------------------------------------------------------------------------------------------+-------------+-----------+-------+--------------+--------------------+---------+---------+-------------------+---------------------+---------------------+---------------------+---------------------+-------------------------+-------------+
| {}        |      0 | s3://paimon-warehouse-dev/test-flink/cookbook.db/my_table/bucket-0/data-b4a49c57-6ef6-4c04-8813-07a4960d987c-0.parquet | parquet     |         0 |     5 |            5 |               1321 | [1]     | [6]     | {f0=0, f1=0, k=0} | {f0=4, f1=111, k=1} | {f0=11, f1=k7, k=6} |                   0 |                   5 | 2025-07-01 23:14:23.967 | COMPACT     |
+-----------+--------+------------------------------------------------------------------------------------------------------------------------+-------------+-----------+-------+--------------+--------------------+---------+---------+-------------------+---------------------+---------------------+---------------------+---------------------+-------------------------+-------------+

tags​

Показывает всю информацию о тегах таблицы, включая имена тегов и связанные снимки:

SELECT * FROM my_table$tags;

Результат:

+----------+-------------+-----------+-------------------------+--------------+--------------+
| tag_name | snapshot_id | schema_id |             commit_time | record_count |   branches   |
+----------+-------------+-----------+-------------------------+--------------+--------------+
|     tag1 |           1 |         0 | 2025-03-04 14:55:29.344 |            3 |      []      |
|     tag3 |           3 |         0 | 2025-03-04 14:58:24.691 |            7 |  [branch-1]  |
+----------+-------------+-----------+-------------------------+--------------+--------------+

branches​

Показывает информацию обо всех известных ветвях таблицы:

SELECT * FROM my_table$branches;

Результат:

+----------------------+-------------------------+
|          branch_name |             create_time |
+----------------------+-------------------------+
|              branch1 | 2025-03-04 20:31:39.084 |
|              branch2 | 2025-03-04 21:11:14.373 |
+----------------------+-------------------------+

consumers​

Показывает информацию о потребителях таблицы, используемую для отслеживания потребления данных:

SELECT * FROM my_table$consumers;

Результат:

+-------------+------------------+
| consumer_id | next_snapshot_id |
+-------------+------------------+
|         id1 |                1 |
|         id2 |                3 |
+-------------+------------------+

manifests​

Показывает информацию о файлах манифестов текущего снимка таблицы:

SELECT * FROM my_table$manifests;

Результат:

+-------------------------------------------------+-----------+-----------------+-------------------+-----------+---------------------+---------------------+
| file_name                                       | file_size | num_added_files | num_deleted_files | schema_id | min_partition_stats | max_partition_stats |
+-------------------------------------------------+-----------+-----------------+-------------------+-----------+---------------------+---------------------+
| manifest-3df9bb64-5c11-4aef-994e-d8717fedfc70-0 |      1949 |               1 |                 0 |         0 | {}                  | {}                  |
| manifest-d7eb4ec4-7238-478a-9ae6-91a4ccebd561-0 |      1946 |               1 |                 0 |         0 | {}                  | {}                  |
| manifest-3b6f4079-c893-4413-aedc-1e8fbcea6db1-0 |      1948 |               1 |                 0 |         0 | {}                  | {}                  |
| manifest-abe5177f-82da-4e86-9864-40efffb391bd-0 |      1964 |               1 |                 0 |         0 | {}                  | {}                  |
| manifest-ee89dff3-a523-4655-a4b8-d7c9e471a1d6-0 |      1949 |               1 |                 0 |         0 | {}                  | {}                  |
| manifest-ee89dff3-a523-4655-a4b8-d7c9e471a1d6-1 |      2232 |               1 |                 5 |         0 | {}                  | {}                  |
+-------------------------------------------------+-----------+-----------------+-------------------+-----------+---------------------+---------------------+

aggregation_fields​

Показывает информацию о полях агрегации таблицы, используемую для настройки полей в агрегатных таблицах:

SELECT * FROM my_table$aggregation_fields;

Результат:

+------------+--------------+----------+------------------+---------+
| field_name | field_type   | function | function_options | comment |
+------------+--------------+----------+------------------+---------+
| k          | INT NOT NULL | []       | []               | NULL    |
| f0         | INT          | []       | []               | NULL    |
| f1         | STRING       | []       | []               | NULL    |
+------------+--------------+----------+------------------+---------+

partitions​

Показывает информацию о разделах таблицы, включая общее число записей и суммарный размер файлов для каждого раздела:

SELECT * FROM my_table$partitions;

Результат:

+-----------+--------------+--------------------+------------+-------------------------+
| partition | record_count | file_size_in_bytes | file_count | last_update_time        |
+-----------+--------------+--------------------+------------+-------------------------+
| {}        |            5 |               1321 |          1 | 2025-07-01 23:14:23.967 |
+-----------+--------------+--------------------+------------+-------------------------+

buckets​

Показывает информацию о бакетах таблицы, включая статистику для каждого бакета:

SELECT * FROM my_table$buckets;

Результат:

+-----------+--------+--------------+--------------------+------------+-------------------------+
| partition | bucket | record_count | file_size_in_bytes | file_count | last_update_time        |
+-----------+--------+--------------+--------------------+------------+-------------------------+
| {}        |      0 |            5 |               1321 |          1 | 2025-07-01 23:14:23.967 |
+-----------+--------+--------------+--------------------+------------+-------------------------+

statistics​

Показывает статистическую информацию о таблице, включая число строк, размер данных и другие статистические показатели:

SELECT * FROM my_table$statistics;

Результат:

+--------------+------------+-----------------------+------------------+----------+
|  snapshot_id |  schema_id |     mergedRecordCount | mergedRecordSize |  colstat |
+--------------+------------+-----------------------+------------------+----------+
|            2 |          0 |              2        |         2        |    {}    |
+--------------+------------+-----------------------+------------------+----------+

table_indexes​

Показывает информацию об индексах таблицы:

SELECT * FROM my_table$table_indexes;

Результат:

+--------------------------------+-------------+--------------------------------+--------------------------------+----------------------+----------------------+--------------------------------+
|                      partition |      bucket |                     index_type |                      file_name |            file_size |            row_count |                      dv_ranges |
+--------------------------------+-------------+--------------------------------+--------------------------------+----------------------+----------------------+--------------------------------+
|                   {2025-03-01} |           0 |                           HASH | index-70abfebf-149e-4796-9f... |                   12 |                    3 |                         <NULL> |
|                   {2025-04-01} |           0 |               DELETION_VECTORS | index-633857e7-cdce-47d2-87... |                   33 |                    1 | [(data-346cb9c8-4032-4d66-a... |
+--------------------------------+-------------+--------------------------------+--------------------------------+----------------------+----------------------+--------------------------------+

Примеры использования системных таблиц​

С помощью системных таблиц можно легко выполнять следующие операции и задачи мониторинга.

Просмотр информации о последнем снимке таблицы для понимания её текущего состояния​

SELECT snapshot_id, commit_time, commit_kind, total_record_count FROM catalog_sales$snapshots ORDER BY snapshot_id DESC;

Результат:

+-------------+-------------------------+-------------+--------------------+
| snapshot_id | commit_time             | commit_kind | total_record_count |
+-------------+-------------------------+-------------+--------------------+
|           1 | 2025-07-01 21:21:54.179 | APPEND      |           14329288 |
+-------------+-------------------------+-------------+--------------------+

Просмотр информации о таблице для снимков​

SELECT s.snapshot_id, t.schema_id, t.fields FROM store_sales$snapshots s JOIN store_sales$schemas t ON s.schema_id=t.schema_id;

Результат:

+-------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| snapshot_id | schema_id | fields                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+-------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|           1 |         0 | [{"id":0,"name":"ss_sold_date_sk","type":"INT"},{"id":1,"name":"ss_item_sk","type":"INT NOT NULL"},{"id":2,"name":"ss_ticket_number","type":"INT NOT NULL"},{"id":3,"name":"ss_sold_time_sk","type":"INT"},{"id":4,"name":"ss_customer_sk","type":"INT"},{"id":5,"name":"ss_cdemo_sk","type":"INT"},{"id":6,"name":"ss_hdemo_sk","type":"INT"},{"id":7,"name":"ss_addr_sk","type":"INT"},{"id":8,"name":"ss_store_sk","type":"INT"},{"id":9,"name":"ss_promo_sk","type":"INT"},{"id":10,"name":"ss_quantity","type":"INT"},{"id":11,"name":"ss_wholesale_cost","type":"DECIMAL(7, 2)"},{"id":12,"name":"ss_list_price","type":"DECIMAL(7, 2)"},{"id":13,"name":"ss_sales_price","type":"DECIMAL(7, 2)"},{"id":14,"name":"ss_ext_discount_amt","type":"DECIMAL(7, 2)"},{"id":15,"name":"ss_ext_sales_price","type":"DECIMAL(7, 2)"},{"id":16,"name":"ss_ext_wholesale_cost","type":"DECIMAL(7, 2)"},{"id":17,"name":"ss_ext_list_price","type":"DECIMAL(7, 2)"},{"id":18,"name":"ss_ext_tax","type":"DECIMAL(7, 2)"},{"id":19,"name":"ss_coupon_amt","type":"DECIMAL(7, 2)"},{"id":20,"name":"ss_net_paid","type":"DECIMAL(7, 2)"},{"id":21,"name":"ss_net_paid_inc_tax","type":"DECIMAL(7, 2)"},{"id":22,"name":"ss_net_profit","type":"DECIMAL(7, 2)"}] |
|           2 |         0 | [{"id":0,"name":"ss_sold_date_sk","type":"INT"},{"id":1,"name":"ss_item_sk","type":"INT NOT NULL"},{"id":2,"name":"ss_ticket_number","type":"INT NOT NULL"},{"id":3,"name":"ss_sold_time_sk","type":"INT"},{"id":4,"name":"ss_customer_sk","type":"INT"},{"id":5,"name":"ss_cdemo_sk","type":"INT"},{"id":6,"name":"ss_hdemo_sk","type":"INT"},{"id":7,"name":"ss_addr_sk","type":"INT"},{"id":8,"name":"ss_store_sk","type":"INT"},{"id":9,"name":"ss_promo_sk","type":"INT"},{"id":10,"name":"ss_quantity","type":"INT"},{"id":11,"name":"ss_wholesale_cost","type":"DECIMAL(7, 2)"},{"id":12,"name":"ss_list_price","type":"DECIMAL(7, 2)"},{"id":13,"name":"ss_sales_price","type":"DECIMAL(7, 2)"},{"id":14,"name":"ss_ext_discount_amt","type":"DECIMAL(7, 2)"},{"id":15,"name":"ss_ext_sales_price","type":"DECIMAL(7, 2)"},{"id":16,"name":"ss_ext_wholesale_cost","type":"DECIMAL(7, 2)"},{"id":17,"name":"ss_ext_list_price","type":"DECIMAL(7, 2)"},{"id":18,"name":"ss_ext_tax","type":"DECIMAL(7, 2)"},{"id":19,"name":"ss_coupon_amt","type":"DECIMAL(7, 2)"},{"id":20,"name":"ss_net_paid","type":"DECIMAL(7, 2)"},{"id":21,"name":"ss_net_paid_inc_tax","type":"DECIMAL(7, 2)"},{"id":22,"name":"ss_net_profit","type":"DECIMAL(7, 2)"}] |
+-------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Просмотр распределения данных по бакетам​

SELECT `bucket`, COUNT(*) as file_count, SUM(file_size_in_bytes)/1024/1024 as total_size_mb FROM paimon_s3.tpcds.catalog_sales$files GROUP BY `bucket` ORDER BY total_size_mb;
Примечание

Многие поля в системных таблицах Paimon являются ключевыми словами в Doris, поэтому их необходимо заключать в обратные кавычки.

Результат:

+--------+------------+--------------------+
| bucket | file_count | total_size_mb      |
+--------+------------+--------------------+
|     35 |          1 | 12.144722938537598 |
|     81 |          1 | 12.143454551696777 |
|     37 |          1 |  12.14071273803711 |
|     36 |          1 | 12.139023780822754 |
|     63 |          1 | 12.137332916259766 |
|      7 |          1 | 12.122495651245117 |
|     15 |          1 | 12.117934226989746 |
|     11 |          1 | 12.116133689880371 |
|     12 |          1 |  12.11155891418457 |
|     46 |          1 | 12.111005783081055 |
+--------+------------+--------------------+

Приложение​

Часто задаваемые вопросы​

1. Could not find a file io implementation for scheme 's3a' in the classpath

В версиях до 3.1 при использовании HMS для хранения метаданных и протокола 's3a' или 's3' на стороне хранилища возникает следующая ошибка:

java.io.UncheckedIOException: org.apache.paimon.fs.UnsupportedSchemeException: Could not find a file io implementation for scheme 's3a' in the classpath. Hadoop FileSystem also cannot access this path 's3a://`.

Версии до 3.1

Версии до 3.1 не поддерживают протокол s3a. Если его использование необходимо, в качестве временного обходного решения можно добавить параметры, связанные с s3a.

Версия 3.1 и выше

Начиная с версии 3.1 явно добавлять параметры s3a больше не требуется. Если нужно переопределить параметры хранилища Paimon, можно добавить параметры с префиксом paimon.fs.. Поскольку Paimon внутри использует HDFS API, поддерживаются все параметры fs.s3a.*.

Например:

CREATE CATALOG `paimon_hms_on_s3a` PROPERTIES (
    "type" = "paimon",
    "paimon.catalog.type" = "hms",
    "hive.metastore.uris" = "thrift://172.20.48.119:9383",
    "warehouse" = "s3a://bucket/paimon_warehouse",
    "s3.access_key" = "<ak>",
    "s3.secret_key" = "<sk>",
    "s3.region" = "ap-east-1",
    "s3.endpoint" = "https://s3.ap-east-1.amazonaws.com",
    -- Explicitly add s3a parameters
    "fs.s3a.access.key" = "<ak>",
    "fs.s3a.secret.key" = "<sk>",
    "fs.s3a.endpoint.region" = "ap-east-1",
    "fs.s3a.endpoint" = "https://s3.ap-east-1.amazonaws.com",
    "fs.s3a.impl" = "org.apache.hadoop.fs.s3a.S3AFileSystem"
);

При использовании протокола s3 необходимо явно добавить параметры Paimon, связанные с S3, то есть добавить префикс paimon.. Например:

CREATE CATALOG test_paimon_on_hms_aws_catalog PROPERTIES (
    'type' = 'paimon',
    'paimon.catalog.type' = 'hms',
    'warehouse' = 's3://bucket-hk/paimon_warehouse',
    'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
    's3.region' = 'ap-east-1',
    's3.endpoint' = 'https://s3.ap-east-1.amazonaws.com',
    's3.access_key' = '<ak>',
    's3.secret_key' = '<sk>',
    -- Explicitly add Paimon S3 parameters
    'paimon.s3.region' = 'ap-east-1',
    'paimon.s3.endpoint' = 'ap-east-1',
    'paimon.s3.access-key' = '<ak>',
    'paimon.s3.secret-key' = '<sk>'
);
Report issue
На этой странице