Apache Iceberg™ テーブルの管理¶

例: テーブルの更新¶

INSERT および UPDATE ステートメントを使用して、Snowflake管理のIcebergテーブルを変更できます。

次の例は、 store_sales という名前のIcebergテーブルに新しい値を挿入し、現在の値が-99の場合、 cola 列を1に更新します。

INSERT INTO store_sales VALUES (-99);

UPDATE store_sales
  SET cola = 1
  WHERE cola = -99;

クエリテーブル¶

Snowflakeは、更新、削除、マージ操作に 行レベル削除 を構成している場合、 外部管理Icebergテーブル へのクエリをサポートします。

行レベルの削除を構成するには、Apache Icebergドキュメントの プロパティを書く をご参照ください。

位置削除ファイルを使用してテーブルに書き込む¶

Snowflakeは、Amazon S3、Azure、またはGoogle Cloudに保存されている外部管理Icebergテーブルへの書き込みのための位置行レベルの削除をサポートしています。位置の削除をオフにするには、コピーオン書き込みモードでの DML 操作の実行を有効にするため、テーブル、スキーマ、データベースレベルで ENABLE_ICEBERG_MERGE_ON_READ パラメーターを FALSE に設定します。

削除ベクターを使用してテーブルに書き込む¶

行レベルのデータ変更を最適化するために、Snowflakeは、Amazon S3、Azure、またはGoogle Cloudに保存された外部管理およびSnowflake管理Icebergテーブルへの書き込み用の削除ベクターをサポートしています。削除ベクターを使用すると、Snowflakeは「読み取り時マージ」（MOR）操作を実行でき、これにより次のDMLステートメントの書き込みパフォーマンスが向上します。

• DELETE

• UPDATE

• MERGE

Snowflakeは、大きなデータファイルを書き換える代わりに、小さなベクターファイルを書き込むことで、このパフォーマンスを実現します。詳しくは、Apache Iceberg仕様の`削除ベクター<https://iceberg.apache.org/spec/#deletion-vectors>`_を参照してください。

コピーオンライトとマージオンリード¶

Icebergは、外部管理テーブルの行レベル操作を計算エンジンがどのように処理するかを構成するために2つのモードを提供します。Snowflakeはこの両方のモードをサポートしています。

次の表は、各モードを使用する場合の例です。

Icebergの行レベルの変更に関する情報は、Apache Icebergドキュメントの 行レベル削除 をご参照ください。

考慮事項と制約¶

Icebergテーブルで行レベルの削除を使用する場合は、以下の情報を考慮してください。

• Snowflakeは、v2 Icebergテーブルには`位置削除<https://iceberg.apache.org/spec/#position-delete-files>`_のみをサポートし、v3 Icebergテーブルには`削除ベクター<https://iceberg.apache.org/spec/#deletion-vectors>`_をサポートしています。

• Snowflakeは、外部管理Icebergテーブルでの位置削除のみをサポートしています。

• 行レベル削除を使用する際に最高の読み取りパフォーマンスを得るには、定期的にコンパクションとテーブル・メンテナンスを行い、古い削除ファイルを削除してください。詳細については、 外部カタログを使用するテーブルの維持 をご参照ください。

• ポジション削除が多すぎると、特に未処理のポジション削除は、テーブルの作成やリフレッシュ処理を妨げる可能性があります。この問題を回避するには、テーブルメンテナンスを実行して、余分なポジション削除を削除します。

  使用するテーブルメンテナンスメソッドは、外部Icebergエンジンによって異なります。たとえば、Sparkでは rewrite_data_files メソッドを delete-file-threshold または rewrite-all オプションと共に使用できます。詳細については、Apache Iceberg™ ドキュメントの rewrite_data_files をご参照ください。

自動クラスタリング¶

自動クラスタリングは、頻繁にクエリされる列に基づいて、ファイルまたはパーティション内のデータを再編成します。Icebergテーブルのファイルサイズは、ターゲットファイルサイズを設定しない限り、クラスタリング構成に基づいています。ターゲットファイルサイズを設定する場合は、ファイルサイズは設定した特定のサイズになります。詳細については、 ターゲットファイルサイズの設定 をご参照ください。

自動クラスタリングを設定するには、Snowflake管理のIcebergテーブルを作成するとき、または既存のテーブルを変更するときに、 CLUSTER BY パラメーターを指定します。詳細については、次をご参照ください。

• CREATE ICEBERG TABLE （IcebergカタログとしてのSnowflake）

