メインコンテンツまでスキップ
に最終更新

Paimon Catalog

Doris は、さまざまなメタデータサービスを介した Paimon テーブルのメタデータへのアクセスと、Paimon データの読み書きをサポートしています。

Apache Doris と Apache 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：Alibaba Cloud DLF をメタデータサービスとして使用します。

    • jdbc：JDBC インターフェースを使用して、メタデータサービスとして機能するリレーショナルデータベースに接続します（バージョン 4.1.0 以降でサポート）。

  • <paimon_warehouse>

    Paimon のウェアハウスパスです。<paimon_catalog_type> が filesystem の場合、このパラメータは必須です。

    warehouse パスは、Database パスの 1 つ上の階層を指す必要があります。たとえば、テーブルのパスが 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> で設定し、個々のテーブル参照では table@options('<option-key>'='<value>') で上書きできます。これらの設定は Doris による読み取りにのみ影響し、 物理 Paimon テーブルのメタデータは更新しません。

    Paimon オプションPaimon のデフォルト値Doris が受け付ける値効果
    read.batch-size10241～65536 の整数Paimon JNI リーダーの各バッチで要求する行数。明示的に設定した値は、Doris がリーダーを開く際にも維持されます。
    file-reader-async-threshold10 MB1 MB～1 GB のメモリサイズPaimon JNI リーダーが非同期読み取りに切り替えるファイルサイズのしきい値。
    file-index.read.enabledtrue真偽値読み取り時の Paimon ファイルインデックスによる絞り込みを有効にします。
    source.split.target-size128 MB正のメモリサイズPaimon がデータファイルを Doris のスキャン分割にまとめる際の目標サイズ。
    source.split.open-file-cost4 MB0 以上のメモリサイズ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'
    );

    オプションの集合はテーブル参照ごとに独立しています。たとえば、同じテーブルの 2 つのエイリアスに、1 つのステートメント内で異なる バッチサイズを指定できます。

    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 は該当する計画段階またはリーダー段階に入る前にクエリを拒否します。 マニフェストの上限も、パーティション、行数・統計情報、フォールバック分岐、およびシステムテーブルのマニフェスト計画前に適用されます。

    表の最初の 5 つのオプションはメタデータに影響せず、キャッシュされた最新のパーティション投影を再利用できます。 scan.manifest.parallelism と scan.plan-sort-partition はメタデータの計画に影響するため、Doris は テーブル参照ごとの有効なテーブルハンドルを使用して計画します。クエリごとの値によって、Paimon の JVM 全体で共有するエグゼキューターのサイズは変更されません。

    Doris は、CREATE CATALOG および ALTER CATALOG の実行時に、不明または無効な paimon.table-option.* プロパティを拒否します。 ALTER CATALOG は、設定を公開する前に候補となる設定全体を検証します。そのため、変更に失敗した場合は以前の Catalog 設定が有効なままです。古い Doris バージョンで永続化された Catalog も読み込めますが、 サポート対象外または無効な旧リーダープロパティは適用されず、無視されます。それらの永続化された値は、 イメージおよび編集ログとの互換性のために保持されます。

    スナップショットと開始位置のオプションはテーブル参照のコンテキストを選択するものであり、 タイムトラベルで説明するように @options を使用する必要があります。Catalog のデフォルト値にはできません。Doris は、 Paimon の Flink ソースエニュメレーターに属する scan.max-splits-per-task、scan.fallback-branch、およびストリーミング、 レイアウト、書き込み、コンパクションのオプションも対象外とします。Bucket、Primary Key、Partition、Merge Engine などの物理的な 動作は、Doris の CREATE TABLE ... PROPERTIES を含め、Paimon テーブルのプロパティとして設定してください。

    ステートメントの一貫性

    Doris は 1 つのステートメント内で、スキーマのバインド、パーティションの読み込み、行数・統計情報の収集、システムテーブルの 計画、およびデータスキャンに対して、同じ Paimon スナップショットとテーブル世代を使用します。 @options で選択したスナップショットまたはタグには、その履歴バージョンに対応するスキーマが使用されます。ネストした STRUCT、MAP、ARRAY フィールドも対象です。準備済みステートメントの実行ごとに新しいステートメント状態が取得されるため、実行間のコミットは 新たな実行のセレクターとキャッシュ設定に従って反映されます。

    運用上の安全性のため、Paimon スキャナーの DEBUG 設定メッセージにはバッチサイズと投影フィールド数のみが出力されます。 Doris は、認証情報を含む可能性があるスキャナーパラメータの生のマップを出力しません。 PaimonJniAsyncReaderThreadCount プロファイルゲージはスキャナー全体について 1 秒に 1 回サンプリングされるため、 最大 1 秒古い値になる場合があります。このサンプリングはクエリの実行やスケジューリングに影響しません。リーダーと IOManager の クリーンアップは独立しており、クローズ処理が途中で失敗しても安全に再試行できます。

    Paimon JNI IOManager

    この機能はバージョン 4.0.8 以降でサポートされます。

    Paimon の主キーテーブルでは、JNI によるマージ読み取り時に、複数ファイルのデータをソートしてマージする必要がある場合があります。 Paimon IOManager を有効にすると、この処理の中間データを BE のローカルディスクに退避でき、 大量のデータをマージ読み取りする際のメモリ負荷を軽減できます。

    プロパティ必須デフォルト値説明
    paimon.jni.enable_jni_io_managerいいえfalseJNI 読み取りで Paimon IOManager を有効にするかどうか。他の IOManager プロパティは、これが true の場合にのみ有効です。
    paimon.jni.io_manager.tmp_dirいいえ<storage_root_path>/paimon_jni_scanner_io_tmpPaimon IOManager が一時退避ファイルに使用するローカルディレクトリ。複数のディレクトリはコンマまたはコロンで区切れます。省略すると、Doris は各 BE ストレージパスの下にディレクトリを 1 つ作成します。
    paimon.jni.io_manager.impl_classいいえPaimon のデフォルト実装カスタム org.apache.paimon.disk.IOManager 実装の完全修飾クラス名。このクラスは、すべての BE の Paimon JNI Scanner クラスパスから利用できる必要があります。

    次の例では IOManager を有効にし、BE のストレージパスから一時ディレクトリを 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.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 は JNI スキャナーごとに IOManager を作成し、スキャナーとともにクローズします。設定したディレクトリが 書き込み可能であり、同時に実行されるクエリに対して十分な容量を持つことを確認してください。カスタム実装クラスを 設定する場合は、String[] を受け取る public コンストラクター、String を受け取る public コンストラクター、または 引数なしの public コンストラクターが必要です。クラスの読み込みまたはインスタンス化に失敗すると、クエリは失敗します。

    これらのプロパティは、JNI パスを使用する Paimon データテーブルの読み取りにのみ影響します。ネイティブ読み取りには影響しません。 paimon.table-option.file-reader-async-threshold オプションは独立しており、Paimon ファイルの非同期読み取りの しきい値を制御します。IOManager を有効にしたり、退避用ディレクトリを設定したりするものではありません。

  • {CommonProperties}

    CommonProperties セクションには共通プロパティを設定します。Catalog の概要の[共通プロパティ]セクションを参照してください。

