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

Iceberg メタデータテーブル

このトピックでは、StarRocks で Iceberg テーブルのメタデータ情報を確認する方法について説明します。

概要​

バージョン V3.4.1 以降、StarRocks は Iceberg メタデータテーブルをサポートしています。これらのメタデータテーブルには、Iceberg テーブルに関するさまざまな情報が含まれており、テーブルの変更履歴、スナップショット、マニフェストなどがあります。元のテーブル名にメタデータテーブル名を追加することで、各メタデータテーブルをクエリできます。

現在、StarRocks は以下の Iceberg メタデータテーブルをサポートしています。

メタデータテーブル説明
historyテーブルに対して行われたメタデータ変更のログを表示します。
metadata_log_entriesテーブルのメタデータログエントリを表示します。
snapshotsテーブルスナップショットの詳細を表示します。
manifestsテーブルのログ内のスナップショットに関連付けられたマニフェストの概要を表示します。
partitionsテーブル内のパーティションの詳細を表示します。
filesテーブルの現在のスナップショット内のデータファイルと削除ファイルの詳細を表示します。
entries現在のスナップショットのマニフェストエントリを表示します。削除されたファイルのエントリも含みます。
all_data_filesテーブルのすべてのスナップショットのデータファイルを表示します。
all_delete_filesテーブルのすべてのスナップショットの削除ファイルを表示します。
all_manifestsテーブルのすべてのスナップショットのマニフェストを表示します。
all_entriesテーブルのすべてのスナップショットのマニフェストエントリを表示します。
refsIceberg の参照に関する詳細を表示し、ブランチやタグを含みます。
propertiesテーブルプロパティをキーと値のペアで表示します。

Iceberg v3 Row Lineage メタデータ列​

バージョン v4.1 以降、Iceberg v3 テーブル(format-version = 3)の場合、StarRocks は以下の Row Lineage メタデータ列のクエリをサポートしています:

メタデータ列説明
_row_idテーブル内で一意の行識別子(BIGINT)。形式:firstRowId + row_position。
_last_updated_sequence_number行が最後に更新されたコミットシーケンス番号(BIGINT)。

使用法:

SELECT _row_id, _last_updated_sequence_number, * FROM [<catalog>.][<database>.]table;
注記
  • _row_id 列には、データファイルに firstRowId メタデータが必要です。データファイルに firstRowId がない場合、クエリはエラーで失敗します。
  • 新規挿入データの場合、_row_id は firstRowId + row_position で計算され、_last_updated_sequence_number はファイルレベルの dataSequenceNumber になります。
  • コンパクション(Iceberg OPTIMIZE / rewrite-data-files など)後、コンパクターが Iceberg v3 仕様に従って _row_id と _last_updated_sequence_number をデータファイルの物理列として書き込んだ場合、StarRocks は各行の物理列値を読み取り、コンパクション後も行リネージ情報を保持します。
  • これらのメタデータ列は Iceberg v3 テーブル(format-version = 3)でのみ使用可能です。

history テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$history;

出力:

フィールド説明
made_current_atスナップショットが現在のスナップショットになった時刻。
snapshot_idスナップショットの ID。
parent_id親スナップショットの ID。
is_current_ancestorこのスナップショットが現在のスナップショットの祖先であるかどうか。

metadata_log_entries テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$metadata_log_entries;

出力:

フィールド説明
timestampメタデータが記録された時刻。
fileメタデータファイルの場所。
latest_snapshot_idメタデータが更新されたときの最新スナップショットの ID。
latest_schema_idメタデータが更新されたときの最新スキーマの ID。
latest_sequence_numberメタデータファイルのデータシーケンス番号。

snapshots テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$snapshots;

出力:

フィールド説明
committed_atスナップショットがコミットされた時刻。
snapshot_idスナップショットの ID。
parent_id親スナップショットの ID。
operationIceberg テーブルに対して行われた操作の種類。 有効な値:
  • append: 新しいデータが追加されます。
  • replace: テーブル内のデータを変更せずにファイルが削除および置換されます。
  • overwrite: 古いデータが新しいデータで上書きされます。
  • delete: テーブルからデータが削除されます。
manifest_listスナップショットの変更に関する詳細情報を含む Avro マニフェストファイルのリスト。
summary前のスナップショットから現在のスナップショットまでに行われた変更の概要。

manifests テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$manifests;

出力:

フィールド説明
pathマニフェストファイルの場所。
lengthマニフェストファイルの長さ。
partition_spec_idマニフェストファイルの書き込みに使用されるパーティション仕様の ID。
added_snapshot_idこのマニフェストエントリが追加されたときのスナップショットの ID。
added_data_files_countマニフェストファイル内で ADDED ステータスのデータファイルの数。
added_rows_countマニフェストファイル内で ADDED ステータスのすべてのデータファイルの総行数。
existing_data_files_countマニフェストファイル内で EXISTING ステータスのデータファイルの数。
existing_rows_countマニフェストファイル内で EXISTING ステータスのすべてのデータファイルの総行数。
deleted_data_files_countマニフェストファイル内で DELETED ステータスのデータファイルの数。
deleted_rows_countマニフェストファイル内で DELETED ステータスのすべてのデータファイルの総行数。
partitionsパーティション範囲のメタデータ。
contentマニフェストファイルのコンテンツタイプ。有効な値:DATA(0)、DELETES(1)。削除マニフェストの場合、*_data_files_count と *_rows_count フィールドは削除ファイルと削除された行を数えます。

