データ接続と統合Iceberg テーブルカタログの動作プロパティ

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

Iceberg テーブルのプロパティ

Iceberg テーブルのメタデータには、テーブルプロパティのキーバリューマップが含まれます。テーブルプロパティの初期マップはテーブルの作成時に設定され、その後は ALTER TABLE ... SET TBLPROPERTIES を使用して変更できます。Iceberg 仕様では主要なプロパティが予約されており、Foundry も、テーブルの RID などの Foundry 固有のメタデータを追跡するためのキーを用意しています。

Foundry 固有のプロパティ

Foundry 固有のプロパティには、次のものがあります。

プロパティ説明ユーザー編集
created-atテーブル作成のタイムスタンプ(カタログ間の規約)✅ 許可
foundry.branch.*ブランチをスコープとするスキーマ、パーティション仕様、並べ替え順序を追跡します❌ 不許可
foundry.ridテーブルの RID❌ 不許可
foundry.table-version内部カタログマーカー❌ 不許可
foundry.table-statusIceberg に移行中のテーブルを示します❌ 不許可

移行ステータス

Foundry がデータセットを Iceberg に移行するとき、foundry.table_status を migrating に設定します。この値を持つテーブルは Foundry 内部でのみ使用するものであり、外部クライアントは読み取らないでください。Foundry は、この制限を説明するために、テーブルの comment プロパティも設定します。

外部統合を構築する際は、Foundry の Iceberg REST カタログからテーブルを読み込むときに返されるテーブルプロパティを確認し、foundry.table_status が migrating のテーブルからデータを読み取らないでください。

現在、Foundry が foundry.table_status に設定する値は migrating のみです。それ以外のすべてのテーブルでは、このプロパティは設定されません。

Iceberg 仕様のプロパティ

Iceberg 仕様でも、中核となる Iceberg テーブルのプロパティ ↗が予約されています。

Foundry の Iceberg REST カタログでは、一部の中核的な Iceberg テーブルプロパティに次の制約があります。

プロパティFoundry のデフォルト値ユーザー編集
encryption.*Iceberg テーブルの暗号化が有効な場合、その設定の一環として設定されます❌ 不許可
format-versionフォーマットバージョンのデフォルト値を参照してください✅ 許可
history.expire.max-snapshot-age-ms2592000000(30日)✅ 許可
write.metadata.delete-after-commit.enabledfalse❌ 不許可
write.metadata.previous-versions-max1✅ 許可
write.object-storage.enabledtrue❌ 不許可
write.object-storage.partitioned-pathsfalse❌ 不許可
write.data.path❌ 不許可
write.folder-storage.path❌ 不許可
write.location-provider.impl❌ 不許可
write.metadata.path❌ 不許可
write.object-storage.path❌ 不許可

Foundry がデフォルト値を用意している場合、その値はオープンソースの Iceberg 仕様のデフォルト値よりも優先されます。明示的に設定されていないプロパティには、Iceberg 仕様のデフォルト値が使用されます。

Foundry が適用するデフォルト設定は変更される可能性があります。特定のプロパティ値を確実に使用するには、以下の説明に従って、テーブルにその値を明示的に設定してください。

トランスフォームで特定のテーブルプロパティを設定する

特定のテーブルプロパティは手動で設定できます。たとえば、Iceberg メンテナンスページで ALTER TABLE 文を実行する方法や、トランスフォームのコードでプロパティを指定する方法があります。

以下は、トランスフォームでテーブルプロパティを設定するコードスニペットの例です。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 import polars as pl from transforms.api import transform from transforms.tables import IcebergOutput, TableOutput @transform.using(output=TableOutput("/path/table")) def compute(output: IcebergOutput) -> None: df_custom = pl.DataFrame({"phrase": ["Hello", "World"]}) output.write_table(df_custom) tbl = output.iceberg().table() with tbl.transaction() as txn: txn.set_properties({ "write.delete.mode": "merge-on-read", "write.update.mode": "merge-on-read", "write.merge.mode": "merge-on-read", "history.expire.max-snapshot-age-ms": "0", })
Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 from transforms.api import TransformContext from transforms.api import transform from transforms.tables import ( TableOutput, TableTransformOutput, ) @transform( output=TableOutput("/path/table") ) def compute(ctx: TransformContext, output: TableTransformOutput): spark = ctx.spark_session df_custom = spark.createDataFrame([["Hello"], ["World"]], schema=["phrase"]) output.write_dataframe(df_custom) identifier = output.identifier spark.sql(f""" ALTER TABLE {identifier} SET TBLPROPERTIES ( "write.delete.mode": "merge-on-read", "write.update.mode": "merge-on-read", "write.merge.mode": "merge-on-read", 'history.expire.max-snapshot-age-ms' = '0' ) """)

テーブルプロパティは、必ず出力テーブルを書き込んだ後に設定してください。これにより、プロパティを設定する前にテーブルが存在することが保証され、Spark の write_dataframe による置換操作で、指定したプロパティ値がデフォルト値で上書きされるのを防ぎます。