メインコンテンツまでスキップ

Iceberg カタログ

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

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

ヒント

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

適用シナリオ​

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

Catalogの設定​

構文​

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 Catalogインターフェースと互換性のあるメタデータサービス。

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

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

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

    • s3tables: AWS S3 Tables Catalogを使用してS3 Table Bucketにアクセスします。

  • <warehouse>

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

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

  • {MetaStoreProperties}

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

  • {StorageProperties}

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

  • {IcebergProperties}

    IcebergPropertiesセクションは、Iceberg Catalogに特有のパラメータを入力するために使用されます。

    • list-all-tables

      Hive Metastoreをメタデータサービスとして使用するIceberg Catalog用。デフォルトはtrueです。デフォルトでは、SHOW TABLES操作は現在のDatabaseのすべての種類のテーブルを一覧表示します（Hive MetastoreはIceberg以外のタイプのテーブルも保存する場合があります）。この方式が最良のパフォーマンスを提供します。

      falseに設定すると、Dorisは各テーブルのタイプを1つずつチェックし、Icebergタイプのテーブルのみを返します。このモードは、テーブルが多い場合にパフォーマンスが低下します。

  • {CommonProperties}

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

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

DorisバージョンIceberg SDKバージョン
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]セクションを参照してください。

Iceberg Catalog機能サポートマトリックス​

メタデータサービステーブルクエリビュークエリDDL操作データライトバックシステムテーブル（3.1+でサポート）
Hive MetaStore✅✅✅✅✅
AWS Glue✅✅❌❌✅
Aliyun DLF✅✅❌❌❌
Iceberg Rest Catalog✅✅サービスプロバイダーに依存サービスプロバイダーに依存サービスプロバイダーに依存
FileSystem✅✅✅✅✅

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

注：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)/timestamptz(6)精度6のdatetimeにマップされます。enable.mapping.timestamp_tzプロパティ（バージョン4.0.3以降でサポート）がマッピング動作を制御します。デフォルトではfalseに設定されており、この場合タイプはdatetimeにマップされます。trueに設定すると、timestamptzタイプにマップされます。
fixed(N)char(N)
stringstring
binarystring/varbinaryCatalogのenable.mapping.varbinaryプロパティによって制御されます（4.0.2以降でサポート）。デフォルトはfalseで、stringにマップされます。trueの場合、varbinaryタイプにマップされます。
uuidstring/varbinaryversion < 4.0.2ではstringタイプにマップされます。version == 4.0.2ではvarbinaryタイプにマップされます。version > 4.0.2では、propertiesのenable.mapping.varbinaryプロパティによって制御されます。デフォルトはfalseで、stringにマップされます。
structstruct（バージョン2.1.3からサポート）
mapmap（バージョン2.1.3からサポート）
listarray
その他UNSUPPORTED

注：

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

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

バージョン4.0.3以降でサポートされ、timestamptz（timestamp with time zone）はDoris timestamptzタイプにマップできます。

Namespaceマッピング​

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

      ┌─────────┐             
      │ Catalog │             
      └────┬────┘             
           │                  
     ┌─────┴─────┐            
  ┌──▼──┐     ┌──▼──┐         
  │ NS1 │     │ NS2 │         
  └──┬──┘     └──┬──┘         
     │           │            
┌────▼───┐    ┌──▼──┐         
│ Table1 │    │ NS3 │         
└────────┘    └──┬──┘         
                 │            
          ┌──────┴───────┐    
     ┌────▼───┐     ┌────▼───┐
     │ Table2 │     │ Table3 │
     └────────┘     └────────┘

バージョン3.1.2から、Iceberg Rest Catalogについて、DorisはNested Namespaceのマッピングをサポートしています。

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

CatalogDatabaseTable
CatalogNS1Table1
CatalogNS2.NS3Table2
CatalogNS2.NS3Table3

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

例​

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

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

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

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

Iceberg JDBC Catalog​

Note

これは実験的機能で、バージョン4.1.0以降でサポートされています。

4.1+ Version

S3でメタデータストレージとしてPostgreSQLを使用

CREATE CATALOG iceberg_jdbc_postgresql PROPERTIES (
    'type' = 'iceberg',
    'iceberg.catalog.type' = 'jdbc',
    'iceberg.jdbc.uri' = 'jdbc:postgresql://127.0.0.1:5432/iceberg_db',
    'iceberg.jdbc.user' = 'iceberg_user',
    'iceberg.jdbc.password' = 'password',
    'iceberg.jdbc.init-catalog-tables' = 'true',
    'iceberg.jdbc.schema-version' = 'V1',
    'iceberg.jdbc.driver_class' = 'org.postgresql.Driver',
    'iceberg.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'
);

