ALTER ICEBERG TABLE

既存の Icebergテーブル のプロパティ、列、または制約を変更します。Icebergテーブルがカタログ統合を使用している場合、 ALTER ICEBERG TABLE を使用して新しいデータでテーブルを更新します。

ALTER ICEBERG TABLE を使用して、カタログ統合を使用するテーブルを、SnowflakeをIcebergカタログとして使用するテーブルに変換することもできます。詳細については、 Icebergテーブルの変換 をご参照ください。

このトピックでは、 Iceberg tables と指定することで混乱を避ける場合を除き、Icebergテーブルを単に「テーブル」と呼びます。

こちらもご参照ください。

CREATE ICEBERG TABLEDROP ICEBERG TABLESHOW ICEBERG TABLESDESCRIBE ICEBERG TABLE

構文

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> REFRESH [ '<metadata_file_relative_path>' ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> CONVERT TO MANAGED [ BASE_LOCATION = '<file_path>' ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> clusteringAction

ALTER ICEBERG TABLE [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER ICEBERG TABLE [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ]
Copy

条件:

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }
Copy

パラメーター

name

変更するIcebergテーブルの識別子。識別子にスペースまたは特殊文字が含まれる場合は、文字列全体を二重引用符で囲む必要があります。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

REFRESH [ 'metadata_file_relative_path' ]

Snowflakeが管理していないIcebergテーブルの指定されたパス(テーブルの外部ボリュームストレージの場所に対して相対)にあるメタデータファイルにアクセスし、テーブルメタデータを更新します。

このオプションは、IcebergテーブルがオブジェクトストレージのIcebergファイルをソースとして使用する場合にのみ使用します。Icebergカタログとして AWS Glueを使用する場合はこのオプションを省略します。

例えば、 s3://mybucket_us_east_1/metadata/v1.metadata.json がメタデータファイルへのフルパスで、テーブルに関連付けられた外部ボリュームのストレージの場所が s3://mybucket_us_east_1 の場合、 metadata/v1.metadata.jsonmetadata_file_relative_path として指定します。

注釈

Snowflakeのバージョン7.34以前では、オブジェクトストレージ内のIcebergファイルからテーブルを作成するには BASE_LOCATION (以前のバージョンでの別称は FILE_PATH)というパラメーターが必要でした。パラメーターは、 EXTERNAL_VOLUME の場所からの相対パスを指定しました。

古い構文を使用して作成したテーブルをリフレッシュするには、 BASE_LOCATION への相対パスを指定します。例えば、メタデータファイルのフルパスが s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json の場合、 metadata/v1.metadata.jsonmetadata-file-relative-path として指定します。

CONVERT TO MANAGED

カタログ統合を使用する読み取り専用のIcebergテーブルを、IcebergカタログとしてSnowflakeを使用するテーブルに変換します。変換されたテーブルは、読み取りと書き込みの両方の操作をサポートし、Snowflakeはコンパクションなどのテーブルのすべてのライフサイクルメンテナンスを処理します。詳細については、 Icebergテーブルの変換 をご参照ください。

[ BASE_LOCATION = 'file_path' ]

テーブルの EXTERNAL_VOLUME の場所から、Snowflakeがテーブルデータとメタデータを書き込めるディレクトリへの相対パスを指定します。元の CREATE ICEBERG TABLE ステートメントが BASE_LOCATION を許可していなかったり、含んでいなかったりする場合は、変換時にこのプロパティの値を指定する必要があります。

このパラメーターの値は、テーブルを変換した後に変更することはできません。

SET ...

外部テーブルのために設定する1つ以上のプロパティ/パラメーターを指定します(空白、コンマ、または改行で区切り)。

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

タグ の名前とタグ文字列の値を指定します。

タグ値は常に文字列であり、タグ値の最大文字数は256です。

ステートメントでのタグの指定に関する情報については、 オブジェクトおよび列のタグクォータ をご参照ください。

UNSET

現在、このコマンドで設定解除できるのは以下のみです。

  • TAG tag_name [ , tag_name ... ]

クラスタリングアクション(clusteringAction

注釈

クラスタリングをサポートしているのは、SnowflakeをIcebergカタログとして使用するテーブルのみです。

CLUSTER BY ( expr [ , expr , ... ] )

1つ以上のテーブル列または列式をテーブルのクラスタリングキーとして指定(または変更)します。これらは 自動クラスタリング によってクラスタリングが維持される列/式です。

クラスタリングの詳細については クラスタリングキーとクラスタ化されたテーブル をご参照ください。

SUSPEND | RESUME RECLUSTER

テーブルの 自動クラスタリング を有効または無効にします。

DROP CLUSTERING KEY

テーブルのクラスタリングキーをドロップします。

クラスタリングキーと再クラスタリングの詳細については、 Snowflakeテーブル構造について をご参照ください。

アクセス制御の要件

この SQL コマンドの実行に使用される ロール には、少なくとも次の 権限 が必要です。

権限

オブジェクト

メモ

OWNERSHIP

Icebergテーブル

OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

USAGE

外部ボリューム

テーブルメタデータを手動で更新する必要があります。

USAGE

ファイル形式

テーブルメタデータを手動で更新する必要があります。

スキーマ内の任意のオブジェクトを操作するには、親データベースとスキーマに対する USAGE 権限も必要であることに注意してください。

指定された権限のセットを使用してカスタムロールを作成する手順については、 カスタムロールの作成 をご参照ください。

セキュリティ保護可能なオブジェクト に対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、 アクセス制御の概要 をご参照ください。

使用上の注意

  • このコマンドを実行できるのは、テーブルの所有者(つまり、テーブルに対する OWNERSHIP 権限を持つロール)以上のみです。

  • クラスタリングをサポートしているのは、SnowflakeをIcebergカタログとして使用するテーブルのみです。Icebergテーブルにクラスタリングを追加するには、テーブルを含むスキーマとデータベースに対する USAGE または OWNERSHIP 権限も必要です。

  • トランザクション内(暗黙的または明示的)での ALTER ICEBERG TABLE ... REFRESH コマンドの使用はサポートされていません。

  • Snowflakeのバージョン7.34以前では、オブジェクトストレージ内のIcebergファイルからテーブルを作成するには BASE_LOCATION (以前のバージョンでの別称は FILE_PATH)というパラメーターが必要でした。パラメーターは、 EXTERNAL_VOLUME の場所からの相対パスを指定しました。

    古い構文を使用して作成したテーブルをリフレッシュするには、 BASE_LOCATION への相対パスを指定します。例えば、メタデータファイルのフルパスが s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json の場合、 metadata/v1.metadata.jsonmetadata-file-relative-path として指定します。

  • メタデータについて:

    注意

    Snowflakeサービスを使用する場合、お客様は、個人データ(ユーザーオブジェクト向け以外)、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールド をご参照ください。

カタログ統合を使用するテーブルのテーブルメタデータを手動で更新する

オブジェクトストレージのIcebergファイル

この例では、新しいメタデータファイルの変更に基づいてテーブルメタデータを手動で更新します。この例では、メタデータファイルへのフルパスは <external-volume-storage-base-url>/path/to/metadata/v2.metadata.json です。

注釈

Snowflakeのバージョン7.34以前では、オブジェクトストレージ内のIcebergファイルからテーブルを作成するには BASE_LOCATION (以前のバージョンでの別称は FILE_PATH)というパラメーターが必要でした。パラメーターは、 EXTERNAL_VOLUME の場所からの相対パスを指定しました。

古い構文を使用して作成したテーブルをリフレッシュするには、 BASE_LOCATION への相対パスを指定します。例えば、メタデータファイルのフルパスが s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json の場合、 metadata/v1.metadata.jsonmetadata-file-relative-path として指定します。

ALTER ICEBERG TABLE my_iceberg_table REFRESH 'path/to/metadata/v2.metadata.json';
Copy

AWS Glue

この例では、Icebergカタログの AWS Glueを使用しているテーブルのメタデータを手動で更新します。AWS GlueをIcebergカタログとして使用する場合は、リフレッシュコマンドでメタデータファイルパスを指定しません。

ALTER ICEBERG TABLE myIcebergTable REFRESH;
Copy

Icebergテーブルの変換

次の例では ALTER ICEBERG TABLE ... CONVERT TO MANAGED ステートメントを使用して、Snowflakeが管理していないテーブルをIcebergカタログとしてSnowflakeを使用するテーブルに変換します。

ALTER ICEBERG TABLE myTable CONVERT TO MANAGED
  BASE_LOCATION = myBaseLocation;
Copy