ALTER 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 ] <table_name> SET
  TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

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

条件:

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.json を metadata_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.json を metadata-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）¶

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

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

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

SUSPEND | RESUME RECLUSTER

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

DROP CLUSTERING KEY

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

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

アクセス制御の要件¶

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

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

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

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

使用上の注意¶

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

• Icebergテーブルにクラスタリングを追加するには、テーブルを含むスキーマとデータベースに対する USAGE または OWNERSHIP 権限も必要です。

• 次のコマンドは、明示的なトランザクションで使用できます（BEGIN ... COMMIT を使用）: ALTER ICEBERG TABLE ... REFRESH ['metadata_file_relative_pathname']。

  明示的なトランザクションを使用して、テーブルメタデータ内の更新されたファイルを手動で置き換えるときに、一貫した状態を確保できます。

• 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.json を metadata-file-relative-path として指定します。

• Regarding metadata:

  注意

  Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Snowflakeのメタデータフィールド.

例¶

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

ALTER ICEBERG TABLE myIcebergTable REFRESH;

ALTER ICEBERG TABLE myTable CONVERT TO MANAGED
  BASE_LOCATION = myBaseLocation;