大网数据广告活动
数据库部署与 SQL 参考

Apache Doris 中文参考:Paimon Catalog

· 52CE 我爱测

Doris 在访问 Paimon 元数据时,会部分使用 Paimon Java SDK,因此可能有一些自定义参数需要透传给 Paimon Java SDK。可以使用以下前缀:

Doris 支持通过多种元数据服务访问 Paimon 表元数据,并对 Paimon 数据进行读写。

使用 Docker 快速体验 Apache Doris & Paimon

适用场景

场景 说明
查询加速 利用 Doris 分布式计算引擎,直接访问 Paimon 数据进行查询加速。
数据集成 读取 Paimon 数据并写入到 Doris 内表。或通过 Doris 计算引擎进行 ZeroETL 操作。
数据写回 使用 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:使用阿里云 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 相关的属性。

    Doris 在访问 Paimon 元数据时,会部分使用 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> 为 Doris 查询设置默认值,也可以通过 table@options('<option-key>'='<value>') 仅覆盖单个表引用。这些参数只影响 Doris 读取,不会修改物理 Paimon 表的元数据。

    Paimon 参数 Paimon 默认值 Doris 接受的值 作用
    read.batch-size 1024 1 到 65536 的整数 Paimon JNI Reader 每批请求的行数。Doris 打开 Reader 时会保留显式配置的值。
    file-reader-async-threshold 10 MB 1 MB 到 1 GB 的内存大小 Paimon JNI Reader 切换为异步文件读取的文件大小阈值。
    file-index.read.enabled true 布尔值 是否在读取时启用 Paimon 文件索引裁剪。
    source.split.target-size 128 MB 正数内存大小 Paimon 将数据文件组合成 Doris 扫描 split 时使用的目标大小。
    source.split.open-file-cost 4 MB 非负内存大小 Paimon 组合文件生成 split 时估算的文件打开成本。
    scan.manifest.parallelism 可用处理器数量 1 到 256 的整数 请求的 Manifest 读取并行度。执行时,Doris 会分别限制每个规划分支,实际值不超过配置值、256 以及执行规划的 FE 或 BE 的可用处理器数量三者中的最小值。
    scan.plan-sort-partition false 布尔值 是否在 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;
    

    参数优先级从高到低为:

    表引用 @options > Doris Catalog 属性 > 物理 Paimon 表参数 > Paimon 默认值
    

    Doris 会在应用上述优先级后校验最终值。因此,合法的 Catalog 或表引用参数可以覆盖物理表中的非法值; 如果最终值仍然非法,Doris 会在受影响的规划或 Reader 阶段开始前拒绝查询。Manifest 限制还会在分区、 行数/统计信息、fallback 分支和系统表的 Manifest 规划前生效。

    表中的前五个参数不会改变元数据选择,可以复用已缓存的最新分区投影。 scan.manifest.parallelism 和 scan.plan-sort-partition 会影响元数据规划,因此 Doris 使用当前表引用的 最终 Table Handle 进行规划。查询级参数不会调整 Paimon JVM 全局 Executor 的大小。

    Doris 会在 CREATE CATALOG 和 ALTER CATALOG 时拒绝未知或非法的 paimon.table-option.* 属性。ALTER CATALOG 会先校验完整的候选配置,再发布修改,因此失败后旧的 Catalog 配置仍然生效。旧 Doris 版本持久化的 Catalog 仍可加载,但不受支持或非法的历史 Reader 参数只会被忽略, 不会被应用;原始值仍会保留,以兼容 image 和 edit log。

    快照和启动位置参数属于表引用上下文选择器,必须使用通过 @options 进行时间旅行 中介绍的语法,不能配置为 Catalog 默认值。Doris 也不支持仅供 Paimon Flink Source Enumerator 使用的 scan.max-splits-per-task,以及 scan.fallback-branch、流式 Source、表布局、写入和 Compaction 参数。 Bucket、Primary Key、Partition、Merge Engine 等物理表行为应配置为 Paimon 表属性,也可以在 Doris CREATE TABLE ... PROPERTIES 中指定。

    在同一条语句内,Doris 会让 Schema 绑定、分区加载、行数/统计信息收集、系统表规划和数据扫描使用同一个 Paimon 快照与表版本。通过 @options 选择快照或 Tag 时,会使用该历史版本对应的 Schema,包括嵌套的 STRUCT、MAP 和 ARRAY 字段。预处理语句每次执行都会获取新的语句状态,因此两次执行之间的新提交会按照 新一次执行的选择器和缓存配置决定是否可见。

    为保障运维安全,Paimon Scanner 的 DEBUG 配置日志只输出批大小和投影字段数量;Doris 不会输出可能包含凭据的 原始 Scanner 参数 Map。Profile 指标 PaimonJniAsyncReaderThreadCount 在所有 Scanner 间按一秒周期采样, 因此可能最多滞后一秒;采样不会影响查询执行或调度。Reader 和 IOManager 会独立清理,部分关闭失败后可以安全重试。

    Paimon JNI IOManager

    对于 Paimon 主键表,JNI merge read 可能需要对多个文件中的数据进行排序和合并。可以启用 Paimon IOManager,将中间数据 spill 到 BE 本地磁盘,以降低大数据量 merge read 的内存压力。

    参数 是否必填 默认值 说明
    paimon.jni.enable_jni_io_manager 否 false 是否为 JNI 读取启用 Paimon IOManager。只有设置为 true 时,其他 IOManager 参数才会生效。
    paimon.jni.io_manager.tmp_dir 否 <storage_root_path>/paimon_jni_scanner_io_tmp Paimon IOManager 存放临时 spill 文件的本地目录。多个目录可以使用逗号或冒号分隔。未配置时,Doris 会在 BE 的每个存储路径下创建一个目录。
    paimon.jni.io_manager.impl_class 否 Paimon 默认实现 自定义 org.apache.paimon.disk.IOManager 实现的完整类名。该类必须存在于每个 BE 的 Paimon JNI Scanner classpath 中。

    以下示例启用 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 不会强制所有 merge read 都进行 spill。只有 merge reader 数量超过 Paimon 的 sort-spill-threshold 时才会触发 spill。该参数不是 Doris 动态 Reader 参数;如需改变 spill 行为, 应在物理 Paimon 表中配置。

    如果需要使用专用 spill 磁盘,可以配置每个 BE 上均存在或可以创建的本地路径:

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

    Doris 会为每个 JNI Scanner 创建一个 IOManager,并在 Scanner 关闭时一同关闭。需要确保配置的目录 可写,并为并发查询预留足够空间。配置自定义实现类时,该类必须提供以 String[] 为参数的 public 构造方法、以 String 为参数的 public 构造方法,或 public 无参构造方法。如果类加载或实例化失败, 查询会失败。

    这些参数只影响使用 JNI 路径读取 Paimon 数据表的场景,不影响 Native 读取。 paimon.table-option.file-reader-async-threshold 是独立参数,用于控制 Paimon 文件异步读取的阈值, 不会启用 IOManager,也不会配置 spill 目录。

  • {CommonProperties}

    CommonProperties 部分用于填写通用属性。请参阅数据目录概述中【通用属性】部分。

