メインコンテンツまでスキップ
バージョン: 2.1

Iceberg カタログ

Dorisは、さまざまなメタデータサービスを通じてIcebergTableデータへのアクセスをサポートしています。データの読み取りに加えて、DorisはIcebergTableへの書き込みもサポートしています。

Apache DorisとApache Icebergのクイックスタート。

ヒント

ユーザーはHive カタログを通じてHive Metastoreをメタデータとして使用してIcebergTableにアクセスできます。ただし、互換性の問題を避けるため、Iceberg カタログを直接使用することを推奨します。

適用シナリオ​

シナリオ説明
クエリ加速Dorisの分散コンピューティングエンジンを使用してIcebergデータに直接アクセスし、クエリを高速化します。
データ統合Icebergデータを読み取ってDoris内部Tableに書き込み、またはDorisコンピューティングエンジンを使用してZeroETL操作を実行します。
データ書き戻しDorisがサポートする任意のデータソースからデータを処理し、IcebergTableストレージに書き戻します。

カタログの設定​

構文​

CREATE CATALOG [IF NOT EXISTS] catalog_name PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = '<iceberg_catalog_type>',
    'warehouse' = '<warehouse>' --optional
    {MetaStoreProperties},
    {StorageProperties},
    {IcebergProperties},
    {CommonProperties}
);

  • <iceberg_catalog_type>

    Iceberg カタログのタイプです。以下のオプションをサポートしています：

    • hms: Hive Metastoreをメタデータサービスとして使用します。

    • rest: Iceberg Rest カタログインターフェースと互換性のあるメタデータサービスです。

    • hadoop: ファイルシステムに保存されているメタデータに直接アクセスします。

    • glue: AWS Glueをメタデータサービスとして使用します。

    • dlf: Alibaba Cloud DLFをメタデータサービスとして使用します。

    • s3tables: AWS S3 Tables カタログを使用してS3 Table バケットにアクセスします。

  • <warehouse>

    Icebergのwarehouseパスです。このパラメータは<iceberg_catalog_type>がhadoopの場合に指定する必要があります。

    warehouseパスはDatabaseパスの上のレベルを指す必要があります。例えば、Tableパスがs3://bucket/path/to/db1/table1の場合、warehouseはs3://bucket/path/to/にする必要があります。

  • {MetaStoreProperties}

    MetaStorePropertiesセクションは、Metastoreメタデータサービスの接続および認証情報を入力するためのものです。[Supported Metadata Services]のセクションを参照してください。

  • {StorageProperties}

    StoragePropertiesセクションは、ストレージシステムに関連する接続および認証情報を入力するためのものです。[Supported Storage システム]のセクションを参照してください。

  • {IcebergProperties}

    IcebergPropertiesセクションは、Iceberg カタログ固有のパラメータを設定するために使用されます。

    • list-all-tables

      Hive Metastoreをメタデータサービスとして使用するIceberg カタログの場合。デフォルトはtrueです。デフォルトでは、SHOW TABLES操作は現在のDatabase内のすべてのタイプのTableをリストします（Hive MetastoreはIceberg以外のタイプのTableも保存している可能性があります）。このアプローチは最高のパフォーマンスを持ちます。

      falseに設定した場合、Dorisは各Tableのタイプを一つずつチェックし、IcebergタイプのTableのみを返します。このモードは、Tableが多数ある場合にパフォーマンスが悪くなります。

  • {CommonProperties}

    CommonPropertiesセクションは、一般的なプロパティを入力するためのものです。共通プロパティの詳細については、カタログ 概要を参照してください。

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

Doris VersionIceberg SDK Version
2.11.6.1
3.01.6.1
3.11.9.1
4.01.9.1

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

  • Iceberg V1/V2フォーマットをサポートします。
  • Position DeleteとEquality Deleteの読み取りをサポートします。
  • Deletion Vectorの読み取りをサポートします（4.1.0以降）。

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

注意：異なるDorisバージョンでサポートされるサービスタイプとパラメータは若干異なります。[Examples]セクションを参照してください。

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

注意：異なるDorisバージョンでサポートされるサービスタイプとパラメータは若干異なります。[Examples]セクションを参照してください。

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

カラム型マッピング​

Iceberg タイプDoris タイプコメント
booleanboolean
integerint
longbigint
floatfloat
doubledouble
decimal(P, S)decimal(P, S)
datedate
timestamp (Timestamp without timezone)datetime(6)精度6のdatetimeにマッピングされます
timestamptz (Timestamp with timezone)datetime(6)精度6のdatetimeにマッピングされます
fixed(N)char(N)
stringstring
binarystring/varbinaryカタログのenable.mapping.varbinaryプロパティによって制御されます（4.0.2以降でサポート）。デフォルトはfalseでstringにマッピングされます。trueの場合はvarbinary型にマッピングされます。
uuidstring/varbinaryバージョン < 4.0.2ではstring型にマッピングされます。バージョン == 4.0.2ではvarbinary型にマッピングされます。バージョン > 4.0.2では、propertiesのenable.mapping.varbinaryプロパティによって制御されます。デフォルトはfalseでstringにマッピングされます。
structstruct（バージョン2.1.3からサポート）
mapmap（バージョン2.1.3からサポート）
listarray
otherUNSUPPORTED

注意：

Dorisは現在、タイムゾーン付きのTimestamp型をサポートしていません。すべてのtimestampとtimestamptzは一律にdatetime(N)型にマッピングされます。ただし、読み取りおよび書き込み時に、Dorisは実際のソース型に基づいてタイムゾーンを正しく処理します。例えば、SET time_zone=<tz>でタイムゾーンを指定した後、timestamptzカラムの読み取りおよび書き込み結果に影響します。

DESCRIBE table_nameステートメントのExtraカラムでソース型にタイムゾーン情報があるかどうかを確認できます。WITH_TIMEZONEと表示されている場合、ソース型がタイムゾーン対応型であることを示します（3.1.0以降でサポート）。

Namespaceマッピング​

Icebergのメタデータ階層はカタログ -> Namespace -> Tableです。Namespaceは複数レベル（Nested Namespace）を持つことができます。

      ┌─────────┐             
      │ カタログ │             
      └────┬────┘             
           │                  
     ┌─────┴─────┐            
  ┌──▼──┐     ┌──▼──┐         
  │ NS1 │     │ NS2 │         
  └──┬──┘     └──┬──┘         
     │           │            
┌────▼───┐    ┌──▼──┐         
│ Table1 │    │ NS3 │         
└────────┘    └──┬──┘         
                 │            
          ┌──────┴───────┐    
     ┌────▼───┐     ┌────▼───┐
     │ Table2 │     │ Table3 │
     └────────┘     └────────┘

バージョン3.1.2以降、Iceberg Rest カタログにおいてDorisはNested Namespaceのマッピングをサポートしています。

上記の例では、Tableは以下のロジックに従ってDorisメタデータにマッピングされます：

カタログDatabaseTable
カタログNS1Table1
カタログNS2.NS3Table2
カタログNS2.NS3Table3

Nested Namespaceのサポートは明示的に有効にする必要があります。詳細については、Iceberg Rest カタログを参照してください。

例​

Hive Metastore​

3.1+ Version

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

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

Kerberos認証が有効化されたHMSおよびHDFSサービスへのアクセス

CREATE CATALOG iceberg_hms_on_hdfs_kerberos_hdfs_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'hms',
    'warehouse' = 'hdfs://127.0.0.1:8520/iceberg-hms-hdfs-warehouse',
    'hive.metastore.uris' = 'thrift://127.0.0.1:9583',
    'hive.metastore.client.principal' = 'hive/presto-master.docker.cluster@LABS.TERADATA.COM',
    'hive.metastore.client.keytab' = '/keytabs/hive-presto-master.keytab',
    'hive.metastore.service.principal' = 'hive/hadoop-master@LABS.TERADATA.COM',
    'hive.metastore.sasl.enabled ' = 'true',
    'hive.metastore.authentication.type' = 'kerberos',
    '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',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8520',
    'hadoop.security.authentication' = 'kerberos',
    'hadoop.kerberos.principal'='hive/presto-master.docker.cluster@LABS.TERADATA.COM',
    'hadoop.kerberos.keytab' = '/keytabs/hive-presto-master.keytab'
);
2.1 & 3.0 Version

Kerberos認証なしでHMSとHDFSサービスにアクセス

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

Kerberos認証が有効化されたHMSおよびHDFSサービスへのアクセス

CREATE CATALOG iceberg_hms_on_hdfs_kerberos_hdfs_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'hms',
    'warehouse' = 'hdfs://127.0.0.1:8520/iceberg-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',
    'hive.metastore.authentication.type' = 'kerberos',
    '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',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8520',
    'hadoop.security.authentication' = 'kerberos',
    'hadoop.kerberos.principal'='hive/presto-master.docker.cluster@LABS.TERADATA.COM',
    'hadoop.kerberos.keytab' = '/keytabs/hive-presto-master.keytab'
);

AWS Glue​

3.1+ Version

AWS GlueとS3ストレージサービスは同じ認証資格情報を共有します。

CREATE CATALOG `iceberg_glue_on_s3_catalog_` PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'glue',
    'warehouse' = 's3://bucket/iceberg-glue-s3-warehouse',
    'glue.region' = 'ap-northeast-1',
    'glue.endpoint' = 'https://glue.ap-northeast-1.amazonaws.com',
    'glue.access_key' = '<ak>',
    'glue.secret_key' = '<sk>'
);

Glue サービスの認証資格情報が S3 の認証資格情報と異なる場合、以下の方法を使用して S3 の認証資格情報を個別に指定できます。

