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

Iceberg Procedures

StarRocks Iceberg catalog は、スナップショット管理、ブランチ管理、データメンテナンス、メタデータ管理、およびテーブル管理を含む、Iceberg テーブルを管理するためのさまざまなプロシージャをサポートしています。

プロシージャを実行するには、適切な権限が必要です。権限の詳細については、権限 を参照してください。

スナップショット管理​

スナップショットへのロールバック​

テーブルを特定のスナップショットにロールバックします。この操作は、テーブルの現在のスナップショットを指定されたスナップショット ID に設定します。

rollback_to_snapshot 構文​

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

パラメータ​

snapshot_id: テーブルをロールバックするスナップショットの ID。

例​

テーブルをスナップショット ID 98765 でロールバックします。

ALTER TABLE iceberg.sales.order
EXECUTE rollback_to_snapshot(98765);

タイムスタンプへのロールバック​

指定したタイムスタンプより前にコミットされた最新のスナップショットにテーブルをロールバックします。タイムスタンプは現在のセッションのタイムゾーンで解釈されます。

rollback_to_timestamp 構文​

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

パラメータ​

timestamp: この時点より前にコミットされた最新のスナップショットにテーブルをロールバックします。形式: 'YYYY-MM-DD HH:MM:SS'。この時点より前にコミットされたスナップショットがない場合はエラーを返します。

例​

テーブルを 2025-01-01 00:00:00 より前の状態にロールバックします。

ALTER TABLE iceberg.sales.order
EXECUTE rollback_to_timestamp('2025-01-01 00:00:00');

現在のスナップショットの設定​

テーブルの現在のスナップショットを指定されたスナップショット ID に設定します。rollback_to_snapshot と異なり、スナップショットは現在のスナップショットの祖先である必要がないため、ロールバックで外れたスナップショットにテーブルを再び進めることができます。

set_current_snapshot 構文​

ALTER TABLE [catalog.][database.]table_name
EXECUTE set_current_snapshot(<snapshot_id>)

パラメータ​

snapshot_id: テーブルの現在のスナップショットとして設定するスナップショットの ID。

例​

ALTER TABLE iceberg.sales.order
EXECUTE set_current_snapshot(98765);

スナップショットの Cherry Pick​

特定のsnapshotをcherry pickし、テーブルの現在の状態に適用します。この操作は、既存のsnapshotに基づいて新しいsnapshotを作成しますが、元のsnapshotは変更されません。

cherrypick_snapshot の構文​

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

Parameters​

snapshot_id: cherry pick したいスナップショットの ID。

例​

ALTER TABLE iceberg.sales.order
EXECUTE cherrypick_snapshot(54321);

ブランチ管理​

別のブランチにブランチを高速で進める​

あるブランチを別のブランチの最新スナップショットに高速で進めます。この操作は、ソースブランチのスナップショットを更新して、ターゲットブランチのスナップショットと一致させます。

fast_forward の構文​

ALTER TABLE [catalog.][database.]table_name
EXECUTE fast_forward('<from_branch>', '<to_branch>')

パラメータ​

  • from_branch: 高速で転送したいブランチ。ブランチ名を引用符で囲みます。
  • to_branch: from_branch を高速で転送したいブランチ。ブランチ名を引用符で囲みます。

例​

main ブランチを test-branch ブランチに高速で進める場合:

ALTER TABLE iceberg.sales.order
EXECUTE fast_forward('main', 'test-branch');

データメンテナンス​

データファイルの書き換え​

データファイルを書き換えて、ファイルレイアウトを最適化します。この手順では、クエリパフォーマンスを向上させ、メタデータのオーバーヘッドを削減するために、小さなファイルをマージします。

rewrite_data_files の構文​

ALTER TABLE [catalog.][database.]table_name
EXECUTE rewrite_data_files
("key"=value [,"key"=value, ...])
[WHERE <predicate>]

パラメータ​

rewrite_data_files プロパティ​

"key"=value のペアで、手動 compaction の動作を宣言します。キーは二重引用符で囲む必要があります。