FileSystem​

3.1+ バージョン

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

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

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

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 Integrationのドキュメントを参照してください。

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 テーブルの特定のスナップショットを読み取ることができます。

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

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

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;

Branch と Tag​

3.1.0以降

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

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

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ビューのクエリをサポートしています。ビューのクエリは通常のテーブルクエリと同じように動作します。以下の点にご注意ください：

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

System Tables​

Since 3.1.0

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

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

SELECT * FROM iceberg_table$system_table_name;

例えば、テーブルの履歴を表示するには、次のように実行できます：

SELECT * FROM iceberg_table$history;

all_manifests システムテーブルはバージョン 4.0.4 以降でサポートされています。

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

entries​

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

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​

テーブルの現在のスナップショットのファイル一覧を表示します：

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システムテーブルと同様に、以下のシステムテーブルを通じて特定のファイルタイプ情報を照会することもできます：

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

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

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

history​

テーブルのすべての履歴を表示します：

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​

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

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

all_manifests​

この機能はバージョン4.0.4から サポートされています

テーブルのすべての有効なスナップショットのマニフェストファイル情報を表示します：

all_manifestsとmanifestsは同じ構造を持ちます。違いは、all_manifestsがすべての有効なスナップショットからのマニフェストファイルを含むのに対し、manifestsは現在のスナップショットからのマニフェストファイルのみを含むことです。

SELECT * FROM iceberg_table$all_manifests;

結果のフォーマットはmanifestsシステムテーブルと同じです。

metadata_log_entries​

テーブルのメタログを表示します：

SELECT * FROM iceberg_table$metadata_log_entries;

結果:

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

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

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. 非パーティション化テーブルの場合、partitionsテーブルにはpartitionおよびspec_idフィールドが含まれません。
  2. partitionsテーブルは、現在のスナップショットでデータファイルまたは削除ファイルを含むパーティションを表示します。ただし、削除ファイルは適用されないため、パーティション内のすべてのデータ行が削除ファイルによって削除済みとしてマークされている場合でも、パーティションが表示される場合があります。

refs​

テーブルの既知のすべてのスナップショット参照（ブランチおよびタグ）を表示します：

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​

テーブルのすべてのスナップショットを表示します：

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

書き込み操作​

INSERT INTO​

INSERT操作は対象のテーブルにデータを追加します。

例：

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操作は、テーブル内の既存データを新しいデータで完全に置き換えます。

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

バージョン4.1.0以降、静的パーティション（またはハイブリッド）へのデータ書き込みをサポートします：

-- Full Static Partition
INSERT OVERWRITE TABLE iceberg_tbl PARTITION (dt='2025-01-25', region='bj')
SELECT id, name FROM source_table;

-- Hybrid Partition Mode: "dt" is static, "region" comes from SELECT dynamically
INSERT OVERWRITE TABLE iceberg_tbl PARTITION (dt='2025-01-25')
SELECT id, name, region FROM source_table;

CTAS​

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

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​

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_sink_non_partition_write_scaling_data_processed_threshold分の追加データごとに新しいライター（インスタンス）が使用されます。このメカニズムはデータ量に基づいてライターの数を調整し、スループットを向上させる一方で、小さなデータ量についてはリソースを節約し、ファイル数を最小化します。
    table_sink_partition_write_min_data_processed_rebalance_threshold25MBパーティションテーブルでリバランシングをトリガーする最小データ量閾値。現在の累積データ量 - 前回のリバランシング以降のデータ量 >= table_sink_partition_write_min_data_processed_rebalance_thresholdの場合にリバランシングが開始されます。この閾値を下げるとファイルサイズの差が大きい場合にバランスが改善される可能性がありますが、リバランシングコストが増加し、パフォーマンスに影響を与える可能性があります。
    table_sink_partition_write_min_partition_data_processed_rebalance_thresholdリバランシングをトリガーする最小パーティションデータ量閾値。現在のパーティションデータ量 >= 閾値 * パーティションに既に割り当てられているタスク数の場合にリバランシングが開始されます。この閾値を下げるとファイルサイズの差が大きい場合にバランスが改善される可能性がありますが、リバランシングコストが増加し、パフォーマンスに影響を与える可能性があります。