CREATE CATALOG `iceberg_glue_on_s3_catalog_` PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'glue',
    'warehouse' = 's3://selectdb-qa-datalake-test/iceberg-glue-s3-warehouse',
    'glue.region' = 'ap-northeast-1',
    'glue.endpoint' = 'https://glue.ap-northeast-1.amazonaws.com',
    'glue.access_key' = '<ak>',
    'glue.secret_key' = '<sk>',
    's3.endpoint' = 's3.ap-northeast-1.amazonaws.com',
    's3.region' = 'ap-northeast-1',
    's3.access_key' = '<ak>',
    's3.secret_key' = '<sk>'
);

IAM Assumed Roleを使用してS3アクセス認証情報を取得する（3.1.2以降）

CREATE CATALOG `glue_iceberg_iamrole` PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'glue',
    'warehouse' = 's3://bucket/warehouse',
    'glue.region' = 'us-east-1',                    
    'glue.endpoint' = 'https://glue.us-east-1.amazonaws.com',
    'glue.role_arn' = '<role_arn>'                
);
2.1 & 3.0 Version

AWS GlueとS3ストレージサービスは同じ認証資格情報を共有します。

非EC2環境では、aws configureを使用してCredentials情報を設定し、~/.awsディレクトリにcredentialsファイルを生成する必要があります。

CREATE CATALOG glue PROPERTIES (
    'type'='iceberg',
    'iceberg.catalog.type' = 'glue',
    'glue.endpoint' = 'https://glue.us-east-1.amazonaws.com',
    'glue.access_key' = '<ak>',
    'glue.secret_key' = '<sk>'
);

Aliyun DLF​

3.1+ バージョン
CREATE CATALOG iceberg_dlf_catalog_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type'='dlf',
    'warehouse' = 'oss://bucket/iceberg-dlf-oss-warehouse',
    'dlf.uid' = '203225413946383283',
    'dlf.catalog_id' = 'p2_regression_case',
    'dlf.region' = 'cn-beijing',
    'dlf.endpoint' = 'datalake.cn-beijing.aliyuncs.com',
    'dlf.access_key' = '<ak>',
    'dlf.secret_key' = '<sk>'
);
2.1 & 3.0 バージョン
CREATE CATALOG iceberg_dlf_catalog_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type'='dlf',
    'warehouse' = 'oss://bucket/iceberg-dlf-oss-warehouse',
    'dlf.uid' = '203225413946383283',
    'dlf.catalog.id' = 'catalog_id',
    'dlf.region' = 'cn-beijing',
    'dlf.access_key' = '<ak>',
    'dlf.secret_key' = '<sk>'
);

Iceberg Rest カタログ​

3.1+ バージョン
CREATE CATALOG iceberg_static_s3 PROPERTIES (
    'type' = 'iceberg',
    'warehouse' = 's3://warehouse',
    'iceberg.catalog.type' = 'rest',
    'iceberg.rest.uri' = 'http://127.0.0.1:8181',
    's3.endpoint' = 'https://s3.ap-east-1.amazonaws.com',
    's3.access_key' = '<ak>',
    's3.secret_key' = '<sk>',
    's3.region' = 'ap-east-1'
);
2.1 & 3.0 バージョン
CREATE CATALOG iceberg_static_s3 PROPERTIES (
    'type' = 'iceberg',
    'warehouse' = 's3://warehouse',
    'iceberg.catalog.type' = 'rest',
    'uri' = 'http://127.0.0.1:8181',
    's3.endpoint' = 'https://s3.ap-east-1.amazonaws.com',
    's3.access_key' = '<ak>',
    's3.secret_key' = '<sk>',
    's3.region' = 'ap-east-1'
);

FileSystem​

3.1+ Version

Kerberos認証なしでHDFSサービスにアクセス

CREATE CATALOG iceberg_fs_on_hdfs_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'hadoop',
    'warehouse' = 'hdfs://127.0.0.1:8320/user/iceberg/warehouse/iceberg-fs-hdfs-warehouse',
    'hadoop.username' = 'doris',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8320'
);

Kerberos認証を有効にしたHDFSサービスへのアクセス

CREATE CATALOG iceberg_fs_on_hdfs_kerberos_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'hadoop',
    'warehouse' = 'hdfs://127.0.0.1:8520/iceberg-fs-hdfs-warehouse',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8520',
    'hadoop.security.authentication' = 'kerberos',
    'hadoop.kerberos.principal'='hive/presto-master.docker.cluster@LABS.TERADATA.COM',
    'hadoop.kerberos.keytab' = '/keytabs/hive-presto-master.keytab'
);

2.1 & 3.0 Version

Kerberos認証なしでHDFSサービスにアクセス

CREATE CATALOG iceberg_fs_on_hdfs_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'hadoop',
    'warehouse' = 'hdfs://127.0.0.1:8320/user/iceberg/warehouse/iceberg-fs-hdfs-warehouse',
    'hadoop.username' = 'doris',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8320'
);

Kerberos認証が有効化されたHDFSサービスへのアクセス

CREATE CATALOG iceberg_fs_on_hdfs_kerberos_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'hadoop',
    'warehouse' = 'hdfs://127.0.0.1:8520/iceberg-fs-hdfs-warehouse',
    'fs.defaultFS' = 'hdfs://127.0.0.1:8520',
    'hadoop.security.authentication' = 'kerberos',
    'hadoop.kerberos.principal'='hive/presto-master.docker.cluster@LABS.TERADATA.COM',
    'hadoop.kerberos.keytab' = '/keytabs/hive-presto-master.keytab'
);

AWS S3 Tables​

3.1+ Version

S3 Tables 統合 ドキュメントを参照してください。

CREATE CATALOG aws_s3_tables PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'rest',
    'warehouse' = 'arn:aws:s3tables:us-east-1:<account_id>:bucket/<s3_table_bucket_name>',
    'iceberg.rest.uri' = 'https://s3tables.us-east-1.amazonaws.com/iceberg',
    'iceberg.rest.sigv4-enabled' = 'true',
    'iceberg.rest.signing-name' = 's3tables',
    'iceberg.rest.signing-region' = 'us-east-1',
    'iceberg.rest.access-key-id' = '<ak>',
    'iceberg.rest.secret-access-key' = '<sk>'
);
3.0.6+ Version

S3 Tables 統合 ドキュメントを参照してください。

CREATE CATALOG test_s3tables_catalog PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 's3tables',
    'warehouse' = 'arn:aws:s3tables:ap-east-1:9527:bucket/doris-s3-table-bucket',
    's3.region' = 'ap-east-1',
    's3.endpoint' = 'https://s3.ap-east-1.amazonaws.com',
    's3.access_key' = '<ak>',
    's3.secret_key' = '<sk>'
);

クエリ操作​

基本クエリ​

-- 1. switch to catalog, use database and query
SWITCH iceberg;
USE iceberg_db;
SELECT * FROM iceberg_tbl LIMIT 10;

-- 2. use iceberg database directly
USE iceberg.iceberg_db;
SELECT * FROM iceberg_tbl LIMIT 10;

-- 3. use full qualified name to query
SELECT * FROM iceberg.iceberg_db.iceberg_tbl LIMIT 10;

Time Travel​

Iceberg Tableの特定のスナップショットを読み取ることができます。

デフォルトでは、読み取りリクエストは最新のスナップショットバージョンにアクセスします。

iceberg_meta() Table関数を使用して、Iceberg Tableの特定のスナップショットをクエリできます：

SELECT * FROM iceberg_meta(
    'table' = 'iceberg_ctl.iceberg_db.iceberg_tbl',
    'query_type' = 'snapshots'
)\G

*************************** 1. row ***************************
 committed_at: 2024-11-28 11:07:29
  snapshot_id: 8903826400153112036
    parent_id: -1
    operation: append
manifest_list: oss://path/to/metadata/snap-8903826400153112036-1-3835e66d-9a18-4cb0-b9b0-9ec80527ad8d.avro
      summary: {"added-data-files":"2","added-records":"3","added-files-size":"2742","changed-partition-count":"2","total-records":"3","total-files-size":"2742","total-data-files":"2","total-delete-files":"0","total-position-deletes":"0","total-equality-deletes":"0"}
*************************** 2. row ***************************
 committed_at: 2024-11-28 11:10:11
  snapshot_id: 6099853805930794326
    parent_id: 8903826400153112036
    operation: append
manifest_list: oss://path/to/metadata/snap-6099853805930794326-1-dd46a1bd-219b-4fb0-bb46-ac441d8b3105.avro
      summary: {"added-data-files":"1","added-records":"1","added-files-size":"1367","changed-partition-count":"1","total-records":"4","total-files-size":"4109","total-data-files":"3","total-delete-files":"0","total-position-deletes":"0","total-equality-deletes":"0"}

FOR TIME AS OFとFOR VERSION AS OF句を使用して、スナップショットIDまたはスナップショットが作成された時刻に基づいて履歴データを読み取ることができます。以下にいくつかの例を示します：

-- Read data as of a specific timestamp
SELECT * FROM iceberg_table FOR TIME AS OF '2023-01-01 00:00:00';

-- Read data as of a specific snapshot ID
SELECT * FROM iceberg_table FOR VERSION AS OF 123456789;

ブランチとタグ​

Since 3.1.0

ブランチとタグの作成、削除、管理については、[Managing Branch & Tag]を参照してください

IcebergTableの特定のブランチとタグの読み取りがサポートされています。

Spark/Trinoなどのシステムとの互換性を保つため、複数の構文形式がサポートされています。

-- BRANCH
SELECT * FROM iceberg_tbl@branch(branch1);
SELECT * FROM iceberg_tbl@branch("name" = "branch1");
SELECT * FROM iceberg_tbl FOR VERSION AS OF 'branch1';

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

FOR VERSION AS OF 構文では、Doris はパラメータがタイムスタンプなのか Branch/Tag 名なのかを自動的に判定します。

View​

Since 3.1.0