• ALTER ICEBERG TABLE

自動クラスタリングの詳細については、 自動クラスタリング をご参照ください。

データ圧縮¶

データ圧縮は、ストレージを管理し、最適なファイルサイズを維持し、クエリパフォーマンスを改善するために、小さなファイルを組み合わせてより大きく効率的なファイルにします。

ほとんどの場合、データ圧縮はコンピューティングコストに大きな影響を与えませんが、これらのコストが気になる場合は、圧縮を無効にすることができます。たとえば、テーブルをほとんどクエリしない場合は、そのテーブルの圧縮を無効にすることができます。データ圧縮を無効または有効にする方法については、:ref:`label-tables_iceberg_manage_set_data_compaction`を参照してください。

マニフェスト圧縮¶

マニフェスト圧縮は、より小さなマニフェストファイルを再編成し組み合わせることにより、メタデータレイヤーを最適化します。この圧縮はメタデータのオーバーヘッドを減らし、クエリのパフォーマンスを改善します。

この機能は自動的に有効になり、無効にすることはできません。

スナップショット有効期限¶

スナップショット有効期限では、古いスナップショットとその固有のデータおよびメタデータファイルをテーブルの履歴からシステム的に削除します。この削除は、事前に定義された保存ポリシーに基づいて行われます。

この機能は自動的に有効になり、無効にすることはできません。

テーブルのメタデータを更新する¶

以下の例では、外部カタログ（AWS Glueまたはデルタなど）を使用するテーブルのメタデータを手動で更新しています。テーブルをリフレッシュすると、リモートカタログで発生した変更とテーブルが同期されます。

この型のIcebergテーブルでは、コマンドでメタデータファイルのパスを指定しません。

ALTER ICEBERG TABLE my_iceberg_table REFRESH;

テーブルを自動的に更新するには、 自動更新 を設定します。ALTER ICEBERG TABLE コマンドを使用します。

例:

ALTER ICEBERG TABLE my_iceberg_table SET AUTO_REFRESH = TRUE;

Icebergファイルから作成されたテーブルのメタデータを更新する¶

次の例では、外部クラウドストレージの場所にある Icebergメタデータファイル から作成されたテーブルを、先頭スラッシュ（/）なしでメタデータファイルへの相対パスを指定して手動でリフレッシュします。メタデータファイルは、更新後のテーブルのデータを定義します。

ALTER ICEBERG TABLE my_iceberg_table REFRESH 'metadata/v1.metadata.json';

例:デフォルト値を持つテーブルを作成する¶

デフォルト値を持つIcebergテーブルを作成するには、:doc:`/sql-reference/sql/create-iceberg-table`コマンドを使用します。

以下の例では、Snowflake管理のIcebergテーブルを作成する際に、まず列のデフォルト値を設定します。次に、デフォルト値を持つ列に値を指定せずに、テーブルにレコードを挿入します。

1. デフォルト値が``2``である``event_version``列を含む``user_events``テーブルを作成します。

   CREATE ICEBERG TABLE user_events (
       event_id INT,
       user_id INT,
       event_type STRING,
       event_time TIMESTAMP,
       event_version INT DEFAULT 2
     )
     CATALOG = 'SNOWFLAKE'
     EXTERNAL_VOLUME = 'my_external_volume'
     BASE_LOCATION = 'database/schema/user_event'
     ICEBERG_VERSION = 3;
   

   Copy

   テーブル定義にデフォルト値を設定すると、初期デフォルトと書き込みデフォルトが設定されます。列には書き込みデフォルトがあるため、書き込み中に``event_version``が指定されていない場合は、新しいレコードに値``2``が使用されます。

2. ``event_version``を指定してログインイベントを追加します。

   INSERT INTO user_events VALUES
     (1, 101, 'login', '2025-11-01 10:00:00', 1);
   

   Copy

3. 購入イベントを追加しますが、``event_version``は指定しません。

   INSERT INTO user_events VALUES
   (1, 101, 'purchase', '2025-11-01 10:01:00');
   

   Copy

   その結果、Snowflakeは``event_version``の値を``2``としてテーブルに入力します。

4. テーブルをクエリします。

   SELECT * FROM user_events;
   

   Copy

   出力:

   +-----------+----------+-------------+---------------------+----------------+
   | event_id  | user_id  | event_type  | event_time          | event_version  |
   +-----------+----------+-------------+---------------------+----------------+
   | 1         | 101      | login       | 2025-11-01 10:00:00 | 1              |
   | 1         | 101      | purchase    | 2025-11-01 10:01:00 | 2              |
   +-----------+----------+-------------+---------------------+----------------+
   