データベースとテーブル管理​

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

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

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

また、完全修飾名を使用してデータベースを作成したり、場所を指定したりすることもできます（現在、HMS型のカタログのみが場所の指定をサポートしています）。例えば：

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 Databaseの場合、データベース自体を削除する前に、データベース配下のすべてのテーブルを先に削除する必要があります。そうしないとエラーが発生します。

テーブルの作成と削除​

  • テーブルの作成

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

    例：

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

バージョン4.1.0から、DorisはIcebergテーブルの作成時にソートカラムの指定をサポートしています。データを書き込む際、指定されたソートカラムに従ってデータがソートされ、より良いクエリパフォーマンスを実現します。

CREATE TABLE ordered_table (
  `id` int NULL,
  `name` text NULL,
  `score` double NULL,
  `create_time` datetimev2(6) NULL
)
ORDER BY  (`id` ASC NULLS FIRST, `score` DESC NULLS LAST)
PROPERTIES (
  "write-format" = "parquet",
  "write.parquet.compression-codec" = "zstd"
);

  • ソート列が指定されていない場合、書き込み時にソートは実行されません。

    • デフォルトのソート順序は ASC NULLS FIRST です。

    作成後、SHOW CREATE TABLE コマンドを使用して Iceberg テーブル作成文を表示できます。パーティション機能の詳細については、Partitioning セクションを参照してください。

  • テーブルの削除

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

    例：

    DROP TABLE [IF EXISTS] iceberg_tbl;

  • Column Type Mapping

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

  • パーティショニング

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

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

    • パーティション変換関数をサポートし、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によって作成されたIcebergテーブルの場合、Datetimeはtimestamp_ntzタイプに対応することに注意してください。

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

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

    • ORC

  • 圧縮形式

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

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

  • ストレージメディア

    • HDFS

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

スキーマ変更​

3.1.0以降、DorisはIcebergテーブルのスキーマ変更をサポートし、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]]]];

例:

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

  • 列の追加

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

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

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

例:

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, ...);

Partition Evolution​

バージョン4.0.2以降、DorisはIcebergテーブルに対して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;

Branch & Tag の管理​

Since 3.1.0

  • Create Branch

    構文:

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

例:

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

例:

ALTER TABLE tbl DROP TAG t1;

Iceberg Table Actions​

この機能はバージョン4.0.2から対応しています。各操作の具体的なバージョン要件を確認してください。

これは実験的機能です。

DorisはALTER TABLE EXECUTE構文を通じて特定のIceberg table actionsの実行をサポートしています。この構文は、テーブル最適化やスナップショット管理などの様々な操作を実行するための統一されたインターフェースを提供します。

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

cherrypick_snapshot​

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

サポートバージョン: 4.0.2+

構文:

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

パラメーター:

ParameterTypeRequiredDescription
snapshot_idLongYesマージ対象のスナップショットID

戻り値:

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

Column NameTypeDescription
source_snapshot_idBIGINTマージされたスナップショットID
current_snapshot_idBIGINTマージ操作後に新しく作成され、currentに設定されたスナップショットID

例:

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

注意:

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

expire_snapshots​

expire_snapshots操作は、Icebergテーブルから古いスナップショットを削除してストレージ容量を解放し、メタデータのパフォーマンスを向上させます。この操作はApache Iceberg Sparkプロシージャ仕様に準拠しています。

サポートバージョン: 4.1.0+

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE expire_snapshots ("key1" = "value1", "key2" = "value2", ...)

パラメータ:

ParameterTypeRequiredDescription
older_thanStringNoスナップショット有効期限のタイムスタンプ閾値。この日時より古いスナップショットが削除されます。ISO datetime形式（例：2024-01-01T00:00:00）またはミリ秒タイムスタンプをサポート
retain_lastIntegerNo保持する祖先スナップショットの数。単独で指定した場合、older_thanは自動的に現在時刻に設定されます
snapshot_idsStringNo有効期限切れにする特定のスナップショットIDのカンマ区切りリスト
max_concurrent_deletesIntegerNo削除操作のスレッドプールサイズ
clean_expired_metadataBooleanNotrueに設定すると、未使用のパーティション仕様とスキーマをクリーンアップします

戻り値:

expire_snapshots操作の実行は、以下の6つのカラムを持つ結果セットを返します：

Column NameTypeDescription
deleted_data_files_countBIGINT削除されたデータファイルの数
deleted_position_delete_files_countBIGINT削除されたposition deleteファイルの数
deleted_equality_delete_files_countBIGINT削除されたequality deleteファイルの数
deleted_manifest_files_countBIGINT削除されたmanifestファイルの数
deleted_manifest_lists_countBIGINT削除されたmanifest listファイルの数
deleted_statistics_files_countBIGINT削除されたstatisticsファイルの数

例:

-- Expire snapshots, keeping only the last 2
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE expire_snapshots ("retain_last" = "2");

-- Expire snapshots older than a specific timestamp
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE expire_snapshots ("older_than" = "2024-01-01T00:00:00");

-- Expire specific snapshots by ID
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE expire_snapshots ("snapshot_ids" = "123456789,987654321");

-- Combine parameters: expire snapshots older than 2024-06-01 but keep at least the last 5
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE expire_snapshots ("older_than" = "2024-06-01T00:00:00", "retain_last" = "5");

注意事項:

  1. この操作はWHERE条件をサポートしていません。
  2. older_thanとretain_lastの両方が指定された場合、両方の条件が適用されます：older_thanより古く、かつ最新のretain_last個のスナップショットに含まれないスナップショットのみが削除されます。
  3. snapshot_idsは単独で使用して特定のスナップショットを削除できます。
  4. この操作はスナップショットとそれに関連するデータファイルを永久に削除します。注意して使用してください。
  5. 実行前に$snapshotsシステムテーブルを照会して、テーブルのスナップショット情報を理解することを推奨します。

fast_forward​

fast_forward操作は、あるブランチの現在のスナップショットを別のブランチの最新スナップショットまで素早く進めます。

サポートバージョン: 4.0.2+

構文:

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

パラメータ:

ParameterTypeRequiredDescription
branchStringYes進めるブランチの名前
toStringYesターゲットブランチ名；branchはこのブランチの最新スナップショットまで進められます

戻り値:

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

Column NameTypeDescription
branch_updatedSTRING進められたブランチの名前
previous_refBIGINT進める前にブランチが指していたスナップショットID（NULLの場合があります）
updated_refBIGINT進めた後にブランチが指すスナップショットID

例:

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

注意:

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

publish_changes​

publish_changes操作は、Write-Audit-Publish (WAP)パターンの「Publish」ステップです。このプロセスは特定のwap.id属性を持つスナップショットを見つけ、現在のテーブル状態に追加します。これにより、ユーザーは検証後に「ステージング」データを原子的に表示できるようになります。

サポートバージョン: 4.1.0+

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE publish_changes ("wap_id" = "<wap-id>")

パラメータ:

ParameterTypeRequiredDescription
wap_idStringYes公開するスナップショットのwap.id

戻り値:

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

Column NameTypeDescription
previous_snapshot_idBIGINT公開前のスナップショットID
current_snapshot_idBIGINT公開後の新しいスナップショットID

例:

ALTER TABLE iceberg_db.iceberg_table
EXECUTE publish_changes ("wap_id" = "branch-123")

注意:

  1. この操作はWHERE条件をサポートしません
  2. 指定されたwap.idが存在しない場合、操作は失敗します

rewrite_data_files​

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

サポートバージョン: 4.0.2+

構文:

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

パラメータ:

ParameterTypeDefault ValueDescription
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 NameTypeDescription
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"
);

-- Rewrite data in specific partitions using WHERE condition
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を使用して、どのファイルが書き直されるかを計算できます

rewrite_manifests​

rewrite_manifests 操作により、ユーザーはマニフェストファイルを書き直すことでIcebergテーブルメタデータを最適化し、クエリパフォーマンスの向上とメタデータオーバーヘッドの削減を実現できます。

これは、大規模なIcebergテーブルにおけるマニフェストファイル最適化の問題に対処します。多数の小さなマニフェストファイルは、クエリプランニングパフォーマンスに影響を与える可能性があります。

サポートバージョン: 4.1.0+

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE rewrite_manifests();

パラメータ:

パラメータなし

戻り値:

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

列名型説明
rewritten_manifests_countBIGINT書き換えられたファイル数
total_data_manifests_countBIGINT書き換えられたデータマニフェストファイル数

例:

ALTER TABLE iceberg_db.iceberg_table
EXECUTE rewrite_manifests();