min_file_size_bytes​
  • 説明: 小さいデータファイルのサイズ上限。サイズがこの値を下回るデータファイルは、compaction 時にマージされます。
  • 単位: バイト
  • タイプ: Int
  • デフォルト: 268,435,456 (256 MB)
batch_size​
  • 説明: 各バッチで処理できるデータの最大サイズ。
  • 単位: バイト
  • タイプ: Int
  • デフォルト: 10,737,418,240 (10 GB)
rewrite_all​
  • 説明: 特定の要件を持つデータファイルをフィルタリングするパラメータを無視して、compaction 時にすべてのデータファイルを書き換えるかどうか。
  • 単位: -
  • タイプ: Boolean
  • デフォルト: false
batch_parallelism​
  • 説明: compaction 時に処理する並列バッチの数。
  • 単位: -
  • タイプ: Int
  • デフォルト: 1
delete_ratio_threshold​
  • 説明: min_file_size_bytes より大きいデータファイルでも、その削除ベクトルまたはファイル単位の位置削除ファイルで削除された行数がファイルの行数に占める割合がこの値に達した場合、書き換えの対象になります。有効範囲: [0, 1]。等価削除ファイルとパーティション単位の位置削除ファイルはこの割合に含まれません。
  • 単位: -
  • タイプ: Double
  • デフォルト: 0.3
delete_file_threshold​
  • 説明: min_file_size_bytes より大きいデータファイルでも、適用される削除ファイルの数がこの値以上の場合、書き換えの対象になります。正の整数である必要があります。
  • 単位: -
  • タイプ: Int
  • デフォルト: 無制限
WHERE 句​
  • 説明: Compaction に含めるパーティションを指定するために使用されるフィルタ述語。

例​

次の例では、Iceberg テーブル t1 内の特定のパーティションに対して手動で Compaction を実行します。パーティションは WHERE part_col = 'p1' という句で表されます。これらのパーティションでは、134,217,728 バイト (128 MB) 未満のデータファイルは Compaction 中にマージされます。

ALTER TABLE t1 EXECUTE rewrite_data_files("min_file_size_bytes"= 134217728) WHERE part_col = 'p1';

メタデータ管理​

スナップショットの有効期限​

特定の日時より古いスナップショットの有効期限が切れます。この操作により、期限切れのスナップショットのデータファイルが削除され、ストレージの使用状況の管理に役立ちます。

expire_snapshots の構文​

ALTER TABLE [catalog.][database.]table_name
EXECUTE expire_snapshots(
[ [older_than =] '<datetime>' ] [, [retain_last =] <int> ]
)

パラメータ​

older_than​
  • 説明: スナップショットを削除するタイムスタンプの基準となる日時。指定しない場合、デフォルトでは、(現在の時刻から)5 日以上前のファイルが削除されます。形式: 'YYYY-MM-DD HH:MM:SS'。
  • タイプ: DATETIME
  • 必須: いいえ
retain_last​
  • 説明: 保持する最新のスナップショットの最大数。このしきい値に達すると、古いスナップショットは削除されます。指定しない場合、デフォルトでは1つのスナップショットのみが保持されます。
  • タイプ: Integer
  • 必須: いいえ

例​

'2023-12-17 00:14:38' より前のスナップショットを期限切れにし、2つのスナップショットを保持します。

-- With the parameter key specified:
ALTER TABLE iceberg.sales.order
EXECUTE expire_snapshots(older_than = '2023-12-17 00:14:38', retain_last = 2);

-- With the parameter key unspecified:
ALTER TABLE iceberg.sales.order
EXECUTE expire_snapshots('2023-12-17 00:14:38', 2);

不要なファイルを削除する​

有効なスナップショットから参照されておらず、指定されたタイムスタンプよりも古い、テーブル内の不要なファイルを削除します。この操作は、未使用のファイルをクリーンアップし、ストレージ容量を再利用するのに役立ちます。

remove_orphan_files の構文​

ALTER TABLE [catalog.][database.]table_name
EXECUTE remove_orphan_files(
[ [older_than =] '<datetime>' ] [, [location =] '<string>' ]
)

パラメータ​