partitions テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$partitions;

出力:

フィールド説明
partition_valueパーティション列名とパーティション列値のマッピング。
spec_idファイルのパーティション Spec ID。
record_countパーティション内のレコード数。
file_countパーティションにマッピングされたファイルの数。
total_data_file_size_in_bytesパーティション内のすべてのデータファイルのサイズ。
position_delete_record_countパーティション内の Position Delete ファイルの総行数。
position_delete_file_countパーティション内の Position Delete ファイルの数。
equality_delete_record_countパーティション内の Equality Delete ファイルの総行数。
equality_delete_file_countパーティション内の Position Equality ファイルの数。
last_updated_atパーティションが最後に更新された時刻。

files テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$files;

出力:

フィールド説明
contentファイルに格納されているコンテンツの種類。 有効な値: DATA(0), POSITION_DELETES(1), および EQUALITY_DELETES(2)。
file_pathデータファイルの場所。
file_formatデータファイルの形式。
spec_id行を含むファイルを追跡するために使用される Spec ID。
partitionファイルのパーティション値。テーブルのすべてのパーティション Spec のパーティションフィールドを持つ Struct です。ファイルのパーティション Spec にないフィールドは NULL です。テーブルが一度もパーティション化されていない場合、このフィールドはありません。partition は予約語のため、クエリではバッククォートで囲んでください。
record_countデータファイルに含まれるエントリの数。
file_size_in_bytesデータファイルのサイズ。
column_sizesIceberg 列 ID とファイル内の対応するサイズとのマッピング。
value_countsIceberg 列 ID とファイル内の対応するエントリ数とのマッピング。
null_value_countsIceberg 列 ID とファイル内の対応する NULL 値の数とのマッピング。
nan_value_countsIceberg 列 ID とファイル内の対応する非数値値の数とのマッピング。
lower_boundsIceberg 列 ID とファイル内の対応する下限とのマッピング。
upper_boundsIceberg 列 ID とファイル内の対応する上限とのマッピング。
split_offsets推奨される分割位置のリスト。
sort_idこのファイルのソート順序を表す ID。
equality_idsEquality Delete ファイルでの等価比較に使用されるフィールド ID のセット。
key_metadataこのファイルを暗号化するために使用される暗号化キーに関するメタデータ(該当する場合)。
first_row_idフォーマットバージョン 3 のテーブルにおける、データファイルの最初の行の行 ID。削除ファイルの場合は NULL。
referenced_data_file削除ベクトルまたはファイル単位の位置削除ファイルが適用されるデータファイルの場所。データファイルの場合は NULL。
content_offsetPuffin ファイル内の削除ベクトルのオフセット。その他のファイルの場合は NULL。
content_size_in_bytesPuffin ファイル内の削除ベクトルのサイズ。その他のファイルの場合は NULL。

entries テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$entries;

出力:

フィールド説明
statusエントリのステータス。有効な値: EXISTING(0), ADDED(1), および DELETED(2)。
snapshot_idファイルが追加または削除されたスナップショットの ID。
sequence_numberファイルのデータシーケンス番号。
file_sequence_numberファイルが追加されたスナップショットのシーケンス番号。
data_fileファイル。files テーブルのフィールドを持つ Struct です。ソート順序 ID のフィールド名は sort_order_id です。

all_data_files テーブルと all_delete_files テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$all_data_files;
SELECT * FROM [<catalog>.][<database>.]table$all_delete_files;

これらのテーブルのフィールドは files テーブルと同じです。テーブルのすべてのスナップショットのマニフェストにあるデータファイルまたは削除ファイルを表示するため、同じファイルが複数回表示されることがあります。

all_manifests テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$all_manifests;

このテーブルには manifests テーブルのフィールドと次のフィールドがあります。マニフェストは、それを含むスナップショットごとに 1 回表示されます。

フィールド説明
reference_snapshot_idマニフェストを含むスナップショットの ID。

all_entries テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$all_entries;

このテーブルのフィールドは entries テーブルと同じです。テーブルのすべてのスナップショットのマニフェストにあるエントリを表示します。

refs テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$refs;

出力:

フィールド説明
name参照の名前。
type参照の種類。 有効な値: BRANCH または TAG。
snapshot_id参照のスナップショット ID。
max_reference_age_in_ms参照が期限切れになるまでの最大年齢。
min_snapshots_to_keepブランチのみ、ブランチ内で保持する最小スナップショット数。
max_snapshot_age_in_msブランチのみ、ブランチ内で許可される最大スナップショット年齢。ブランチ内の古いスナップショットは期限切れになります。

properties テーブル​

使用法:

SELECT * FROM [<catalog>.][<database>.]table$properties;

出力:

フィールド説明
keyテーブルプロパティの名前。
valueテーブルプロパティの値。

出力例:

keyvalue
locations3://bucket/warehouse/db/my_table
write.format.defaultparquet
write.parquet.compression-codeczstd