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

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 パスの一つ上の階層を指定する必要があります。たとえば、テーブルのパスが 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 のスキャン split にまとめる際の目標サイズです。
    source.split.open-file-cost4 MB0 以上のメモリサイズPaimon がファイルを split にまとめる際に使用する、ファイルを開くコストの推定値です。
    scan.manifest.parallelism利用可能なプロセッサ数1～256 の整数要求する manifest 読み取りの並列度です。実行時、Doris は各計画ブランチの並列度を、この値、256、およびその FE または BE で利用可能なプロセッサ数のうち最小の値に個別に制限します。
    scan.plan-sort-partitionfalse真偽値Paimon のスキャン計画時にパーティションをソートします。

    たとえば、次の Catalog 設定は物理的な Paimon テーブルに保存された値を上書きし、Doris のクエリの デフォルト値になります。

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

    クエリでは、Catalog や Paimon テーブルのメタデータを変更せずに、これらのデフォルト値を上書きできます。

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

    テーブル参照ごとに独立したオプションのセットを持ちます。たとえば、同じテーブルの二つのエイリアスに、単一のステートメント内で異なる バッチサイズを指定できます。

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

    優先順位は高い順に次のとおりです。

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

    Doris は、この優先順位を適用した後の最終的な値を検証します。そのため、物理テーブルに無効な値があっても、Catalog またはテーブル参照に有効な値を設定すれば 置き換えられます。最終的な値も無効な場合、Doris は該当する計画段階またはリーダー段階が始まる前に クエリを拒否します。manifest の上限は、パーティション、行数や統計情報、 フォールバックブランチ、システムテーブルの manifest 計画より前にも適用されます。

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

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

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

    ステートメント内の一貫性

    単一のステートメント内では、Doris はスキーマの関連付け、パーティションの読み込み、行数や統計情報の収集、システムテーブルの 計画、データスキャンを、同じ Paimon スナップショットとテーブル世代に対して行います。 @options で選択したスナップショットまたはタグには、その履歴バージョンに属するスキーマが使用されます。これには、ネストした STRUCT、MAP、ARRAY フィールドも含まれます。プリペアドステートメントは実行ごとに新しいステートメント状態を取得するため、実行間のコミットは 新しい実行の選択条件とキャッシュ設定に従って反映されます。

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

    Paimon JNI IOManager

    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 の各ストレージパスの下にディレクトリを作成します。
    paimon.jni.io_manager.impl_classいいえPaimon のデフォルト実装カスタム org.apache.paimon.disk.IOManager 実装の完全修飾クラス名です。このクラスは、すべての BE の Paimon JNI Scanner クラスパスで利用できる必要があります。

    次の例では IOManager を有効にし、一時ディレクトリを Doris が BE のストレージパスから選択するようにします。

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

    IOManager を有効にしても、すべてのマージ読み取りで退避が発生するわけではありません。Paimon が退避するのは、マージリーダーの数が sort-spill-threshold を超えた場合だけです。これは Doris の動的なリーダーオプションではありません。退避動作を変更する必要がある場合は、物理的な Paimon テーブルで設定してください。

    専用の退避ディスクを使用するには、すべての BE に存在するか作成可能なローカルパスを設定します。

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

    Doris は JNI スキャナーごとに IOManager を作成し、スキャナーとともにクローズします。設定するディレクトリは 書き込み可能で、同時実行クエリに十分な容量があることを確認してください。カスタム実装クラスを設定する場合は、 String[] を受け取る public コンストラクター、String を受け取る public コンストラクター、または引数のない public コンストラクターが必要です。 クラスの読み込みやインスタンス化に失敗すると、クエリは失敗します。

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

  • {CommonProperties}

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

メタデータキャッシュ​

外部データソースへのアクセス性能を高めるため、Apache Doris は Paimon のメタデータをキャッシュします。メタデータには、特定のスナップショット時点のテーブルスキーマ、最新のスナップショット 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.<engine>.<entry>.{enable,ttl-second,capacity,max-weight} の設定キーを使用します。Paimon の <engine> は paimon です。meta.cache.paimon.table.ttl-second は、最新スナップショットキャッシュとテーブルスキーマキャッシュの TTL を制御します。

プロパティ例意味
enabletrue/falseこのキャッシュエントリを有効にするかどうか。
ttl-second600, 0, -10 はエントリを無効にします（即座に反映され、最新データの確認に使用できます）。-1 は期限切れにならないことを意味します。その他の正の整数は、アクセス時刻を基準とする秒単位の TTL を表します。
capacity10000キャッシュエントリの最大件数です。0 はエントリを無効にします。
max-weight1GBDoris 4.1.4 以降でサポートされます。保持されるメモリの推定量に対する任意指定の上限です。正の値が必要で、0 は拒否されます。以下に示す対象エントリだけが受け付けます。

有効になる条件： enable=true、ttl-second != 0、capacity > 0 の場合にエントリが有効になります。さらに、FE 全体、Catalog、またはエントリ単位のメモリ上限が、メモリ使用量の推定値に基づくキャッシュへの追加を制御します。外部メタデータキャッシュのメモリ管理を参照してください。

キャッシュモジュール​

次のエントリには独自の設定キーがあり、max-weight を受け付けます。

エントリ（<entry>）プロパティキーのプレフィックスENTRY_NAMEキャッシュされる内容と効果デフォルトの有効状態 / TTL / 容量
partition_viewmeta.cache.paimon.partition_view.paimon.partition-viewテーブルのスナップショットから導出されたパーティション投影。効果：計画時に繰り返し行うパーティションスキャンを減らします。true / 86400 秒 / 1000