Iceberg ビューのクエリをサポートしています。ビュークエリは通常のTableクエリと同じ方法で動作します。以下の点にご注意ください：

  • hms タイプの Iceberg カタログ のみサポートされています。
  • ビュー定義 SQL は Doris SQL dialect と互換性がある必要があります。そうでなければ解析エラーが発生します。（dialect 変換機能は将来のバージョンで提供予定です）。

システム Tables​

Since 3.1.0

Doris は Iceberg システムTableのクエリをサポートしており、Tableに関するメタデータ情報を取得できます。システムTableを使用して、スナップショット履歴、マニフェストファイル、データファイル、パーティション、その他のメタデータを表示できます。

Iceberg Tableのメタデータにアクセスするには、Table名に $ 記号とその後にシステムTable名を追加します：

SELECT * FROM iceberg_table$system_table_name;

例えば、Tableの履歴を表示するには、次を実行できます：

SELECT * FROM iceberg_table$history;

現在、all_manifestsとposition_deletesシステムTableはまだサポートされておらず、将来のバージョンでサポートされる予定です。

entries​

Tableの現在のスナップショットのすべてのマニフェストエントリを表示します：

all_entriesとentriesは類似していますが、all_entriesはすべてのスナップショットのエントリを含むのに対し、entriesは現在のスナップショットのエントリのみを含むという違いがあります。

SELECT * FROM iceberg_table$entries;

結果:

+--------+---------------------+-----------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| status | snapshot_id         | sequence_number | file_sequence_number | data_file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | readable_metrics                                                                                                                                                                                                                                                   |
+--------+---------------------+-----------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|      2 | 4890031351138056789 |               1 |                    1 | {"content":0, "file_path":"s3://.../iceberg_table/data/id=1/00000-16-79ef2fd7-9997-47eb-a91a-9f7af8201315-0-00001.parquet", "file_format":"PARQUET", "spec_id":0, "partition":{"id":1}, "record_count":1, "file_size_in_bytes":625, "column_sizes":{1:36, 2:41}, "value_counts":{1:1, 2:1}, "null_value_counts":{1:0, 2:0}, "nan_value_counts":{}, "lower_bounds":{1:"   ", 2:"Alice"}, "upper_bounds":{1:"   ", 2:"Alice"}, "key_metadata":null, "split_offsets":[4], "equality_ids":null, "sort_order_id":0, "first_row_id":null, "referenced_data_file":null, "content_offset":null, "content_size_in_bytes":null} | {"id":{"column_size":36, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":1, "upper_bound":1}, "name":{"column_size":41, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":"Alice", "upper_bound":"Alice"}} |
|      0 | 1851184769713369003 |               1 |                    1 | {"content":0, "file_path":"s3://.../iceberg_table/data/id=2/00000-16-79ef2fd7-9997-47eb-a91a-9f7af8201315-0-00002.parquet", "file_format":"PARQUET", "spec_id":0, "partition":{"id":2}, "record_count":1, "file_size_in_bytes":611, "column_sizes":{1:36, 2:39}, "value_counts":{1:1, 2:1}, "null_value_counts":{1:0, 2:0}, "nan_value_counts":{}, "lower_bounds":{1:"   ", 2:"Bob"}, "upper_bounds":{1:"   ", 2:"Bob"}, "key_metadata":null, "split_offsets":[4], "equality_ids":null, "sort_order_id":0, "first_row_id":null, "referenced_data_file":null, "content_offset":null, "content_size_in_bytes":null}     | {"id":{"column_size":36, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":2, "upper_bound":2}, "name":{"column_size":39, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":"Bob", "upper_bound":"Bob"}}     |
+--------+---------------------+-----------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

files​

Tableの現在のスナップショットに対するファイルリストを表示します：

SELECT * FROM iceberg_table$files;

結果:

+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------+-----------+--------------+--------------------+--------------+--------------+-------------------+------------------+-----------------------+-----------------------+--------------+---------------+--------------+---------------+--------------+----------------------+----------------+-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| content | file_path                                                                                       | file_format | spec_id | partition | record_count | file_size_in_bytes | column_sizes | value_counts | null_value_counts | nan_value_counts | lower_bounds          | upper_bounds          | key_metadata | split_offsets | equality_ids | sort_order_id | first_row_id | referenced_data_file | content_offset | content_size_in_bytes | readable_metrics                                                                                                                                                                                                                                                   |
+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------+-----------+--------------+--------------------+--------------+--------------+-------------------+------------------+-----------------------+-----------------------+--------------+---------------+--------------+---------------+--------------+----------------------+----------------+-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|       0 | s3://.../iceberg_table/data/id=2/00000-16-79ef2fd7-9997-47eb-a91a-9f7af8201315-0-00002.parquet  | PARQUET     |       0 | {"id":2}  |            1 |                611 | {1:36, 2:39} | {1:1, 2:1}   | {1:0, 2:0}        | {}               | {1:"   ", 2:"Bob"}   | {1:"   ", 2:"Bob"}   | NULL         | [4]           | NULL         |             0 |         NULL | NULL                 |           NULL |                  NULL | {"id":{"column_size":36, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":2, "upper_bound":2}, "name":{"column_size":39, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":"Bob", "upper_bound":"Bob"}}     |
|       0 | s3://.../iceberg_table/data/id=4/00000-16-79ef2fd7-9997-47eb-a91a-9f7af8201315-0-00004.parquet  | PARQUET     |       0 | {"id":4}  |            1 |                618 | {1:36, 2:40} | {1:1, 2:1}   | {1:0, 2:0}        | {}               | {1:"   ", 2:"Dave"}  | {1:"   ", 2:"Dave"}  | NULL         | [4]           | NULL         |             0 |         NULL | NULL                 |           NULL |                  NULL | {"id":{"column_size":36, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":4, "upper_bound":4}, "name":{"column_size":40, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":"Dave", "upper_bound":"Dave"}}   |
|       0 | s3://.../iceberg_table/data/id=6/00000-16-79ef2fd7-9997-47eb-a91a-9f7af8201315-0-00006.parquet  | PARQUET     |       0 | {"id":6}  |            1 |                625 | {1:36, 2:41} | {1:1, 2:1}   | {1:0, 2:0}        | {}               | {1:"   ", 2:"Frank"} | {1:"   ", 2:"Frank"} | NULL         | [4]           | NULL         |             0 |         NULL | NULL                 |           NULL |                  NULL | {"id":{"column_size":36, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":6, "upper_bound":6}, "name":{"column_size":41, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":"Frank", "upper_bound":"Frank"}} |
|       0 | s3://.../iceberg_table/data/id=8/00000-16-79ef2fd7-9997-47eb-a91a-9f7af8201315-0-00008.parquet  | PARQUET     |       0 | {"id":8}  |            1 |                625 | {1:36, 2:41} | {1:1, 2:1}   | {1:0, 2:0}        | {}               | {1:"   ", 2:"Heidi"} | {1:"   ", 2:"Heidi"} | NULL         | [4]           | NULL         |             0 |         NULL | NULL                 |           NULL |                  NULL | {"id":{"column_size":36, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":8, "upper_bound":8}, "name":{"column_size":41, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":"Heidi", "upper_bound":"Heidi"}} |
|       0 | s3://.../iceberg_table/data/id=10/00000-16-79ef2fd7-9997-47eb-a91a-9f7af8201315-0-00010.parquet | PARQUET     |       0 | {"id":10} |            1 |                618 | {1:36, 2:40} | {1:1, 2:1}   | {1:0, 2:0}        | {}               | {1:"   ", 2:"Judy"}  | {1:"   ", 2:"Judy"}  | NULL         | [4]           | NULL         |             0 |         NULL | NULL                 |           NULL |                  NULL | {"id":{"column_size":36, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":10, "upper_bound":10}, "name":{"column_size":40, "value_count":1, "null_value_count":0, "nan_value_count":null, "lower_bound":"Judy", "upper_bound":"Judy"}} |
+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+---------+-----------+--------------+--------------------+--------------+--------------+-------------------+------------------+-----------------------+-----------------------+--------------+---------------+--------------+---------------+--------------+----------------------+----------------+-----------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

filesシステムTableと同様に、以下のシステムTableを通じて特定のファイルタイプ情報を照会することもできます：

-- Query data files for the current snapshot
SELECT * FROM iceberg_table$data_files;

-- Query delete files for the current snapshot
SELECT * FROM iceberg_table$delete_files;

-- Query all files (including data and delete files) from all snapshots
SELECT * FROM iceberg_table$all_files;

-- Query data files from all snapshots
SELECT * FROM iceberg_table$all_data_files;

-- Query delete files from all snapshots
SELECT * FROM iceberg_table$all_delete_files;

これらのTableの結果形式はfilesシステムTableに似ていますが、それぞれがデータファイルまたは削除ファイルに特化しています。all_プレフィックスを持つシステムTableには、現在のスナップショットからのファイルだけでなく、すべてのスナップショットからのファイルが含まれています。

注意: 特定のタイプのファイルがTableに存在しない場合（例えば、Tableに削除ファイルが存在しないときにdelete_filesをクエリする場合）、クエリ結果は空になることがあります。

history​

Tableのすべての履歴を表示します：

SELECT * FROM iceberg_table$history;

結果:

+----------------------------+---------------------+---------------------+---------------------+
| made_current_at            | snapshot_id         | parent_id           | is_current_ancestor |
+----------------------------+---------------------+---------------------+---------------------+
| 2025-06-12 22:29:16.357000 | 1851184769713369003 |                NULL |                   1 |
| 2025-06-12 22:29:39.922000 | 4890031351138056789 | 1851184769713369003 |                   1 |
+----------------------------+---------------------+---------------------+---------------------+

manifests​

Tableのマニフェストファイル情報を表示します：

SELECT * FROM iceberg_table$manifests;

結果:

+---------+------------------------------------------------------------------------------------------------------------------------------------------------+--------+-------------------+---------------------+------------------------+---------------------------+--------------------------+--------------------------+-----------------------------+----------------------------+--------------------------------------------------------------------------------+
| content | path                                                                         | length | partition_spec_id | added_snapshot_id   | added_data_files_count | existing_data_files_count | deleted_data_files_count | added_delete_files_count | existing_delete_files_count | deleted_delete_files_count | partition_summaries                                                            |
+---------+------------------------------------------------------------------------------------------------------------------------------------------------+--------+-------------------+---------------------+------------------------+---------------------------+--------------------------+--------------------------+-----------------------------+----------------------------+--------------------------------------------------------------------------------+
|       0 | s3://.../iceberg_table/metadata/3194eb8b-5ea4-4cbe-95ba-073229458e7b-m0.avro |   7138 |                 0 | 4890031351138056789 |                      0 |                         5 |                        5 |                        0 |                           0 |                          0 | [{"contains_null":0, "contains_nan":0, "lower_bound":"1", "upper_bound":"10"}] |
+---------+------------------------------------------------------------------------------------------------------------------------------------------------+--------+-------------------+---------------------+------------------------+---------------------------+--------------------------+--------------------------+-----------------------------+----------------------------+--------------------------------------------------------------------------------+

metadata_log_entries​

Tableのメタログを表示します：

SELECT * FROM iceberg_table$metadata_log_entries;

Text:

+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+------------------+------------------------+
| timestamp                  | file                                                                                     | latest_snapshot_id  | latest_schema_id | latest_sequence_number |
+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+------------------+------------------------+
| 2025-06-12 22:29:06.948000 | s3://.../iceberg_table/metadata/00000-e373aa16-15f1-4e69-ae7d-5ed64199cf9a.metadata.json |                NULL |             NULL |                   NULL |
| 2025-06-12 22:29:16.357000 | s3://.../iceberg_table/metadata/00001-bbc8e244-e41c-4958-92f4-63b8c3ee1196.metadata.json | 1851184769713369003 |                0 |                      1 |
| 2025-06-12 22:29:39.922000 | s3://.../iceberg_table/metadata/00002-7dc00d6a-6269-4200-9d28-5f8c1c6b9f99.metadata.json | 4890031351138056789 |                0 |                      2 |
+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------------+------------------+------------------------+

partitions​

Tableのパーティションを表示します：

SELECT * FROM iceberg_table$partitions;

結果:

+-----------+---------+--------------+------------+-------------------------------+------------------------------+----------------------------+------------------------------+----------------------------+----------------------------+--------------------------+
| partition | spec_id | record_count | file_count | total_data_file_size_in_bytes | position_delete_record_count | position_delete_file_count | equality_delete_record_count | equality_delete_file_count | last_updated_at            | last_updated_snapshot_id |
+-----------+---------+--------------+------------+-------------------------------+------------------------------+----------------------------+------------------------------+----------------------------+----------------------------+--------------------------+
| {"id":8}  |       0 |            1 |          1 |                           625 |                            0 |                          0 |                            0 |                          0 | 2025-06-12 22:29:16.357000 |      1851184769713369003 |
| {"id":6}  |       0 |            1 |          1 |                           625 |                            0 |                          0 |                            0 |                          0 | 2025-06-12 22:29:16.357000 |      1851184769713369003 |
| {"id":10} |       0 |            1 |          1 |                           618 |                            0 |                          0 |                            0 |                          0 | 2025-06-12 22:29:16.357000 |      1851184769713369003 |
| {"id":4}  |       0 |            1 |          1 |                           618 |                            0 |                          0 |                            0 |                          0 | 2025-06-12 22:29:16.357000 |      1851184769713369003 |
| {"id":2}  |       0 |            1 |          1 |                           611 |                            0 |                          0 |                            0 |                          0 | 2025-06-12 22:29:16.357000 |      1851184769713369003 |
+-----------+---------+--------------+------------+-------------------------------+------------------------------+----------------------------+------------------------------+----------------------------+----------------------------+--------------------------+

注意:

  1. パーティション分割されていないTableの場合、partitionsTableにはpartitionとspec_idフィールドが含まれません。
  2. partitionsTableは、現在のスナップショットでデータファイルまたは削除ファイルを含むパーティションを表示します。ただし、削除ファイルは適用されないため、パーティション内のすべてのデータ行が削除ファイルによって削除済みとしてマークされている場合でも、パーティションが表示される場合があります。

refs​

Tableの既知のスナップショット参照（ブランチとタグ）をすべて表示します:

SELECT * FROM iceberg_table$refs;

結果:

+------+--------+---------------------+-------------------------+-----------------------+------------------------+
| name | type   | snapshot_id         | max_reference_age_in_ms | min_snapshots_to_keep | max_snapshot_age_in_ms |
+------+--------+---------------------+-------------------------+-----------------------+------------------------+
| main | BRANCH | 4890031351138056789 |                    NULL |                  NULL |                   NULL |
+------+--------+---------------------+-------------------------+-----------------------+------------------------+

snapshots​

Tableのすべてのスナップショットを表示します：

SELECT * FROM iceberg_table$snapshots;

結果:

+----------------------------+---------------------+---------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| committed_at               | snapshot_id         | parent_id           | operation | manifest_list                                                                                        | summary                                                                                                                                                                                                                                                                                                                      |
+----------------------------+---------------------+---------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 2025-06-12 22:29:16.357000 | 1851184769713369003 |                NULL | append    | s3://.../iceberg_table/metadata/snap-1851184769713369003-1-82059f57-821a-4983-b083-002cc2cde313.avro | {"spark.app.id":"application_1738810850199_0472", "added-data-files":"10", "added-records":"10", "added-files-size":"6200", "changed-partition-count":"10", "total-records":"10", "total-files-size":"6200", "total-data-files":"10", "total-delete-files":"0", "total-position-deletes":"0", "total-equality-deletes":"0"}  |
| 2025-06-12 22:29:39.922000 | 4890031351138056789 | 1851184769713369003 | overwrite | s3://.../iceberg_table/metadata/snap-4890031351138056789-1-3194eb8b-5ea4-4cbe-95ba-073229458e7b.avro | {"spark.app.id":"application_1738810850199_0472", "deleted-data-files":"5", "deleted-records":"5", "removed-files-size":"3103", "changed-partition-count":"5", "total-records":"5", "total-files-size":"3097", "total-data-files":"5", "total-delete-files":"0", "total-position-deletes":"0", "total-equality-deletes":"0"} |
+----------------------------+---------------------+---------------------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Write 運用​

INSERT INTO​

INSERT操作は対象Tableにデータを追加します。

例：

INSERT INTO iceberg_tbl VALUES (val1, val2, val3, val4);
INSERT INTO iceberg.iceberg_db.iceberg_tbl SELECT col1, col2 FROM internal.db1.tbl1;

INSERT INTO iceberg_tbl(col1, col2) VALUES (val1, val2);
INSERT INTO iceberg_tbl(col1, col2, partition_col1, partition_col2) VALUES (1, 2, 'beijing', '2023-12-12');

バージョン3.1.0以降、指定されたブランチへのデータ書き込みをサポート：

INSERT INTO iceberg_tbl@branch(b1) values (val1, val2, val3, val4);
INSERT INTO iceberg_tbl@branch(b1) (col3, col4) values (val3, val4);

INSERT OVERWRITE​

INSERT OVERWRITE操作は、Table内の既存データを新しいデータで完全に置き換えます。

INSERT OVERWRITE TABLE iceberg_tbl VALUES (val1, val2, val3, val4);
INSERT OVERWRITE TABLE iceberg.iceberg_db.iceberg_tbl(col1, col2) SELECT col1, col2 FROM internal.db1.tbl1;

バージョン3.1.0以降、指定されたブランチへのデータ書き込みをサポート：

INSERT OVERWRITE TABLE iceberg_tbl@branch(b1) values (val1, val2, val3, val4);
INSERT OVERWRITE TABLE iceberg_tbl@branch(b1) (col3, col4) values (val3, val4);

CTAS​

CTAS（Create Table As Select）ステートメントを使用してIcebergTableを作成し、データを書き込むことができます：

CREATE TABLE iceberg_ctas AS SELECT * FROM other_table;

CTASは、ファイル形式、パーティショニング、およびその他のプロパティの指定をサポートしています：

CREATE TABLE iceberg_ctas
PARTITION BY LIST (pt1, pt2) ()
AS SELECT col1, pt1, pt2 FROM part_ctas_src WHERE col1 > 0;

CREATE TABLE iceberg.iceberg_db.iceberg_ctas (col1, col2, pt1)
PARTITION BY LIST (pt1) ()
PROPERTIES (
    'write-format'='parquet',
    'compression-codec'='zstd'
)
AS SELECT col1, pt1 AS col2, pt2 AS pt1 FROM test_ctas.part_ctas_src WHERE col1 > 0;

INSERT INTO BRANCH​

Since 3.1.0以降

INSERT INTO iceberg_table@branch(b1) SELECT * FROM other_table;
INSERT OVERWRITE TABLE iceberg_table@branch(b1) SELECT * FROM other_table;