older_than​
  • 説明: 孤立ファイルを削除するタイムスタンプの期限。指定しない場合、デフォルトでは、(現在の時刻から)7 日以上前のファイルが削除されます。形式: 'YYYY-MM-DD HH:MM:SS'。この値は現在の時刻から少なくとも iceberg_remove_orphan_files_min_retention_seconds(デフォルトは 24 時間)だけ過去である必要があります。これより新しい値は拒否されます。それほど新しいファイルを削除すると、並行する書き込みがまだコミットしていないデータを消してしまう可能性があるためです。
  • タイプ: DATETIME
  • 必須: いいえ
location​
  • 説明: 不要なファイルを削除するディレクトリ。テーブルの場所のサブディレクトリである必要があります。指定しない場合、デフォルトでテーブルの場所が使用されます。
  • タイプ: STRING
  • 必須: いいえ

例​

テーブルの場所のサブディレクトリ sub_dir から、'2024-01-01 00:00:00' より古い孤立ファイルを削除します。

-- With the parameter key specified:
ALTER TABLE iceberg.sales.order
EXECUTE remove_orphan_files(older_than = '2024-01-01 00:00:00', location = 's3://iceberg-bucket/iceberg_db/iceberg_table/sub_dir');

-- With the parameter key unspecified:
ALTER TABLE iceberg.sales.order
EXECUTE remove_orphan_files('2024-01-01 00:00:00', 's3://bucket-test/iceberg_db/iceberg_table/sub_dir');

マニフェストの再書き込み​

データマニフェストファイルを再書き込みし、パーティションごとにマージします。これにより、過剰な小規模マニフェストによるパフォーマンスの低下を回避します。

注記

この操作は現在のスナップショットのデータマニフェストのみを再書き込みします。

rewrite_manifests 構文​

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

例​

現在のスナップショットのデータマニフェストを書き換える:

ALTER TABLE iceberg.sales.order
EXECUTE rewrite_manifests()

テーブル管理​

ファイルの追加​

ソーステーブルまたは特定の場所から Iceberg テーブルにデータファイルを追加します。このプロシージャは、Parquet および ORC ファイル形式をサポートしています。

add_files 構文​

ALTER TABLE [catalog.][database.]table_name
EXECUTE add_files(
[source_table = '<source_table>' | location = '<location>', file_format = '<format>']
[, recursive = <boolean>]
)

パラメータ​

source_table または location のいずれかを指定する必要があります。両方を指定することはできません。

source_table​
  • 説明: ファイルを追加する元のテーブル。形式: 'catalog.database.table'。
  • タイプ: String
  • 必須: いいえ
location​
  • 説明: ファイルの追加元となるディレクトリパスまたはファイルパス。
  • タイプ: String
  • 必須: いいえ
file_format​
  • 説明: データファイルの形式。サポートされている値: 'parquet'、'orc'。
  • タイプ: String
  • 必須: いいえ ( location を使用する場合に必須)
recursive​
  • 説明: ある場所からファイルを追加する際に、サブディレクトリを再帰的にスキャンするかどうか。
  • タイプ: Boolean
  • デフォルト: true
  • 必須: いいえ

例​

ソーステーブルからファイルを追加します。

ALTER TABLE iceberg.sales.order
EXECUTE add_files(source_table = 'hive_catalog.sales.source_order');

Parquet 形式で特定の場所からファイルを追加します。

ALTER TABLE iceberg.sales.order
EXECUTE add_files(location = 's3://bucket/data/order/', file_format = 'parquet', recursive = true);

単一のファイルからファイルを追加します。

ALTER TABLE iceberg.sales.order
EXECUTE add_files(location = 's3://bucket/data/order/data.parquet', file_format = 'parquet');

Equality Delete ファイルの追加​

既存のファイルを Equality Delete ファイルとして Iceberg テーブルに追加します。ファイル内の各行は、Equality 列の値が同じテーブルの行を削除します。ファイルは新しいスナップショットでコミットされるため、テーブルにすでにあるデータに適用されます。このプロシージャは、Parquet および ORC ファイル形式をサポートしており、フォーマットバージョン 2 以降の Iceberg テーブルが必要です。

