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

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 カタログを参照してください。

Examples​

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

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

Iceberg JDBC カタログ​

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

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

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

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

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ダイアレクトと互換性がある必要があります。そうでなければパースエラーが発生します。（ダイアレクト変換機能は将来のバージョンで提供される予定です）。

システム Tables​

Since 3.1.0

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

IcebergTableのメタデータにアクセスするには、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;

Text:

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

Text:

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

結果:

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

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でscaling-writeを開始するためのデータ閾値。追加の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型のカタログのみが場所の指定をサポートしています）。例えば：

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の場合、データベース自体を削除する前に、データベース配下のすべての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のパーティションタイプは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

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

Schema Change​

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

    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をサポートしています。

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

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

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

  • partition keyの追加

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

ブランチ & タグの管理​

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;

  • Create Tag

    構文:

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

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 操作は、指定されたスナップショットからの変更を現在のTable状態にマージし、元のスナップショットを変更または削除することなく新しいスナップショットを作成します。

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

構文:

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

パラメータ:

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

Return Value:

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

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

Example:

-- 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. マージ操作は新しいスナップショットを作成し、元のスナップショットは削除しません

fast_forward​

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

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

構文:

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

パラメータ:

ParameterタイプRequiredデスクリプション
branchStringYes進めるブランチの名前
toStringYesターゲットブランチ名; branch はこのブランチの最新スナップショットまで進められます

戻り値:

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

Column Nameタイプデスクリプション
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. 指定されたbranchが存在しない場合、操作は失敗します
  3. branchのみ進めることができ、tagは対象外です

publish_changes​

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

サポートされているバージョン: 4.1.0+

構文:

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

パラメータ:

ParameterタイプRequiredデスクリプション
wap_idStringYes公開するスナップショットのwap.id

戻り値:

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

Column Nameタイプデスクリプション
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操作は、IcebergTable内のデータファイルを書き換えて小さなファイルの圧縮を実現し、クエリパフォーマンスとストレージ効率を最適化します。これは同期操作です。

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

構文:

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

パラメータ:

Parameterタイプデフォルト値デスクリプション
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"
);

-- 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操作により、ユーザーはマニフェストファイルを書き換えることでIcebergTableメタデータを最適化し、クエリパフォーマンスの向上とメタデータオーバーヘッドの削減を実現できます。

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

サポートバージョン: 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操作は、IcebergTableを指定されたスナップショットにロールバックします。

サポートされているバージョン: 4.0.2+

構文:

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

パラメータ:

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

Return Value:

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

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

Example:

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

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

構文:

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

パラメータ:

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

戻り値:

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

Column Nameタイプデスクリプション
previous_snapshot_idBIGINTロールバック前の現在のsnapshotのID
current_snapshot_idBIGINT指定された時点のsnapshot ID。現在のsnapshotとして設定される

例:

-- 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. 指定した時点に対応するsnapshotが存在しない場合、操作は失敗します

set_current_snapshot​

set_current_snapshot操作は、IcebergTableのcurrentスナップショットをspecifiedスナップショットIDまたはreference（branchまたはtag）に設定します。

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

構文:

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

パラメータ:

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

Return Value:

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

Column Nameタイプデスクリプション
previous_snapshot_idBIGINT操作前の現在のスナップショットのID
current_snapshot_idBIGINT操作後のスナップショットID（snapshot_idパラメータから、またはrefパラメータから解決されたもの）

Examples:

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

注意: このクエリは、ファイルレベルの条件（ファイルサイズ）を満たすファイルのみを識別できます。実際に書き換えられるファイルグループは、SQLクエリでは正確にシミュレートできないBinPackグループ化アルゴリズムに依存します。このクエリで識別されたファイルは、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"] |
    +---------------------+----------------------------+-----------+-------------------------------------+
このページでは