関連パラメータ​

  • BE (Backend)

    パラメータ名デフォルト値デスクリプション
    iceberg_sink_max_file_size1GBデータファイルの最大サイズ。書き込まれたデータがこのサイズを超えると、現在のファイルが閉じられ、新しいファイルが作成されて書き込みが継続されます。
    table_sink_partition_write_max_partition_nums_per_writer128BEノード上で各インスタンスが書き込み可能なパーティションの最大数。
    table_sink_non_partition_write_scaling_data_processed_threshold25MB非パーティション化Tableでスケーリング書き込みを開始するためのデータ閾値。追加のtable_sink_non_partition_write_scaling_data_processed_thresholdデータ量ごとに新しいライター（インスタンス）が使用されます。このメカニズムは、データ量に基づいてライター数を調整し、スループットを向上させると同時に、小さなデータ量に対してはリソースを節約し、ファイル数を最小化します。
    table_sink_partition_write_min_data_processed_rebalance_threshold25MBパーティション化Tableのリバランシングを開始する最小データ量閾値。現在の累積データ量 - 前回のリバランシング以降のデータ量 >= table_sink_partition_write_min_data_processed_rebalance_thresholdの場合にリバランシングが開始されます。この閾値を下げることで、ファイルサイズの差が大きい場合のバランスを改善できますが、リバランシングコストが増加し、パフォーマンスに影響を与える可能性があります。
    table_sink_partition_write_min_partition_data_processed_rebalance_thresholdリバランシングを開始する最小パーティションデータ量閾値。現在のパーティションデータ量 >= 閾値 * パーティションに既に割り当てられたタスク数の場合にリバランシングが開始されます。この閾値を下げることで、ファイルサイズの差が大きい場合のバランスを改善できますが、リバランシングコストが増加し、パフォーマンスに影響を与える可能性があります。

データベースとTable管理​

データベースの作成と削除​

SWITCH文を使用して目的のカタログに切り替えて、CREATE DATABASEコマンドを実行できます：

SWITCH iceberg;
CREATE DATABASE [IF NOT EXISTS] iceberg_db;

完全修飾名を使用してデータベースを作成することも、場所を指定することも可能です（現在、場所の指定をサポートしているのはHMS-type catalogsのみです）。例：

CREATE DATABASE [IF NOT EXISTS] iceberg.iceberg_db;

CREATE DATABASE [IF NOT EXISTS] iceberg.iceberg_db
PROPERTIES ('location'='hdfs://172.21.16.47:4007/path/to/db/');

データベースの場所情報はSHOW CREATE DATABASEコマンドを使用して確認できます：

mysql> SHOW CREATE DATABASE iceberg_db;
+-------------+-------------------------------------------------------------------------------------------------+
| Database    | Create Database                                                                                 |
+-------------+-------------------------------------------------------------------------------------------------+
| iceberg_db  | CREATE DATABASE iceberg_db LOCATION 'hdfs://172.21.16.47:4007/usr/hive/warehouse/iceberg_db.db' |
+-------------+-------------------------------------------------------------------------------------------------+

データベースを削除するには:

DROP DATABASE [IF EXISTS] iceberg.iceberg_db;
注意

Iceberg データベースの場合、データベース自体を削除する前に、データベース配下のすべてのTableを最初に削除する必要があります。そうしなければ、エラーが発生します。

Tableの作成と削除​

  • Tableの作成

    Doris は Iceberg でパーティション化されたTableと非パーティション化されたTableの両方の作成をサポートしています。

    例：

    -- Create unpartitioned iceberg table
    CREATE TABLE unpartitioned_table (
      `col1` BOOLEAN COMMENT 'col1',
      `col2` INT COMMENT 'col2',
      `col3` BIGINT COMMENT 'col3',
      `col4` FLOAT COMMENT 'col4',
      `col5` DOUBLE COMMENT 'col5',
      `col6` DECIMAL(9,4) COMMENT 'col6',
      `col7` STRING COMMENT 'col7',
      `col8` DATE COMMENT 'col8',
      `col9` DATETIME COMMENT 'col9'
    )
    PROPERTIES (
      'write-format'='parquet'
    );

    -- Create partitioned iceberg table
    -- The partition columns must be in table's column definition list
    CREATE TABLE partition_table (
      `ts` DATETIME COMMENT 'ts',
      `col1` BOOLEAN COMMENT 'col1',
      `col2` INT COMMENT 'col2',
      `col3` BIGINT COMMENT 'col3',
      `col4` FLOAT COMMENT 'col4',
      `col5` DOUBLE COMMENT 'col5',
      `col6` DECIMAL(9,4) COMMENT 'col6',
      `col7` STRING COMMENT 'col7',
      `col8` DATE COMMENT 'col8',
      `col9` DATETIME COMMENT 'col9',
      `pt1` STRING COMMENT 'pt1',
      `pt2` STRING COMMENT 'pt2'
    )
    PARTITION BY LIST (day(ts), pt1, pt2) ()
    PROPERTIES (
      'write-format'='orc',
      'compression-codec'='zlib'
    );

作成後、SHOW CREATE TABLEコマンドを使用してIcebergTableの作成文を確認できます。パーティション関数の詳細については、Partitioningセクションを参照してください。

  • Tableの削除

    DROP TABLE文を使用してIcebergTableを削除できます。Tableを削除すると、パーティションデータを含むデータも削除されます。

    例：

    DROP TABLE [IF EXISTS] iceberg_tbl;

  • Column タイプ Mapping

    Column タイプ Mapping セクションを参照してください。

  • パーティショニング

    IcebergのPartition typesは、DorisのListパーティションに対応します。したがって、DorisでIcebergパーティションTableを作成する際は、Listパーティショニング構文を使用する必要がありますが、各パーティションを明示的に列挙する必要はありません。Dorisは、データ挿入時にデータ値に基づいて対応するIcebergパーティションを自動的に作成します。

    • 単一列または複数列のパーティションTableの作成をサポートします。

    • Icebergの暗黙的パーティショニングとパーティション進化を可能にするパーティション変換関数をサポートします。具体的なIcebergパーティション変換関数については、Iceberg partition transformsを参照してください：

      • year(ts) または years(ts)

      • month(ts) または months(ts)

      • day(ts) または days(ts) または date(ts)

      • hour(ts) または hours(ts) または date_hour(ts)

      • bucket(N, col)

      • truncate(L, col)

  • ファイル形式

    • Parquet (デフォルト)

      Dorisによって作成されたIcebergTableでは、Datetimeはtimestamp_ntzタイプに対応することに注意してください。

      3.1.0以降のバージョンでは、DatetimeタイプがParquetファイルに書き込まれる際、使用される物理タイプはINT96ではなくINT64です。

      また、IcebergTableが他のシステムによって作成された場合、timestampとtimestamp_ntzタイプは両方ともDoris Datetimeタイプにマッピングされますが、書き込み時には実際のタイプに基づいてタイムゾーンの処理が必要かどうかを判断します。

    • ORC

  • 圧縮形式

    • Parquet: snappy、zstd (デフォルト)、plain (圧縮なし)。

    • ORC: snappy、zlib (デフォルト)、zstd、plain (圧縮なし)。

  • ストレージメディア

    • HDFS

    • オブジェクトストレージ

スキーマ変更​

3.1.0以降、DorisはIcebergTableのスキーマ変更をサポートしており、ALTER TABLE文を使用して変更できます。

サポートされるスキーマ変更操作には以下が含まれます：

  • 列名変更

    RENAME COLUMN句を使用して列名を変更します。ネストされたタイプ内での列名変更はサポートされていません。

    ALTER TABLE iceberg_table RENAME COLUMN old_col_name TO new_col_name;

  • 列の追加

    新しい列を追加するにはADD COLUMNを使用します。ネストされた型への新しい列の追加はサポートされていません。

    新しい列を追加する際、nullable属性、デフォルト値、コメント、および列の位置を指定できます。

    ALTER TABLE iceberg_table ADD COLUMN col_name col_type [NULL|NOT NULL, [DEFAULT default_value, [COMMENT 'comment', [FIRST|AFTER col_name]]]];

Example:

ALTER TABLE iceberg_table ADD COLUMN new_col STRING NOT NULL DEFAULT 'default_value' COMMENT 'This is a new col' AFTER old_col;

  • Add Columns

    ADD COLUMNを使用して複数の列を追加することもできます。新しい列はTableの末尾に追加されます。複数列に対する列の位置指定はサポートされていません。ネストした型への新しい列の追加はサポートされていません。

    各列の構文は単一列を追加する場合と同じです。

    ALTER TABLE iceberg_table ADD COLUMN (col_name1 col_type1 [NULL|NOT NULL, [DEFAULT default_value, [COMMENT 'comment']]], col_name2 col_type2 [NULL|NOT NULL, [DEFAULT default_value, [COMMENT 'comment']]] ...);

  • Drop Column

    DROP COLUMNを使用して列を削除します。ネストされた型内の列の削除はサポートされていません。

    ALTER TABLE iceberg_table DROP COLUMN col_name;

  • 列の変更

    MODIFY COLUMN文を使用して、型、null許可、デフォルト値、コメント、列位置を含む列属性を変更します。

    注意：列属性を変更する場合、変更されない全ての属性についても、元の値を明示的に指定する必要があります。

    ALTER TABLE iceberg_table MODIFY COLUMN col_name col_type [NULL|NOT NULL, [DEFAULT default_value, [COMMENT 'comment', [FIRST|AFTER col_name]]]];

Example:

CREATE TABLE iceberg_table (
    id INT,
    name STRING
);
-- Modify the id column type to BIGINT, set as NOT NULL, default value to 0, and add comment
ALTER TABLE iceberg_table MODIFY COLUMN id BIGINT NOT NULL DEFAULT 0 COMMENT 'This is a modified id column';

  • 列の並び替え

    ORDER BYを使用して、新しい列の順序を指定することで列を並び替えます。

    ALTER TABLE iceberg_table ORDER BY (col_name1, col_name2, ...);

パーティション Evolution​

バージョン4.0.2から、DorisはIcebergTableに対してALTER文を通じたPartition Evolutionをサポートしています。

サポートされるパーティション変換には以下が含まれます：

TransformSyntaxExample
bucketbucket(N, column)bucket(16, id)
truncatetruncate(N, column)truncate(10, name)
yearyear(column)year(ts)
monthmonth(column)month(ts)
dayday(column)day(ts)
hourhour(column)hour(ts)
identitycolumncategory