次のキャッシュには <entry> トークンがなく、Catalog と FE 全体のメモリ上限のみに従います。

ENTRY_NAMEキャッシュされる内容TTL / 容量
paimon-schema-at特定のスナップショット時点のテーブルスキーマ期限なし / 10000
paimon-latest-snapshotテーブルの最新スナップショット IDmeta.cache.paimon.table.ttl-second（86400 秒）/ 1000

Paimon テーブルのカラムスキーマは、共有の default エンジン（meta.cache.default.schema.*）によってキャッシュされます。

従来のパラメータの対応と変換​

従来のプロパティキー統一されたキー説明
schema.cache.ttl-secondmeta.cache.default.schema.ttl-secondテーブルスキーマキャッシュの有効期限

ベストプラクティス​

  • 最新データへのリアルタイムアクセス：すべてのクエリで Paimon テーブルの最新スナップショットを参照するには、meta.cache.paimon.table.ttl-second を 0 に設定します。 
    -- Disable the latest-snapshot cache to detect the latest snapshots of Paimon tables
    ALTER CATALOG paimon_ctl SET PROPERTIES ("meta.cache.paimon.table.ttl-second" = "0");
  • 性能の最適化：Catalog プロパティの変更に成功すると、影響を受けるメタデータキャッシュが削除され、次回のアクセス時に新しい設定で再構築されます。meta.cache.max-weight または schema.cache.ttl-second を変更すると Catalog のすべてのキャッシュが削除され、meta.cache.<engine>.<entry>.* を変更すると、そのエンジンのキャッシュが削除されます。進行中のクエリには影響しません。FE 全体または Catalog のメモリ上限が適用される場合、計上されない二重のメタデータキャッシュを避けるため、Paimon SDK 自体の CachingCatalog はデフォルトで無効になります。明示的に設定された paimon.cache-enabled プロパティが優先されます。

可観測性​

キャッシュのメトリクスは、information_schema.catalog_meta_cache_statistics システムテーブルで確認できます。ENTRY_NAME には上の表に示した名前が表示され、default エンジンの行は共有のテーブルスキーマキャッシュを表します。

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

このシステムテーブルについては、catalog_meta_cache_statisticsのドキュメントを参照してください。

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

現在依存している Paimon のバージョンは 1.4.2 です。

サポートされる Paimon 形式​

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

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

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

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

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

サポートされるデータ形式​

カラム型の対応​

Doris 4.2 における型の対応表全体、精度のルール、サポートされない型については、Paimon から Doris へのデータ型の対応を参照してください。

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

バージョンに関する注意

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

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

例​

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 の認証情報には、Metastore の更新、およびウェアハウス内のファイルの作成、書き込み、名前変更、削除の権限が 必要です。具体的な権限は、Metastore とストレージシステムによって異なります。
  • 書き込みの対象は通常の 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 はステートメントを拒否します。

運用上の注意事項​

  • 主キー、パーティション、バケット、マージエンジン、ファイル形式、compaction などの物理的な動作は、 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;

ファイルメタデータカラム​

バージョン 4.2.0 以降でサポートされます。

Doris は Paimon データテーブル向けに二つの隠しメタデータカラムを公開します。クエリ結果の各行を生成した物理データファイルと行の特定に使用できます。

カラム型説明
__paimon_file_pathSTRING NOT NULL生データファイルについて Paimon が返す元のパス。
__paimon_row_indexBIGINT NOT NULLデータファイル全体における、ゼロから始まる物理的な行位置。

前提条件：前述の例に従って 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_columnsBOOLEANfalseいいえSELECT * と DESC に隠しカラムを含めます。カラムを明示的に参照する場合は不要です。
enable_file_scanner_v2BOOLEANtrueいいえクエリがこれらのメタデータカラムを参照する場合、有効のままにする必要があります。
force_jni_scannerBOOLEANfalseいいえJNI リーダーはこれらのメタデータカラムを生成できないため、無効のままにする必要があります。

行位置は物理ファイル全体を基準とします。述語によるフィルタリング、Deletion Vector の処理、スキャンの分割によって、残った行の番号が振り直されることはありません。そのため、__paimon_file_path と __paimon_row_index の組み合わせで、現在のテーブルスナップショット内の物理レコードを特定できます。データファイルの再書き込みや compaction によって両方の値が変わる可能性があるため、安定した論理行 ID として使用しないでください。

注意

これらのカラムを使用できるのは、クエリに参加するすべての Paimon split を、FileScannerV2 のネイティブ Parquet または ORC リーダーで生データファイルとして読み取れる場合だけです。これらのカラムを参照するクエリは、JNI またはネイティブと JNI が混在するスキャン、enable_file_scanner_v2 が無効な場合、force_jni_scanner が有効な場合、または選択されたデータファイルをネイティブ Parquet/ORC リーダーで読み取れない場合に失敗します。

__paimon_file_path と __paimon_row_index は予約名であり、大文字と小文字を区別せずに比較されます。Paimon テーブルの物理カラム名として使用しないでください。

バッチ増分クエリ​

バージョン 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');

一つのテーブル参照には、開始位置のオプションを一つだけ指定できます。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 システムテーブルをクエリしてテーブル関連のメタデータを取得できます。システムテーブルを使用すると、スナップショットの履歴、manifest ファイル、データファイル、パーティションなどの情報を確認できます。

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​

テーブルの現在のスナップショットに含まれる manifest ファイルの情報を表示します。

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

付録​

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 より前のバージョン

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