メタデータキャッシュ​

外部データソースへのアクセス性能を向上させるため、Apache Doris は Paimon メタデータをキャッシュします。メタデータには、テーブル構造（Schema）、テーブルオブジェクト、スナップショット、パーティション投影が含まれます。

ヒント

Doris 4.1.x より前のバージョンでは、メタデータキャッシュは主に FE の設定項目で全体的に制御します。詳細はメタデータキャッシュを参照してください。 Doris 4.1.x 以降では、Paimon Catalog の外部メタデータキャッシュを統一された meta.cache.* キーで設定します。

キャッシュプロパティの設定（4.1.x 以降）​

各エンジンのキャッシュエントリには、統一された設定キーフォーマット meta.cache.<engine>.<entry>.{enable,ttl-second,capacity,max-weight} を使用します。メモリ制限は、推定器を使用する table および snapshot エントリに適用されます。外部メタデータキャッシュのメモリ管理を参照してください。

プロパティ例意味
enabletrue/falseこのキャッシュモジュールを有効にするかどうか。
ttl-second600, 0, -10 はキャッシュの無効化を意味します（即座に反映され、最新データの確認に使用できます）。-1 は期限切れにならないことを意味します。その他の正の整数は、アクセス時刻を基準とする秒単位の TTL です。
capacity10000件数によるキャッシュエントリの最大数。max-weight が有効な場合は同時適用される件数制限にはなりませんが、0 にするとキャッシュは無効になります。
max-weight1GBDoris 4.1.4 以降でサポート。保持メモリの推定量に対する任意の上限です。Paimon の table と snapshot がサポートし、0 にするとそのエントリは無効になります。