元数据缓存 {#meta-cache}

为了提升访问外部数据源的性能,Apache Doris 会缓存 Paimon 的元数据,包括指定 Snapshot 下的表结构、最新 Snapshot ID 以及派生的分区投影。

Doris 4.1.x 之前的版本,元数据缓存主要由 FE 配置项全局控制,详见元数据缓存。 自 Doris 4.1.x 起,Paimon Catalog 的外表元数据缓存使用统一的 meta.cache.* 键配置。下文的模块描述当前版本;Doris 4.1.x 和 4.2.x 的模块集合与此不同,见本页的 4.x 版本。

缓存属性配置 {#meta-cache-unified-model}

每个缓存模块使用统一的配置键格式:meta.cache.<engine>.<entry>.{enable,ttl-second,capacity,max-weight}。Paimon 的 <engine> 为 paimon。meta.cache.paimon.table.ttl-second 控制最新 Snapshot 缓存和表结构缓存的 TTL。

属性 示例 含义
enable true/false 是否开启该缓存模块。
ttl-second 600、0、-1 0 表示关闭该模块(立即生效,可用于查看最新数据);-1 表示永不过期;其他正整数表示按访问时间计算的 TTL 秒数。
capacity 10000 缓存条目数上限。0 表示关闭该模块。
max-weight 1GB 自 Doris 4.1.4 起支持。可选的模块估算保留内存上限。必须为正数,0 会被拒绝。只有下表标注的模块接受该属性。

生效逻辑: 模块在 enable=true、ttl-second != 0 且 capacity > 0 时生效。FE 总上限、Catalog 上限或模块上限存在时,还会按估算内存控制准入,详见 外表元数据缓存内存管理。

缓存模块 {#meta-cache-unified-modules}

以下模块拥有独立配置键并接受 max-weight:

模块(<entry>) 属性键前缀 ENTRY_NAME 缓存内容与影响 默认 enable / TTL / capacity
partition_view meta.cache.paimon.partition_view. paimon.partition-view 由表快照派生的分区投影。影响:减少规划阶段重复扫描分区。 true / 86400 秒 / 1000

以下缓存没有 <entry> 名,只受 Catalog 和 FE 总内存上限约束:

ENTRY_NAME 缓存内容 TTL / capacity
paimon-schema-at 表在指定 Snapshot 下的 Schema 不过期 / 10000
paimon-latest-snapshot 表的最新 Snapshot ID meta.cache.paimon.table.ttl-second(86400 秒)/ 1000

Paimon 表的列结构由共享的 default 引擎缓存(meta.cache.default.schema.*)。

旧参数映射与转换 {#meta-cache-mapping}

旧属性键 统一键 说明
schema.cache.ttl-second meta.cache.default.schema.ttl-second 表结构缓存的过期时间

最佳实践 {#meta-cache-best-practices}

  • 实时访问最新数据:希望每次查询都看到 Paimon 表的最新 Snapshot 时,将 meta.cache.paimon.table.ttl-second 设为 0。
    -- 关闭最新 Snapshot 缓存,感知 Paimon 表的最新快照
    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 内存上限生效时,默认关闭 Paimon SDK 自带的 CachingCatalog,避免出现第二份不计入配额的元数据缓存;显式配置 paimon.cache-enabled 时以用户配置为准。

可观测性 {#meta-cache-unified-observability}

可以通过 information_schema.catalog_meta_cache_statistics 系统表观察缓存指标。ENTRY_NAME 显示上表中列出的名称,default 引擎的行是所有 Catalog 共享的表结构缓存:

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 版本所支持的服务类型和参数略有区别,请参考【基础示例】章节。

支持的数据格式

列类型映射

请参阅Paimon 与 Doris 数据类型映射,了解 Doris 4.2 的完整映射表、精度和不支持的类型。

在两个 Paimon JNI Scanner 路径上,Doris 都会保留带引号的顶层列名和嵌套 STRUCT 字段名的原始大小写与字符。 包含逗号(region,code)、井号(nested#value)、冒号(colon:name)、空格或 Unicode 字符的名称,除普通 SQL 标识符引用外无需额外转义。读取时列按不区分大小写的方式匹配,因此含大写字母或大小写混合的列名(如 UserId)可以正常查询。

4.0.8 之前的 4.0.x 版本在读取时按精确匹配定位列,含大小写混合列名的 Paimon / Iceberg 表可能读到错误的列或查询失败。该问题已在 4.0.8 中修复。

自 4.1.5 版本起,显式执行 REFRESH TABLE、REFRESH DATABASE 或 REFRESH CATALOG 时,也会使 Paimon 的相应元数据缓存失效。外部表结构变更、删除后重建等操作后,可用刷新命令重新加载元数据;已开始执行的查询仍使用其已选定的快照。

基础示例

Hive Metastore

3.1+ 版本


    
        ```sql
        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'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_hms_aws_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'warehouse' = 's3://bucket/paimon_warehouse',
            's3.region' = 'ap-east-1',
            's3.endpoint' = 'https://s3.ap-east-1.amazonaws.com',
            's3.access_key' = '<ak>',
            's3.secret_key' = '<sk>'
        );
        ```

        使用 IAM Assumed Role 的方式获取 S3 访问凭证 (3.1.2+)

        ```sql
        CREATE CATALOG paimon_hms_on_s3_iamrole PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 's3://bucket/warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            's3.region' = 'us-east-1',
            's3.role_arn' = 'arn:aws:iam::543815668950:role/role'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_hms_ali_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'warehouse' = 'oss://bucket/regression/paimon_warehouse',
            'oss.region' = 'cn-beijing',
            'oss.endpoint' = 'oss-cn-beijing.aliyuncs.com',
            'oss.access_key' = '<ak>',
            'oss.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_hms_tx_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 'cosn://bucket/paimon_warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'cos.region' = 'ap-beijing',
            'cos.endpoint' = 'cos.ap-beijing.myqcloud.com',
            'cos.access_key' = '<ak>',
            'cos.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_hms_hw_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 'obs://bucket/regression/paimon_warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'obs.region' = 'cn-north-4',
            'obs.endpoint' = 'obs.cn-north-4.myhuaweicloud.com',
            'obs.access_key' = '<ak>',
            'obs.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG `paimon_on_gcs` PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 'gs://bucket/paimon_warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'fs.gcs.support' = 'true',
            'gs.secret_key' = '<sk>',
            'gs.access_key' = '<ak>'
        );
        ```
    
    
        自 4.0.4 起支持
        ```sql
        CREATE CATALOG paimon_hms_on_ozone_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 's3a://test-bucket/paimon-warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'fs.ozone.support' = 'true',
            'ozone.endpoint' = 'http://ozone-s3g:9878',
            'ozone.access_key' = '<ak>',
            'ozone.secret_key' = '<sk>',
            'ozone.region' = 'us-east-1',
            'ozone.use_path_style' = 'true'
        );
        ```
    
    
        ```sql
        CREATE CATALOG paimon_hms_on_minio_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 's3://test-bucket/paimon-warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'fs.minio.support' = 'true',
            'minio.endpoint' = 'http://127.0.0.1:19000',
            'minio.access_key' = 'minioadmin',
            'minio.secret_key' = 'minioadmin',
            'minio.use_path_style' = 'true'
        );
        ```
    




2.1 & 3.0 版本

    
        访问未开启 Kerberos 认证的 HMS
        ```sql
        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'
        );
        ```
        访问开启 Kerberos 认证的 HMS
        ```sql
        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'
        );
        ```
    
    
        ```sql
        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',
            'paimon.s3.region' = 'ap-east-1',
            's3.endpoint' = 'https://s3.ap-east-1.amazonaws.com',
            'paimon.s3.endpoint' = 'ap-east-1',
            's3.access_key' = '<ak>',
            'paimon.s3.access-key' = '<ak>',
            's3.secret_key' = '<sk>',
            'paimon.s3.secret-key' = '<sk>'    
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_hms_ali_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 'oss://bucket/regression/paimon_warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'oss.region' = 'cn-beijing',
            'oss.endpoint' = 'oss-cn-beijing.aliyuncs.com',
            'oss.access_key' = '<ak>',
            'oss.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_hms_tx_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 'cosn://bucket/paimon_warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'cos.region' = 'ap-beijing',
            'cos.endpoint' = 'cos.ap-beijing.myqcloud.com',
            'cos.access_key' = '<ak>',
            'cos.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_hms_hw_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 'obs://bucket/regression/paimon_warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            'obs.region' = 'cn-north-4',
            'obs.endpoint' = 'obs.cn-north-4.myhuaweicloud.com',
            'obs.access_key' = '<ak>',
            'obs.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_hms_minio_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'hms',
            'warehouse' = 's3://bucket/paimon-warehouse',
            'hive.metastore.uris' = 'thrift://127.0.0.1:9383',
            's3.endpoint' = 'http://127.0.0.1:19000',
            'paimon.s3.endpoint' = 'http://127.0.0.1:19000',
            's3.access_key' = '<ak>',
            'paimon.s3.access-key' = '<ak>',
            's3.secret_key' = '<sk>',
            'paimon.s3.secret-key' = '<sk>',    
            's3.path.style.access' = 'true'
        );
        ```

Aliyun DLF Metastore

3.1+ 版本


    
        ```sql
        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>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG paimon_dlf_test PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'rest',
            'uri' = 'http://cn-beijing-vpc.dlf.aliyuncs.com',
            'warehouse' = 'new_dfl_paimon_catalog',
            'paimon.rest.token.provider' = 'dlf',
            'paimon.rest.dlf.access-key-id' = '<ak>',
            'paimon.rest.dlf.access-key-secret' = '<sk>'
        );
        ```
    




2.1 & 3.0 版本


    
        ```sql
        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 Metastore

3.1+ 版本


    
        访问未开启 Kerberos 认证的 HMS 和 HDFS 服务
        ```sql
        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'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_fs_aws_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 's3://bucket/paimon_warehouse',
            's3.region' = 'ap-east-1',
            's3.endpoint' = 'https://s3.ap-east-1.amazonaws.com',
            's3.access_key' = '<ak>',
            's3.secret_key' = '<sk>'
        );
        ```

        使用 IAM Assumed Role 的方式获取 S3 访问凭证 (3.1.2+)

        ```sql
        CREATE CATALOG paimon_fs_on_s3_iamrole PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 's3://bucket/warehouse',
            's3.region' = 'us-east-1',
            's3.role_arn' = 'arn:aws:iam::543815668950:role/role'
        );
        ```    
    
    
        使用 OSS
        ```sql
        CREATE CATALOG paimon_base_filesystem_paimon_oss PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 'oss://bucket/regression/paimon1',
            'oss.region'='cn-beijing',
            'oss.endpoint'='oss-cn-beijing.aliyuncs.com',
            'oss.access_key'='<ak>',
            'oss.secret_key'='<sk>'
        );
        ```

        使用 OSS-HDFS

        ```sql
        CREATE CATALOG paimon_base_filesystem_paimon_oss_hdfs PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 'oss://bucket/regression/paimon1',
            'fs.oss-hdfs.support' = 'true',
            'oss.hdfs.access_key' = '<ak>',
            'oss.hdfs.secret_key' = '<sk>',
            'oss.hdfs.endpoint' = 'cn-beijing.oss-dls.aliyuncs.com',
            'oss.hdfs.region' = 'cn-beijing'
        );
        ```
    
    
        ```sql
        CREATE CATALOG paimon_base_filesystem_paimon_cosn PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 'cosn://bucket/regression/paimon1',
            'cos.region' = 'ap-beijing',
            'cos.endpoint' = 'cos.ap-beijing.myqcloud.com',
            'cos.access_key' = '<ak>',
            'cos.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG paimon_base_filesystem_paimon_obs PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 'obs://bucket/regression/paimon1',
            'obs.region' = 'cn-north-4',
            'obs.endpoint' = 'obs.cn-north-4.myhuaweicloud.com',
            'obs.access_key' = '<ak>',
            'obs.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG paimon_on_gcs_s3_fs PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 's3://bucket/paimon_warehouse',
            'fs.gcs.support' = 'true',
            'gs.secret_key' = '<sk>',
            'gs.access_key' = '<ak>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_minio_minio PROPERTIES (
            'type' = 'paimon',
            'warehouse' = 's3://warehouse/wh',
            'fs.minio.support' = 'true',
            'minio.endpoint' = 'http://127.0.0.1:19001',
            'minio.access_key' = 'admin',
            'minio.secret_key' = 'password',
            'minio.use_path_style' = 'true'
        );
        ```
    




2.1 & 3.0

    
        访问未开启 Kerberos 认证的 HMS 和 HDFS 服务
        ```sql
        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'
        );
        ```
    
    
        ```sql
        CREATE CATALOG test_paimon_on_fs_aws_catalog PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 's3://bucket/paimon_warehouse',
            's3.region' = 'ap-east-1',
            's3.endpoint' = 'https://s3.ap-east-1.amazonaws.com',
            's3.access_key' = '<ak>',
            's3.secret_key' = '<sk>'
        );
        ```
    
    
        使用 OSS

        ```sql
        CREATE CATALOG paimon_base_filesystem_paimon_oss PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 'oss://bucket/regression/paimon1',
            'oss.region'='cn-beijing',
            'oss.endpoint'='oss-cn-beijing.aliyuncs.com',
            'oss.access_key'='<ak>',
            'oss.secret_key'='<sk>'
        );
        ```

        使用 OSS-HDFS

        ```sql
        CREATE CATALOG paimon_base_filesystem_paimon_oss_hdfs PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 'oss://bucket/regression/paimon1',
            'oss.hdfs.enabled' = 'true',
            'oss.access_key' = 'your-access-key',
            'oss.secret_key' = 'your-secret-key',
            'oss.endpoint' = 'cn-hangzhou.oss-dls.aliyuncs.com',
            'oss.region' = 'cn-hangzhou'
        );
        ```
    
    
        ```sql
        CREATE CATALOG paimon_base_filesystem_paimon_cosn PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 'cosn://bucket/regression/paimon1',
            'cos.region' = 'ap-beijing',
            'cos.endpoint' = 'cos.ap-beijing.myqcloud.com',
            'cos.access_key' = '<ak>',
            'cos.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG paimon_base_filesystem_paimon_obs PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'filesystem',
            'warehouse' = 'obs://bucket/regression/paimon1',
            'obs.region' = 'cn-north-4',
            'obs.endpoint' = 'obs.cn-north-4.myhuaweicloud.com',
            'obs.access_key' = '<ak>',
            'obs.secret_key' = '<sk>'
        );
        ```
    
    
        ```sql
        CREATE CATALOG paimon_base_filesystem_paimon_minio PROPERTIES (
            'type' = 'paimon',
            'warehouse' = 's3://warehouse/wh',
            'paimon.catalog.type' = 'filesystem',
            's3.endpoint' = 'http://127.0.0.1:19001',
            's3.access_key' = '<ak>',
            's3.secret_key' = '<sk>',
            's3.path.style.access' = 'true'
        );
        ```

Paimon JDBC Catalog

该功能为试验功能,自 4.1.0 版本支持。

4.1+ 版本

    
        使用 PostgreSQL 作为元数据存储,配合 S3 存储
        ```sql
        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'
        );
        ```
    
    
        使用 MySQL 作为元数据存储,配合 S3 存储
        ```sql
        CREATE CATALOG paimon_jdbc_mysql PROPERTIES (
            'type' = 'paimon',
            'paimon.catalog.type' = 'jdbc',
            'paimon.jdbc.uri' = 'jdbc:mysql://127.0.0.1:3306/paimon_db',
            'paimon.jdbc.user' = 'paimon_user',
            'paimon.jdbc.password' = 'password',
            'paimon.jdbc.driver_class' = 'com.mysql.cj.jdbc.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 Snapshot;如果语句执行失败,Doris 不会发布只包含部分数据的 Snapshot。

写入前检查

写入数据前,请确认以下事项:

  • 所有 FE 和 BE 节点都已经运行包含 Paimon 写入功能的 Doris 版本。滚动升级期间,如果还有旧版本 BE 节点,请不要向 Paimon 写入数据。
  • Catalog 使用的账号既要有修改元数据服务的权限,也要有在 Warehouse 中创建、写入、重命名和删除文件的 权限。具体权限取决于所使用的元数据服务和存储系统。
  • 只能写入普通的 Paimon 数据表。Paimon 系统表以及指定了 Branch、Tag、Snapshot 或时间点的表引用都是只读的。

支持的 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;

追加和覆盖数据

对于 Append Only 表,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;

对于分区表,可以使用以下两种方式:

-- 只替换指定分区。静态分区列不需要出现在 SELECT 列表中。
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;

-- 动态覆盖会替换输入数据中出现的分区,并保留其他分区。
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 时,才允许在写入时省略非主键列。对于 Append Only 表, 省略的列使用默认值;如果列允许为空且没有默认值,则使用 NULL。

删除、更新和合并数据

行级修改要求目标表是 Paimon 主键表。对于使用默认 deduplicate Merge Engine 的表,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 Merge Engine,并且不支持 changelog-producer=input。
  • 更新分区列时,目标表必须是动态 Bucket 表(bucket=-1),并且 ignore-delete=false。
  • DELETE 以及 MERGE 中的删除操作要求 ignore-delete=false。默认的 deduplicate Merge Engine 可以直接 执行删除;partial-update 表需要设置 partial-update.remove-record-on-delete=true;aggregation 表需要设置 aggregation.remove-record-on-delete=true。
  • 配置了 rowkind.field 的表不支持这些行级修改语句。配置了 cross-partition-upsert.index-ttl 的动态 Bucket 表也不支持这些语句。
  • MERGE 中包含哪类操作,就需要同时满足对应的 UPDATE 或 DELETE 限制。

为保证结果明确,MERGE 的源表数据在匹配键上应保持唯一。如果多条源表记录匹配同一条目标表记录,Doris 会拒绝执行该语句。

使用注意事项

  • 主键、分区、Bucket、Merge Engine、文件格式、Compaction 等数据组织方式应配置为 Paimon 表属性。Doris 会通过 Paimon SDK 校验这些属性。
  • Doris 暂未提供 Paimon 表通用的 ALTER TABLE ... SET TBLPROPERTIES 操作。建表后如需修改表属性,请使用 其他 Paimon 引擎完成修改,然后在 Doris 中执行 REFRESH TABLE 或 REFRESH CATALOG。
  • 每个 BE 都需要为写入过程预留足够的本地磁盘空间,并且 Warehouse 账号需要有操作临时文件和提交数据的 权限。BE 配置项 paimon_jni_writer_memory_pool_limit_bytes 用于限制每个 Paimon JNI Writer 的内存池大小, 默认值为 512 MB。
  • 写入或表结构变更成功后,新执行的 Doris 语句会读取已提交的 Paimon Snapshot;已经开始执行的语句仍然使用 启动时选定的 Snapshot。

查询操作

基础查询

配置好 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 full qualified name to query
SELECT * FROM paimon_ctl.paimon_db.paimon_tbl LIMIT 10;

文件元数据列

该功能自 4.2.0 版本起支持。

Doris 为 Paimon 数据表提供两个隐藏元数据列,可用于定位每条查询结果对应的物理数据文件和文件内行位置。

列名 类型 说明
__paimon_file_path STRING NOT NULL Paimon 为原始数据文件返回的路径。
__paimon_row_index BIGINT NOT NULL 该行在完整数据文件中的物理位置,从 0 开始。

前置条件:按照前文示例配置 Paimon Catalog,并创建一个包含 id 列、使用 Parquet 或 ORC 文件的 Paimon 数据表。以下查询假设 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_columns BOOLEAN false 否 在 SELECT * 和 DESC 中显示隐藏列。显式引用列名时无需开启。
enable_file_scanner_v2 BOOLEAN true 否 查询引用这些元数据列时必须保持开启。
force_jni_scanner BOOLEAN false 否 必须保持关闭,因为 JNI Reader 无法生成这些元数据列。

行位置以完整物理文件为基准。谓词过滤、Deletion Vector 处理及扫描切分不会对保留行重新编号。因此,__paimon_file_path 和 __paimon_row_index 的组合可以定位当前表快照中的一条物理记录。数据文件重写或 Compaction 后,两列的值可能变化,不能将其作为稳定的逻辑行 ID。

仅当查询涉及的每个 Paimon Split 都能作为原始数据文件,通过 FileScannerV2 原生 Parquet 或 ORC Reader 读取时,才能使用这些列。对于 JNI 或原生/JNI 混合扫描、关闭 enable_file_scanner_v2、开启 force_jni_scanner,以及所选数据文件无法使用原生 Parquet/ORC Reader 的情况,引用这些列的查询会失败。

__paimon_file_path 和 __paimon_row_index 是保留列名,名称比较不区分大小写。请勿在 Paimon 表中使用它们作为物理列名。

增量查询

该功能自 3.1.0 版本支持

支持类似 Flink 针对 Paimon 的 Batch Incremental 查询。

支持查询指定的快照或时间戳区间内的增量数据。区间为左闭右开区间。

-- 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 起始快照 ID,必须大于 0。必须和 endSnapshotId 配对使用。 'startSnapshotId'='3'
endSnapshotId 结束快照 ID,必须大于 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 文档 进一步了解这些参数。

时间旅行

该功能自 3.1.0 版本支持

支持读取 Paimon 表指定的 Snapshot。

默认情况下,读取请求只会读取最新版本的快照。

可以通过 $snapshots 表函数查询查询指定 Paimon 表的 Snapshot:

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 语句,根据快照 ID 或者快照产生的时间读取历史版本的数据。示例如下:

-- 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;

通过 @options 进行时间旅行 {#time-travel-with-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。选择快照或 Tag 时也会选择对应的 历史 Schema;Doris 不会把最新 Schema 错误地绑定到历史数据。

-- 使用快照 1 中保存的 Schema 读取快照 1。
SELECT id, old_name
FROM paimon_tbl@options('scan.snapshot-id' = '1');

-- 即使普通快照已经过期,保留的 Tag 仍然可以读取。
SELECT id, old_name
FROM paimon_tbl@options('scan.tag-name' = 'tag1');

一个表引用只能指定一个启动位置参数。只有 Paimon 定义为兼容的组合才能同时使用 scan.mode 和位置参数;例如, scan.mode='from-creation-timestamp' 必须同时指定 scan.creation-time-millis。不存在或已过期的快照、Branch 或 Tag 会明确报错,不会静默回退到最新表。@options 可以用于查询的表引用,也可以保存在 View 定义中,但不能 应用于 CTE 引用或 SHOW 等非查询命令。

Branch 和 Tag

该功能自 3.1.0 版本支持

支持读取指定 Paimon 表的分支(Branch)和标签(Tag)。

可以使用 $branches 和 $tags 系统表查看 Paimon 表的 Branch 和 Tag:

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 会根据后面的参数,自动判断是时间戳还是 Tag 名称。

系统表

该功能自 3.1.0 版本支持

Doris 支持查询 Paimon 系统表,用来查询表的相关元信息。支持使用系统表查看快照历史、清单文件、数据文件、分区等信息。

要访问 Paimon 表的元数据,可以在表名后添加 $ 符号,后跟系统表名称:

SELECT * FROM my_table$system_table_name;

audit_log、binlog、manifests、partitions、ro、row_tracking 和 table_indexes 系统表支持表引用 @options。选择的快照或 Tag 会应用于系统表数据;如果系统表会显示源表列,也会使用匹配的历史源表 Schema:

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)"}] |
+-------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

查看 buckets 的数据分布情况

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 |
+--------+------------+--------------------+

附录

FAQ

  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 之前的版本不支持 s3a 协议,如果必须使用,可以临时显示添加 s3a 协议相关参数临时解决。

    3.1 之后的版本无需此操作。同时,3.1 之后的版本如果需要对 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 s3 parameters
        'paimon.s3.region' = 'ap-east-1',
        'paimon.s3.endpoint' = 'ap-east-1',
        'paimon.s3.access-key' = '<ak>',
        'paimon.s3.secret-key' = '<sk>'
    );
    

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。