サポートされる操作には以下が含まれます：

  • パーティションキーの追加

    -- use optional AS keyword to specify a custom name for the partition field
    ALTER TABLE table_name ADD PARTITION KEY partition_transform [AS key_name];

    -- example
    ALTER TABLE prod.db.sample ADD PARTITION KEY bucket(16, id);
    ALTER TABLE prod.db.sample ADD PARTITION KEY truncate(4, data);
    ALTER TABLE prod.db.sample ADD PARTITION KEY year(ts);
    -- use optional AS keyword to specify a custom name for the partition field 
    ALTER TABLE prod.db.sample ADD PARTITION KEY bucket(16, id) AS shard;

  • パーティションキーの削除

    ALTER TABLE table_name DROP PARTITION KEY partition_transform｜key_name;

    -- example
    ALTER TABLE prod.db.sample DROP PARTITION KEY catalog;
    ALTER TABLE prod.db.sample DROP PARTITION KEY bucket(16, id);
    ALTER TABLE prod.db.sample DROP PARTITION KEY truncate(4, data);
    ALTER TABLE prod.db.sample DROP PARTITION KEY year(ts);
    ALTER TABLE prod.db.sample DROP PARTITION KEY shard;

  • パーティションキーの置換

    -- use optional AS keyword to specify a custom name for the partition field
    ALTER TABLE table_name REPLACE PARTITION KEY key_name WITH partition_transform [AS key_name];

    -- example
    ALTER TABLE prod.db.sample REPLACE PARTITION KEY ts_day WITH day(ts);
    -- use optional AS keyword to specify a custom name for the new partition field 
    ALTER TABLE prod.db.sample REPLACE PARTITION KEY ts_day WITH day(ts) AS day_of_ts;

Managing Branch & Tag​

Since 3.1.0

  • ブランチの作成

    構文:

    ALTER TABLE [catalog.][database.]table_name
    CREATE [OR REPLACE] BRANCH [IF NOT EXISTS] <branch_name>
    [AS OF VERSION <snapshot_id>]
    [RETAIN <num> { DAYS | HOURS | MINUTES }]
    [WITH SNAPSHOT RETENTION { snapshotKeep | timeKeep }]

    snapshotKeep:
      <num> SNAPSHOTS [<num> { DAYS | HOURS | MINUTES }]

    timeKeep:
      <num> { DAYS | HOURS | MINUTES }

例:

-- Create branch "b1".
ALTER TABLE tbl CREATE BRANCH b1;
ALTER TABLE tb1 CREATE BRANCH IF NOT EXISTS b1;
-- Create or replace branch "b1".
ALTER TABLE tb1 CREATE OR REPLACE BRANCH b1;
-- Create or replace branch "b1" based on snapshot "123456".
ALTER TABLE tb1 CREATE OR REPLACE BRANCH b1 AS OF VERSION 123456;
-- Create or replace branch "b1" based on snapshot "123456", branch retained for 1 day.
ALTER TABLE tb1 CREATE OR REPLACE BRANCH b1 AS OF VERSION 123456 RETAIN 1 DAYS;
-- Create branch "b1" based on snapshot "123456", branch retained for 30 days. Keep the latest 3 snapshots in the branch.
ALTER TABLE tb1 CREATE BRANCH b1 AS OF VERSION 123456 RETAIN 30 DAYS WITH SNAPSHOT RETENTION 3 SNAPSHOTS;
-- Create branch "b1" based on snapshot "123456", branch retained for 30 days. Snapshots in the branch are retained for at most 2 days.
ALTER TABLE tb1 CREATE BRANCH b1 AS OF VERSION 123456 RETAIN 30 DAYS WITH SNAPSHOT RETENTION 2 DAYS;
-- Create branch "b1" based on snapshot "123456", branch retained for 30 days. Keep the latest 3 snapshots in the branch, and snapshots in the branch are retained for at most 2 days.
ALTER TABLE tb1 CREATE BRANCH b1 AS OF VERSION 123456 RETAIN 30 DAYS WITH SNAPSHOT RETENTION 3 SNAPSHOTS 2 DAYS;

  • Drop Branch

    構文:

    ALTER TABLE [catalog.][database.]table_name
    DROP BRANCH [IF EXISTS] <branch_name>;

Example:

ALTER TABLE tbl DROP BRANCH b1;

  • タグの作成

    構文:

    ALTER TABLE [catalog.][database.]table_name
    CREATE [OR REPLACE] TAG [IF NOT EXISTS] <tag_name>
    [AS OF VERSION <snapshot_id>]
    [RETAIN <num> { DAYS | HOURS | MINUTES }]

例：

-- Create tag "t1".
ALTER TABLE tbl CREATE TAG t1;
ALTER TABLE tb1 CREATE TAG IF NOT EXISTS t1;
-- Create or replace tag "t1".
ALTER TABLE tb1 CREATE OR REPLACE TAG t1;
-- Create or replace tag "t1" based on snapshot "123456".
ALTER TABLE tb1 CREATE OR REPLACE TAG b1 AS OF VERSION 123456;
-- Create or replace tag "b1" based on snapshot "123456", tag retained for 1 day.
ALTER TABLE tb1 CREATE OR REPLACE TAG b1 AS OF VERSION 123456 RETAIN 1 DAYS;

  • Drop Tag

    構文:

    ALTER TABLE [catalog.][database.]table_name
    DROP TAG [IF EXISTS] <tag_name>;

Example:

ALTER TABLE tbl DROP TAG t1;

Iceberg Table Actions​

この機能は4.0.2からサポートされています

これは実験的機能です。

DorisはIcebergTableに対してALTER TABLE EXECUTE構文を通じて特定のアクションを実行することをサポートしています。この構文は、Table最適化やスナップショット管理などの様々なアクションを実行するための統一されたインターフェースを提供します。

ALTER TABLE [catalog.][database.]table_name
EXECUTE <action_name> ("key1" = "value1", "key2" = "value2", ...)
[WHERE <condition>]
  • action_name: 実行するアクションの名前
  • ("key1" = "value1", ...): キーバリューペアとして提供されるアクション関連のパラメータ。パラメータ名は二重引用符で囲む必要があります
  • [WHERE <condition>]: 操作対象のパーティションまたはデータ範囲を指定するオプションのWHERE条件（一部の操作のみサポート）

rewrite_data_files​

rewrite_data_files操作は、IcebergTable内のデータファイルを書き換えて小さなファイルの結合を実装し、クエリパフォーマンスとストレージ効率を最適化します。これは同期操作です。

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE rewrite_data_files ("key1" = "value1", "key2" = "value2", ...) [WHERE <condition>]

パラメータ:

パラメータ名タイプデフォルト値デスクリプション
target-file-size-bytesLong536870912 (512MB)出力ファイルの目標ファイルサイズ（バイト単位）
min-file-size-bytesLongtarget-file-size-bytes * 0.75最小ファイルサイズ（バイト単位）。このサイズより小さいファイルは書き換えられます。指定されない場合、目標ファイルサイズの75%がデフォルトになります
max-file-size-bytesLongtarget-file-size-bytes * 1.8最大ファイルサイズ（バイト単位）。このサイズより大きいファイルは分割されます。指定されない場合、目標ファイルサイズの180%がデフォルトになります
min-input-filesInteger5書き換えを実行する最小入力ファイル数。書き換え対象のファイル数がこの閾値に達した時のみ書き換えが実行されます
rewrite-allBooleanfalseファイルサイズに関係なくすべてのファイルを書き換えるかどうか
max-file-group-size-bytesLong107374182400 (100GB)ファイルグループの最大サイズ（バイト単位）。単一の書き換えタスクで処理されるデータ量を制限するために使用されます
delete-file-thresholdIntegerInteger.MAX_VALUE書き換えを実行するために必要な削除ファイルの最小数
delete-ratio-thresholdDouble0.3書き換えを実行するために必要な削除レコードと全レコードの最小比率（削除レコード / 全レコード）。範囲: 0.0 - 1.0
output-spec-idLong2出力ファイルのパーティション仕様ID

戻り値:

rewrite_data_filesを実行すると、以下の4列を含む結果セットが返されます:

Column Nameタイプデスクリプション
rewritten_data_files_countINT書き換えられたデータファイルの数
added_data_files_countINT新たに書き込まれたデータファイルの数
rewritten_bytes_countINT書き換えられたバイト数
removed_delete_files_countBIGINT削除された削除ファイルの数

例:

-- Rewrite data files with default parameters
ALTER TABLE iceberg_db.iceberg_table EXECUTE rewrite_data_files();

-- Specify target file size and minimum input files
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE rewrite_data_files (
  "target-file-size-bytes" = "134217728",
  "min-input-files" = "10"
);

-- Use WHERE condition to rewrite specific partition data
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE rewrite_data_files (
  "target-file-size-bytes" = "268435456"
)
WHERE date_col = '2024-01-01';

-- Rewrite all files
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE rewrite_data_files (
  "rewrite-all" = "true",
  "target-file-size-bytes" = "536870912"
);

注意:

  1. rewrite_data_files オペレーションはデータファイルを読み取って書き直すため、追加のI/Oと計算オーバーヘッドが発生します。クラスターリソースを適切に割り当ててください。
  2. 実行前に、View Data File Distribution セクションのSQLを使用して、リライトオペレーションが必要かどうかを評価できます
  3. WHERE条件を使用して、リライト対象のパーティションやデータ範囲を制限できます。この条件により、WHERE条件に一致するデータを含まないファイルが除外され、リライト対象のファイル数とデータ量が削減されます
  4. 実行前に、Rewrite File Selection Logic セクションのSQLを使用して、どのファイルがリライトされるかを計算できます

cherrypick_snapshot​

cherrypick_snapshot オペレーションは、指定されたスナップショットからの変更を現在のTable状態にマージし、元のスナップショットを変更または削除することなく新しいスナップショットを作成します。

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE cherrypick_snapshot ("snapshot_id" = "<snapshot_id>")