有効化の条件： enable=true、ttl-second != 0、capacity > 0 であり、かつ max-weight が未指定または 0 以外の場合に、モジュールのキャッシュが有効になります。

キャッシュモジュール​

Paimon Catalog には、以下のキャッシュモジュールがあります。

モジュール（<entry>）プロパティキーのプレフィックスキャッシュする内容と影響
schemameta.cache.paimon.schema.テーブル構造をキャッシュします。影響：テーブルのカラム情報が反映されるタイミング。無効にすると、クエリごとに最新の Schema を取得します。
tablemeta.cache.paimon.table.Paimon テーブルのメタデータオブジェクトをキャッシュします。影響：クエリ計画時のメタデータ読み込み負荷を軽減します。
snapshotmeta.cache.paimon.snapshot.スナップショットのメタデータ、スキーマ世代、パーティション投影をキャッシュします。このエントリは max-weight をサポートします。

旧パラメータの対応関係と変換​

バージョン 4.1.x 以降では統一キーの使用を推奨します。従来の Catalog プロパティと 4.1.x 以降の統一キーの対応は次のとおりです。

従来のプロパティキー4.1.x 以降の統一キー説明
schema.cache.ttl-secondmeta.cache.paimon.schema.ttl-secondテーブル構造キャッシュの有効期限

ベストプラクティス​

  • 最新データへのリアルタイムアクセス：各クエリで Paimon テーブルの最新のデータ変更やスキーマ変更を確認するには、schema または table の ttl-second を 0 に設定できます。 
    -- Disable table object cache to detect the latest snapshots of Paimon tables
    ALTER CATALOG paimon_ctl SET PROPERTIES ("meta.cache.paimon.table.ttl-second" = "0");
  • 性能の最適化：Doris 4.1.4 以降では、Catalog プロパティの変更が成功すると、Catalog の実行コンテキストがリセットされ、その Catalog が使用する各メタデータキャッシュエンジンの初期化済みエントリが消去されます。次回のアクセス時に、新しいコンテキストと設定を使用して再構築されます。実行中のクエリには影響しません。Doris のメモリ管理が有効な場合、Paimon SDK の CachingCatalog はデフォルトで無効になります。paimon.cache-enabled を明示的に設定した場合は、その設定が優先されます。

可観測性​

キャッシュのメトリクスは、システムテーブル information_schema.catalog_meta_cache_statistics で確認できます。

SELECT catalog_name, engine_name, entry_name,
       effective_enabled, ttl_second, capacity,
       estimated_size, hit_rate, load_failure_count, last_error
FROM information_schema.catalog_meta_cache_statistics
WHERE catalog_name = 'paimon_ctl' AND engine_name = 'paimon'
ORDER BY entry_name;

このシステムテーブルのドキュメント：catalog_meta_cache_statistics。

サポートされる Paimon バージョン​

現在依存している Paimon のバージョンは 1.4.2 です（4.1.4 より前は 1.3.1）。

サポートされる Paimon フォーマット​

  • Paimon Deletion Vector の読み取りをサポート

サポートされるメタデータサービス​

注：Doris のバージョンによって、サポートされるサービスの種類とパラメータが多少異なります。[例]セクションを参照してください。

サポートされるストレージシステム​

注：Doris のバージョンによって、サポートされるサービスの種類とパラメータが多少異なります。[例]セクションを参照してください。

サポートされるデータフォーマット​

カラム型のマッピング​

Doris 4.2 の完全な型のマッピング表、精度の規則、サポートされない型については、Paimon から Doris へのデータ型マッピングを参照してください。

Doris は、Paimon JNI スキャナーの両方のパスで、引用符で囲まれたトップレベルのカラム名とネストした STRUCT フィールド名の 表記を正確に保持します。コンマ（region,code）、ハッシュ記号（nested#value）、コロン（colon:name）、 空白、Unicode 文字を含む名前も、通常の SQL 識別子の引用を超えるエスケープは不要です。読み取り時のカラム照合では 大文字と小文字を区別しないため、大文字や大文字・小文字が混在するカラム名（例：UserId）も通常どおりクエリできます。