ファイルは add_files と同じ方法で検出されます。パーティションテーブルの場合、各ファイルのパーティションはパス内の <column>=<value> ディレクトリから取得され、削除はそのパーティションのデータファイルにのみ適用されます。いずれかのパーティション列のディレクトリがパスにないファイルは拒否されます。Identity パーティション変換のみサポートされています。非パーティションテーブルの場合、削除はテーブル全体に適用されます。現在のパーティション仕様がパーティション化されていて、古いパーティション仕様で書き込まれたデータファイルがテーブルに残っている場合、削除はそれらのファイルに適用されないため、このプロシージャはエラーになります。セッション変数 enable_read_iceberg_equality_delete_with_partition_evolution が false(デフォルト: true)に設定されている場合、クエリエンジンは複数のパーティション仕様にまたがる Equality Delete を読み取らないため、現在以外のパーティション仕様で書き込まれた Equality Delete ファイルがテーブルに残っているときも、このプロシージャはエラーになります。ファイル内のいずれかの列が Iceberg フィールド ID を持つ場合、そのファイルのすべての Equality 列がテーブルと同じフィールド ID を持つ必要があり、そうでない場合はファイルが拒否されます。Equality 列の型をテーブル列の型として損失なく読み取れないファイル(例: テーブル列が INT でファイルの列が文字列)も拒否されます。フィールド ID を持たないファイルは列名でテーブルと照合されるため、ファイルの追加後にその Equality 列の名前を変更しないでください。変更すると削除が適用されなくなります。このプロシージャは WHERE 句をサポートしていません。

add_equality_delete_files 構文​

ALTER TABLE [catalog.][database.]table_name
EXECUTE add_equality_delete_files(
location = '<location>',
file_format = '<format>',
equality_columns = '<column>[, <column> ...]'
[, recursive = <boolean>]
)

パラメータ​

location​
  • 説明: Equality Delete ファイルの追加元となるディレクトリパスまたはファイルパス。
  • タイプ: String
  • 必須: はい
file_format​
  • 説明: Equality Delete ファイルの形式。サポートされている値: 'parquet'、'orc'。
  • タイプ: String
  • 必須: はい
equality_columns​
  • 説明: 削除時に照合するテーブル列のカンマ区切りリスト。各列は INT、BIGINT、STRING、DATE のいずれかの型のトップレベル列である必要があり、すべてのファイルがこれらの列をすべて含んでいる必要があります。
  • タイプ: String
  • 必須: はい
recursive​
  • 説明: location のサブディレクトリを再帰的にスキャンするかどうか。
  • タイプ: Boolean
  • デフォルト: true
  • 必須: いいえ

例​

s3://bucket/deletes/order/ 配下のファイル(例: s3://bucket/deletes/order/dt=2024-01-01/delete.parquet)のいずれかの行と id が一致する行を削除します。

ALTER TABLE iceberg.sales.order
EXECUTE add_equality_delete_files(location = 's3://bucket/deletes/order/', file_format = 'parquet', equality_columns = 'id');

テーブルの登録​

メタデータファイルを使用して Iceberg テーブルを登録します。このプロシージャを使用すると、データを移行せずに既存の Iceberg テーブルを catalog に追加できます。

register_table の構文​

CALL [catalog.]system.register_table(
database_name = '<database_name>',
table_name = '<table_name>',
metadata_file = '<metadata_file_path>'
)

パラメータ​

database_name​
  • 説明: テーブルを登録するデータベースの名前。
  • タイプ: String
  • 必須: はい
table_name​
  • 説明: 登録するテーブルの名前。
  • タイプ: String
  • 必須: はい
metadata_file​
  • 説明: Iceberg テーブルのメタデータファイルへのパス (例: metadata.json)。
  • タイプ: String
  • 必須: はい

例​

メタデータファイルを使用してテーブルを登録します。

CALL iceberg_catalog.system.register_table(
database_name = 'sales',
table_name = 'order',
metadata_file = 's3://bucket/metadata/sales/order/metadata/00001-xxxxx-xxxxx-xxxxx.metadata.json'
);

現在の catalog を使用することもできます。

CALL system.register_table(
database_name = 'sales',
table_name = 'order',
metadata_file = 's3://bucket/metadata/sales/order/metadata/00001-xxxxx-xxxxx-xxxxx.metadata.json'
);