パラメータ:

パラメータ名タイプRequiredデスクリプション
snapshot_idLongYesマージするスナップショットID

戻り値:

cherrypick_snapshotを実行すると、以下の2つの列を持つ結果セットが返されます：

Column Nameタイプデスクリプション
source_snapshot_idBIGINT変更がマージされたスナップショットID
current_snapshot_idBIGINTマージ操作後に作成され、現在として設定された新しいスナップショットのスナップショットID

例:

-- Merge changes from snapshot 123456789 into current table state
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE cherrypick_snapshot ("snapshot_id" = "123456789");

注意:

  1. この操作はWHERE条件をサポートしていません
  2. 指定されたスナップショットが存在しない場合、操作は失敗します
  3. マージ操作は新しいスナップショットを作成し、元のスナップショットは削除しません

fast_forward​

fast_forward操作は、あるブランチの現在のスナップショットを、別のブランチの最新のスナップショットにfast-forwardします。

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE fast_forward ("branch" = "<branch_name>", "to" = "<target_branch>")

パラメータ:

パラメータ名タイプRequiredデスクリプション
branchStringYesfast-forwardするブランチ名
toStringYesターゲットブランチ名。branchはこのブランチの最新スナップショットまでfast-forwardされます

戻り値:

fast_forwardを実行すると、以下の3つのカラムを持つ結果セットが返されます:

Column Nameタイプデスクリプション
branch_updatedSTRINGfast-forwardされたブランチ名
previous_refBIGINTfast-forward操作前にブランチが指していたスナップショットID（NULLの場合があります）
updated_refBIGINTfast-forward操作後にブランチが指しているスナップショットID

例:

-- Fast-forward feature branch to the latest snapshot of main branch
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE fast_forward ("branch" = "feature", "to" = "main");

注意:

  1. この操作はWHERE条件をサポートしません
  2. 指定されたブランチが存在しない場合、操作は失敗します
  3. fast-forwardできるのはブランチのみで、タグはできません

rollback_to_snapshot​

rollback_to_snapshot操作は、IcebergTableを指定されたスナップショットにロールバックします。

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE rollback_to_snapshot ("snapshot_id" = "<snapshot_id>")

パラメータ:

パラメータ名タイプRequiredデスクリプション
snapshot_idLongYesロールバック先のスナップショットID

戻り値:

rollback_to_snapshotを実行すると、以下の2つのカラムを含む結果セットが返されます:

Column Nameタイプデスクリプション
previous_snapshot_idBIGINTロールバック操作前に現在であったスナップショットID
current_snapshot_idBIGINT指定されたスナップショットにロールバック後に現在として設定されるスナップショットID

例:

-- Rollback to snapshot 987654321
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE rollback_to_snapshot ("snapshot_id" = "987654321");

注意事項:

  1. この操作はWHERE条件をサポートしていません
  2. 指定されたスナップショットが存在しない場合、操作は失敗します
  3. 現在のスナップショットが既にターゲットスナップショットである場合、操作は新しいスナップショットを作成せずに直接復帰します

rollback_to_timestamp​

rollback_to_timestamp操作は、指定されたタイムスタンプでのスナップショットにIcebergTableをロールバックします。

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE rollback_to_timestamp ("timestamp" = "<timestamp>")

パラメータ:

パラメータ名タイプRequiredデスクリプション
timestampStringYesロールバック先のタイムスタンプ。2つの形式をサポートします:
1. ISO datetime形式: yyyy-MM-dd HH:mm:ss.SSS (例: 2024-01-01 10:30:00.000)
2. ミリ秒タイムスタンプ (例: 1704067200000)

戻り値:

rollback_to_timestampを実行すると、以下の2つの列を持つ結果セットが返されます:

Column Nameタイプデスクリプション
previous_snapshot_idBIGINTロールバック操作前に現在だったスナップショットID
current_snapshot_idBIGINT指定されたタイムスタンプで現在だったスナップショットIDで、現在として設定されたもの

例:

-- Rollback to specified timestamp (ISO format)
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE rollback_to_timestamp ("timestamp" = "2024-01-01 10:30:00.000");

-- Rollback to specified timestamp (timestamp format)
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE rollback_to_timestamp ("timestamp" = "1704067200000");

注意:

  1. この操作はWHERE条件をサポートしていません
  2. timestampパラメータはISO datetime形式（yyyy-MM-dd HH:mm:ss.SSS）またはミリ秒timestamp形式をサポートします
  3. 指定されたtimestampに対応するsnapshotが存在しない場合、操作は失敗します

set_current_snapshot​

set_current_snapshot操作は、IcebergTableの現在のsnapshotを指定されたsnapshot IDまたはreference（branchまたはtag）に設定します。

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE set_current_snapshot ("snapshot_id" = "<snapshot_id>" | "ref" = "<ref_name>")

パラメータ:

パラメータ名タイプRequiredデスクリプション
snapshot_idLongいずれか一つ現在として設定するスナップショットID
refStringいずれか一つ現在として設定する参照名（ブランチまたはタグ）

戻り値:

set_current_snapshotを実行すると、以下の2つの列を持つ結果セットが返されます:

Column Nameタイプデスクリプション
previous_snapshot_idBIGINT新しい現在のスナップショットを設定する前に現在だったスナップショットID
current_snapshot_idBIGINT現在として設定されたスナップショットID（snapshot_idパラメータから、またはrefパラメータから解決された）

例:

-- Set current snapshot by snapshot ID
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE set_current_snapshot ("snapshot_id" = "123456789");

-- Set current snapshot by branch name
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE set_current_snapshot ("ref" = "feature_branch");

-- Set current snapshot by tag name
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE set_current_snapshot ("ref" = "v1.0");

注意:

  1. この操作はWHERE条件をサポートしていません
  2. snapshot_idとrefパラメータは相互排他的です。どちらか一方のみを指定できます
  3. 指定されたスナップショットIDまたはリファレンスが存在しない場合、操作は失敗します
  4. 現在のスナップショットが既にターゲットスナップショットと同じ場合、操作は新しいスナップショットを作成せずに直接戻ります

IcebergTableの最適化​

データファイル分散の表示​

以下のSQLを使用してIcebergTableのデータ分散と削除ファイル数を分析し、rewrite_data_filesなどの最適化が必要かどうかを判断することができます。

  • データファイルサイズの分散を表示します。これにより、過多な

    SELECT
      CASE
        WHEN file_size_in_bytes BETWEEN 0 AND 8 * 1024 * 1024 THEN '0-8M'
        WHEN file_size_in_bytes BETWEEN 8 * 1024 * 1024 + 1 AND 32 * 1024 * 1024 THEN '8-32M'
        WHEN file_size_in_bytes BETWEEN 2 * 1024 * 1024 + 1 AND 128 * 1024 * 1024 THEN '32-128M'
        WHEN file_size_in_bytes BETWEEN 128 * 1024 * 1024 + 1 AND 512 * 1024 * 1024 THEN '128-512M'
        WHEN file_size_in_bytes > 512 * 1024 * 1024 THEN '> 512M'
        ELSE 'Unknown'
      END AS SizeRange,
      COUNT(*) AS FileNum
    FROM store_sales$data_files
    GROUP BY
      SizeRange;

    +-----------+---------+
    | SizeRange | FileNum |
    +-----------+---------+
    | 0-8M      |       8 |
    | 8-32M     |       6 |
    +-----------+---------+

  • データファイル数と削除ファイル数を表示する

    SELECT
      CASE
        WHEN content = 0 THEN 'DataFile'
        WHEN content = 1 THEN 'PositionDeleteFile'
        WHEN content = 2 THEN 'EqualityDeleteFile'
        ELSE 'Unknown'
      END AS ContentType,
      COUNT(*) AS FileNum,
      SUM(file_size_in_bytes) AS SizeInBytes,
      SUM(record_count) AS Records
    FROM
      iceberg_table$files
    GROUP BY
      ContentType;

    +--------------------+---------+-------------+---------+
    | ContentType        | FileNum | SizeInBytes | Records |
    +--------------------+---------+-------------+---------+
    | EqualityDeleteFile |    2787 |     1432518 |   27870 |
    | DataFile           |    2787 |     4062416 |   38760 |
    | PositionDeleteFile |      11 |       36608 |   10890 |
    +--------------------+---------+-------------+---------+

Dangling Delete​

一部のケースでは、rewrite_data_filesアクションの実行後、特定のPosition Deleteへの参照がSnapshotメタデータから削除されていない場合があります（Dangling Delete）。この状況で直接メタデータの行番号情報を使用すると、結果が正しくない可能性があります。

そのため、デフォルトでは、COUNT(*)クエリにおいて、Position Deleteファイルが見つかった場合、COUNTプッシュダウン最適化は有効にされず、代わりにファイルを直接読み取って実際のCOUNT(*)結果を取得します。ただし、この方法は時間がかかります。

ユーザーがDangling Deleteの問題がないことを保証できる場合、Dorisセッション変数ignore_iceberg_dangling_deleteを使用してこのチェックをスキップできます。この変数はデフォルトでfalseです。trueに設定すると、システムはメタデータ内の行数情報に基づいて直接COUNT(*)結果を返し、クエリ効率を向上させます。

この機能はバージョン3.1.4および4.0.3からサポートされています。

付録​

rewrite_data_filesファイル選択戦略​

このセクションを確認することで、書き換え対象ファイルの選択ロジックを理解できます。また、以下のSQLクエリを使用してシステムTable情報に基づいてどのファイルが書き換えられるかを分析することもできます。これにより、実際の書き換え操作を実行する前に書き換え動作をデバッグし理解するのに役立ちます。