例:既存のテーブルにデフォルト値を持つ列を追加する¶

Icebergテーブルにデフォルト値を持つ新しい列を追加するには、:doc:`/sql-reference/sql/alter-iceberg-table`コマンドを使用します。

次の例では、デフォルト値が``2``である``event_version``列を追加することで``user_events``テーブルを変更します。

ALTER ICEBERG TABLE user_events ADD COLUMN event_version INT DEFAULT 2;

書き込みデフォルトを設定することに加えて、デフォルト値を持つ列を追加すると、列の初期デフォルトも設定されます。その結果、``event_version``列の既存レコードのデフォルト値は``2``になります。

例:列の書き込みデフォルトを変更する¶

以下の例では、``user_events``テーブルの``event_version``列の書き込みデフォルトを``3``に変更します。

ALTER ICEBERG TABLE user_events ALTER COLUMN event_version SET WRITE DEFAULT 3;

テーブル用に定義されたデフォルト値を表示する¶

Snowflake管理または外部管理Icebergテーブルのテーブル列のデフォルト値を表示するには、:doc:`/sql-reference/sql/desc-iceberg-table`コマンドを実行し、出力の``DEFAULT``列と``WRITE DEFAULT``列を表示します。

• ``DEFAULT``列は、Apache Iceberg仕様の``initial-default``値にマップされます。

• ``WRITE DEFAULT``列は、Apache Iceberg仕様の``write-default``値にマップされます。

これらの列は、テーブルがv2 Icebergテーブルかv3 Icebergテーブルかに関係なく、出力として返されます。

以下の例では、``user_events``テーブルの列について説明します。このテーブルには、``event_version``列に初期デフォルトと書き込みデフォルトが指定されています。

DESC ICEBERG TABLE user_events
  ->> SELECT
    "name",
    "kind",
    "default",
    "write default"
      FROM $1;

出力:

+-----------------+---------+---------+---------------+
| name            | kind    | default | write default |
+-----------------+---------+-------------------------+
| EVENT_ID        | COLUMN  |         |               |
| USER_ID         | COLUMN  |         |               |
| EVENT_TYPE      | COLUMN  |         |               |
| EVENT_TIME      | COLUMN  |         |               |
| EVENT_VERSION   | COLUMN  | 2       | 3             |
+-----------------+---------+---------+---------------+

書き込みデフォルトをドロップする¶

列の書き込みデフォルトをドロップするには、ALTER ICEBERG TABLEコマンドで``DROP WRITE DEFAULT``キーワードを使用します。

以下の例では、``event_version``列のデフォルト書き込み値をドロップします。

ALTER ICEBERG TABLE user_events ALTER COLUMN event_version DROP WRITE DEFAULT;

デフォルト値の考慮事項と制限¶

Snowflake管理および外部管理Icebergテーブルでデフォルト値を使用する場合は、以下の項目を考慮してください。

行系統に関する考慮事項と制限¶

行系統は、次の点を考慮してストリームでサポートされています。

• 追加専用ストリームと標準ストリームは、Snowflake管理Iceberg v3テーブルでサポートされています。

• 外部管理Iceberg v3テーブルでは、挿入専用ストリームと標準ストリームがサポートされています。

  • 標準ストリームが正しい結果を生成するようにするには、外部エンジンはIceberg v3の仕様に従ってIceberg v3テーブルに書き込む必要があります。具体的には、新しく挿入された行には:code:`_row_id=NULL`が必要です。書き込み時コピー中にコピーされた行は、:code:`_row_id`を維持する必要があります。

  • MAX_DATA_EXTENSION_TIME_IN_DAYSは外部管理Iceberg v3テーブルでは機能しません。

• DMLsが複数ステートメントのトランザクションでコミットされる場合、Iceberg v3テーブルの追加専用ストリームは、Iceberg v2テーブルと比較して異なるセマンティクスを持ちます。

  • Iceberg v2では、追加専用ストリームにおいて、複数ステートメントのトランザクションで行が追加されてから削除された場合、この行は挿入とみなされます。

  • Iceberg v3では、追加専用ストリームにおいて、この行は挿入として扱われません。

これらの考慮事項と制限は、Iceberg v3からの機能である行系統に適用されます。すべてのIceberg v3テーブルに適用される考慮事項と制限のリストについて詳しくは、:ref:`iceberg-v3_considerations_limitations`を参照してください。