バージョンに関する注記

4.0.8 より前のバージョンでは、読み取り時に完全一致でカラムを特定していたため、大文字・小文字が混在するカラム名を持つ Paimon および Iceberg テーブルで、誤ったカラムを読み取ったり、クエリが失敗したりする場合がありました。この問題は 4.0.8 で修正されました。

4.1.5 以降では、明示的な REFRESH TABLE、REFRESH DATABASE、REFRESH CATALOG コマンドによって、対応する Paimon SDK キャッシュも無効になります。外部でスキーマを変更した後や、テーブルを削除して再作成した後は、リフレッシュコマンドを使用してメタデータを再読み込みしてください。すでに開始したクエリでは、選択済みのスナップショットが維持されます。

例​

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

Kerberos 認証なしで HMS にアクセスする場合

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 にアクセスする場合

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 Metastore​

バージョン 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 Metastore​

バージョン 3.1+

Kerberos 認証なしで HMS および HDFS サービスにアクセスする場合

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

Kerberos 認証なしで HMS および HDFS サービスにアクセスする場合

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 ノードで、Paimon 書き込みをサポートする Doris ビルドが稼働している必要があります。古い BE ノードがまだ稼働している ローリングアップグレード中は、Paimon に書き込まないでください。
  • Catalog の認証情報には、メタストアを更新し、ウェアハウス内のファイルを作成、書き込み、名前変更、削除する権限が必要です。 必要な権限は、メタストアとストレージシステムによって異なります。
  • 書き込みの対象は通常の Paimon データテーブルに限られます。Paimon システムテーブル、およびブランチ、 タグ、スナップショット、タイムスタンプを選択するテーブル参照は読み取り専用です。

サポートされる SQL​

操作サポート内容と注記
データベース DDLCREATE DATABASE と DROP DATABASE
テーブル DDLCREATE 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 で設定したカラムを変更できません。
  • MERGE 内の更新アクションを含む UPDATE は、deduplicate マージエンジンのみをサポートし、 changelog-producer=input はサポートしません。
  • パーティションカラムの更新には、ignore-delete=false を設定した動的バケットテーブル（bucket=-1）が必要です。
  • MERGE 内の削除アクションを含む DELETE には、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 は Paimon テーブルに対する汎用的な ALTER TABLE ... SET TBLPROPERTIES 操作を提供していません。 作成後にテーブルプロパティを変更する場合は、別の Paimon エンジンを使用し、その後 Doris で REFRESH TABLE または REFRESH CATALOG を 実行してください。
  • 書き込み時のディスクへの退避に備えて各 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;

バッチ増分クエリ​

バージョン 3.1.0 以降

Flink と同様に、Paimon のバッチ増分クエリをサポートします。

指定したスナップショットまたはタイムスタンプの区間内にある増分データをクエリできます。区間は左閉右開です。

-- 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 テーブルの指定したスナップショットの読み取りをサポートします。

デフォルトでは、読み取り要求は最新バージョンのスナップショットのみを読み取ります。

$snapshots テーブル関数を使用すると、指定した Paimon テーブルのスナップショットをクエリできます。

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 を使用したタイムトラベル​

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

1 つのテーブル参照には開始位置のオプションを 1 つだけ指定できます。scan.mode を位置指定と組み合わせられるのは、 その組み合わせを Paimon が互換と定義している場合だけです。たとえば、scan.mode='from-creation-timestamp' には scan.creation-time-millis が必要です。不明または期限切れのスナップショット、ブランチ、タグを指定すると、 暗黙に最新テーブルへ切り替えることなく、明示的に失敗します。@options 構文はクエリのテーブル参照でサポートされ、ビューの 定義にも保存できますが、CTE 参照や SHOW などのクエリ以外のコマンドには適用できません。

ブランチとタグ​

バージョン 3.1.0 以降

指定した Paimon テーブルのブランチとタグの読み取りをサポートします。

$branches および $tags システムテーブルを使用すると、Paimon テーブルのブランチとタグを確認できます。

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 は、Flink でのみサポートされる Paimon のグローバルシステムテーブルの読み取りをサポートしません。

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
On This Page