書き換え操作は2段階のフィルタリングおよびグループ化戦略を使用します：

  1. ステージ1：ファイルレベルフィルタリング

    まず、ファイルレベル条件に基づいてファイルがフィルタリングされます。以下の条件のうち少なくとも1つを満たすファイルのみが書き換え対象として考慮されます：

    1. ファイルサイズが範囲外：ファイルがmin-file-size-bytesより小さいか、max-file-size-bytesより大きい
    2. 削除ファイルが多すぎる：関連する削除ファイル数がdelete-file-threshold以上
    3. 削除比率が高い：削除レコード比率がdelete-ratio-threshold以上

    削除ファイル条件についての注意： 削除ファイルに関連する条件（delete-file-thresholdとdelete-ratio-threshold）はファイル書き換え選択に影響しますが、システムTableSQLクエリでは正確に計算できません。これは、現在のシステムTable情報では、どのデータファイルが削除ファイルの影響を受けるかを正確に判定するには不十分だからです。削除ファイルは特定のデータファイルのみに影響する可能性があり（特にPosition Deleteファイル）、削除ファイルとデータファイル間の関連付けには、現在のシステムTableでは利用できないより詳細なメタデータが必要です。実際の書き換え操作では、システムTableで公開されていないより詳細なメタデータに基づいてこれらの条件が評価されます。

  2. ステージ2：BinPackグループ化とグループレベルフィルタリング

    ファイルレベルフィルタリングの後、ファイルはパーティションごとにグループ化され、各パーティション内で、ファイルはファイルサイズとmax-file-group-size-bytesに基づいてBinPackアルゴリズムを使用してグループ化されます。BinPackアルゴリズムは書き換え操作を最適化するためにファイルをインテリジェントにグループにパックします。

    グループ化後、ファイルグループはグループレベル条件に基づいてフィルタリングされます。ファイルグループは以下の条件のうち少なくとも1つを満たす場合に書き換えられます：

    1. 十分な入力ファイル：グループ内のファイル数 > 1 かつ ファイル数がmin-input-files以上
    2. 十分なコンテンツ：グループ内のファイル数 > 1 かつ 合計サイズがtarget-file-size-bytesより大きい
    3. コンテンツが多すぎる：グループの合計サイズがmax-file-group-size-bytesより大きい
    4. 削除ファイル問題を含むファイルが存在：グループ内の少なくとも1つのファイルに削除ファイルが多すぎるか削除比率が高い

    BinPackグループ化についての注意： 各パーティション内でファイルをグループ化するために使用されるBinPackアルゴリズムは、システムTableSQLクエリでは正確にシミュレートできない複雑な最適化アルゴリズムです。このアルゴリズムはファイルサイズとmax-file-group-size-bytesを考慮してファイルをインテリジェントにグループにパックするため、単純なパーティションベースのグループ化とは異なるグループ化結果になる場合があります。したがって、以下に提供されるSQLクエリは、ファイルレベル条件を満たすファイルのみを特定できますが、書き換えられる最終的なファイルグループを正確に計算することはできません。

以下にいくつかのクエリ戦略の例を示します：

  • クエリ1：ファイルレベル条件を満たすファイルの特定

    このクエリは、ファイルレベル条件（ファイルサイズ）を満たし、書き換え対象として考慮されるファイルを特定します：

    -- Set parameters (adjust according to your rewrite parameters)
    SET @min_file_size_bytes = 16 * 1024 * 1024;   -- 16 MB (default: target-file-size-bytes * 0.75)
    SET @max_file_size_bytes = 768 * 1024 * 1024;  -- 768 MB (default: target-file-size-bytes * 1.8)

    SELECT 
        file_path,
        `partition`,
        file_size_in_bytes / 1024.0 / 1024.0 AS file_size_mb,
        record_count,
        CASE 
            WHEN file_size_in_bytes < @min_file_size_bytes THEN 'Too small'
            WHEN file_size_in_bytes > @max_file_size_bytes THEN 'Too large'
        END AS size_issue
    FROM iceberg_table$data_files
    WHERE file_size_in_bytes < @min_file_size_bytes 
    OR file_size_in_bytes > @max_file_size_bytes
    ORDER BY `partition`, file_size_in_bytes DESC;

サンプル出力:

+----------------------------------------------------------------------------------------+---------------------------+-------------+--------------+------------+
| file_path                                                                             | partition                 | file_size_mb | record_count | size_issue |
+----------------------------------------------------------------------------------------+---------------------------+-------------+--------------+------------+
| s3a://bucket/path/to/table/data/date_col=2024-01-01/00000-0-00000-00000-0.parquet   | {"date_col":"2024-01-01"} |     0.00215  |            5 | Too small  |
| s3a://bucket/path/to/table/data/date_col=2024-01-01/00001-0-00001-00001-0.parquet     | {"date_col":"2024-01-01"} |     0.00198  |            5 | Too small  |
| s3a://bucket/path/to/table/data/date_col=2024-01-02/00002-0-00002-00002-0.parquet     | {"date_col":"2024-01-02"} |     0.00231  |            5 | Too small  |
| s3a://bucket/path/to/table/data/date_col=2024-01-02/00003-0-00003-00003-0.parquet     | {"date_col":"2024-01-02"} |   850.23456  |      1250000 | Too large  |
| s3a://bucket/path/to/table/data/date_col=2024-01-03/00004-0-00004-00004-0.parquet     | {"date_col":"2024-01-03"} |     0.00245  |            5 | Too small  |
+----------------------------------------------------------------------------------------+---------------------------+-------------+--------------+------------+
5 rows in set

注意: このクエリは、ファイルレベル条件（ファイルサイズ）を満たすファイルのみを特定できます。実際に書き換えられるファイルグループは、BinPackグルーピングアルゴリズムに依存し、SQLクエリでは正確にシミュレートできません。このクエリで特定されたファイルは、BinPackアルゴリズムによって異なる方法でグループ化される可能性があり、一部のグループはグループレベル条件に基づいてフィルタリングされる可能性があります。

  • Query 2: 全体統計サマリー

    このクエリは、ファイルレベル条件を満たすファイルに関する全体統計を提供します：

    -- Set parameters (adjust according to your rewrite parameters)
    SET @min_file_size_bytes = 16 * 1024 * 1024;
    SET @max_file_size_bytes = 768 * 1024 * 1024;

    WITH file_analysis AS (
        SELECT 
            `partition`,
            file_path,
            file_size_in_bytes,
            record_count,
            (file_size_in_bytes < @min_file_size_bytes OR file_size_in_bytes > @max_file_size_bytes) AS meets_file_level_conditions
        FROM iceberg_table$data_files
    )
    SELECT 
        'Total files' AS metric, 
        COUNT(*) AS value
    FROM file_analysis
    UNION ALL
    SELECT 
        'Files meeting file-level conditions', 
        SUM(CASE WHEN meets_file_level_conditions THEN 1 ELSE 0 END)
    FROM file_analysis
    UNION ALL
    SELECT 
        'Total size (GB)', 
        ROUND(SUM(file_size_in_bytes) / 1024.0 / 1024.0 / 1024.0, 2)
    FROM file_analysis
    UNION ALL
    SELECT 
        'Size meeting file-level conditions (GB)', 
        ROUND(SUM(CASE WHEN meets_file_level_conditions THEN file_size_in_bytes ELSE 0 END) / 1024.0 / 1024.0 / 1024.0, 2)
    FROM file_analysis
    UNION ALL
    SELECT 
        'Percentage meeting file-level conditions (%)', 
        ROUND(SUM(CASE WHEN meets_file_level_conditions THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2)
    FROM file_analysis;

サンプル出力:

+----------------------------------------------+--------+
| metric                                       | value  |
+----------------------------------------------+--------+
| Total files                                  |  15.00 |
| Total size (GB)                              |   2.45 |
| Files meeting file-level conditions          |  12.00 |
| Size meeting file-level conditions (GB)      |   1.85 |
| Percentage meeting file-level conditions (%) |  80.00 |
+----------------------------------------------+--------+
5 rows in set

注意:

  • 例のiceberg_tableを実際のTable名に置き換えてください

  • パラメータ値（@min_file_size_bytes、@max_file_size_bytes）を実際のrewriteパラメータに応じて調整してください

  • 上記に示されているデフォルト値は、デフォルトのrewriteパラメータに対応しています（min-file-size-bytes = target-file-size-bytes * 0.75、max-file-size-bytes = target-file-size-bytes * 1.8）

  • スナップショットとブランチの関係を表示

    SELECT
    refs_data.snapshot_id,
    snapshots.committed_at,
    snapshots.operation,
    ARRAY_SORT(refs_data.refs)
    FROM (
    SELECT
        snapshot_id,
        ARRAY_AGG(CONCAT(type, ':', name)) AS refs
    FROM
        iceberg_table$refs
    GROUP BY
        snapshot_id
    ) AS refs_data
    JOIN (
    SELECT
        snapshot_id,
        committed_at,
        operation
    FROM
        iceberg_table$snapshots
    ) AS snapshots
    ON refs_data.snapshot_id = snapshots.snapshot_id
    ORDER BY
    snapshots.committed_at;

    +---------------------+----------------------------+-----------+-------------------------------------+
    | snapshot_id         | committed_at               | operation | ARRAY_SORT(refs_data.refs)          |
    +---------------------+----------------------------+-----------+-------------------------------------+
    | 8272911997874079853 | 2025-07-10 15:27:07.177000 | append    | ["BRANCH:b1", "TAG:t1"]             |
    | 1325777059626757917 | 2025-07-10 15:27:07.530000 | append    | ["BRANCH:b2", "TAG:t2"]             |
    |   76492482642020578 | 2025-07-10 15:27:07.865000 | append    | ["BRANCH:b3", "TAG:t3"]             |
    | 1788715857849070138 | 2025-07-12 04:15:19.626000 | append    | ["BRANCH:main", "TAG:t4", "TAG:t5"] |
    +---------------------+----------------------------+-----------+-------------------------------------+
このページでは