rollback_to_snapshot​

rollback_to_snapshotオペレーションは、Icebergテーブルを指定されたスナップショットにロールバックします。

サポート対象バージョン: 4.0.2+

構文:

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

パラメータ:

ParameterTypeRequiredDescription
snapshot_idLongYesロールバック先のスナップショットID

戻り値:

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

Column NameTypeDescription
previous_snapshot_idBIGINTロールバック前の現在のスナップショットのID
current_snapshot_idBIGINTロールバック後に現在として設定されるスナップショットID

例:

-- Roll back 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操作は、Icebergテーブルを指定された時点のスナップショットにロールバックします。

サポートバージョン: 4.0.2+

構文:

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

パラメータ:

ParameterTypeRequiredDescription
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 NameTypeDescription
previous_snapshot_idBIGINTロールバック前の現在のスナップショットのID
current_snapshot_idBIGINT指定された時点でのスナップショットID、現在として設定される

例:

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

-- Roll back to specified point in time (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. 指定された時点に対応するスナップショットが存在しない場合、操作は失敗します

set_current_snapshot​

set_current_snapshot操作は、Icebergテーブルの現在のスナップショットを指定されたスナップショットIDまたはリファレンス（ブランチまたはタグ）に設定します。

サポートバージョン: 4.0.2+

構文:

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

パラメータ:

ParameterTypeRequiredDescription
snapshot_idLongEither one現在として設定するスナップショットID
refStringEither one現在として設定する参照名（ブランチまたはタグ）

戻り値:

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

Column NameTypeDescription
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. 指定されたsnapshot IDまたはreferenceが存在しない場合、操作は失敗します
  4. 現在のsnapshotが既にターゲットsnapshotである場合、操作は新しいsnapshotを作成せずに直接戻ります

publish_changes​

publish_changes操作は、WAP（Write-Audit-Publish）モードにおいて、指定されたwap.idを持つsnapshotを現在のテーブル状態として公開するために使用されます。
与えられたwap_idに一致するwap.idを持つsnapshotを特定し、それを現在のテーブルにcherry-pickして、ステージされたデータを全ての読み取り操作から見えるようにします。

構文:

ALTER TABLE [catalog.][database.]table_name
EXECUTE publish_changes("wap_id" = "<wap_id>")

パラメータ:

パラメータ:

パラメータ名型必須説明
wap_idSTRINGYes公開するWAPスナップショットID

戻り値:

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

列名型説明
previous_snapshot_idSTRING公開操作前の現在のスナップショットのID（存在しない場合はNULL）
current_snapshot_idSTRING公開後に作成され、現在として設定された新しいスナップショットのID

例:

-- Publish the snapshot whose WAP ID is test_wap_001
ALTER TABLE iceberg_db.iceberg_table 
EXECUTE publish_changes("wap_id" = "test_wap_001");

注意:

  1. この操作はWHERE句、およびPARTITION/PARTITIONS句をサポートしません
  2. write.wap.enabled = trueが設定され、wap.idを介してWAPスナップショットが生成されたIcebergテーブルに対してのみ意味があります
  3. 指定されたwap_idのスナップショットが見つからない場合、操作は失敗してエラーをスローします
  4. 公開後、新しいスナップショットが現在のスナップショットになります
  5. 公開前にスナップショットが存在しない場合、previous_snapshot_idはNULLになる可能性があります

Icebergテーブルの最適化​

データファイルの分散状況の確認​

以下のSQLを使用してIcebergテーブルのデータ分散状況および削除ファイル数を分析し、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クエリを使用してシステムテーブル情報に基づいてどのファイルが書き換えされるかを分析できます。これにより、実際の書き換え操作を実行する前に書き換え動作をデバッグし理解するのに役立ちます。

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

  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アルゴリズムは、システムテーブルのSQLクエリでは正確にシミュレートできない複雑な最適化アルゴリズムです。このアルゴリズムは、ファイルサイズと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 を実際のテーブル名に置き換えてください

  • パラメータ値（@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"] |
    +---------------------+----------------------------+-----------+-------------------------------------+
Report issue
このページ
ASF
Resources
Community
Join the community
Copyright © 2026 The Apache Software Foundation,Licensed under the Apache License, Version 2.0. Apache, Doris, Apache Doris, the Apache feather logo and the Apache Doris logo are trademarks of The Apache Software Foundation.