ALTER ICEBERG TABLE¶

既存の Apache Iceberg™テーブルのクラスタリングオプションやタグなどのプロパティを変更します。

また、 ALTER ICEBERG TABLE ステートメントを使用して、テーブルをリフレッシュしたり、テーブルを変換したり、構造化タイプの列を変更したりすることもできます。これらの操作の構文はかなり異なります。Icebergテーブルのリフレッシュまたは変換の構文、パラメーターの説明、使用上の注意、および例を表示するには、以下のページをご参照ください。

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

こちらもご参照ください。: CREATE ICEBERG TABLE、 DROP ICEBERG TABLE、 SHOW ICEBERG TABLES、 DESCRIBE ICEBERG TABLE

構文¶

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> clusteringAction

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> SET
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ CATALOG_SYNC = '<open_catalog_integration_name>']
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> UNSET REPLACE_INVALID_CHARACTERS

ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction

Copy

条件:

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

Copy

dataGovnPolicyTagAction ::=
  {
      SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
    | UNSET TAG <tag_name> [ , <tag_name> ... ]
  }
  |
  {
      ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ROW ACCESS POLICY <policy_name>
    | DROP ROW ACCESS POLICY <policy_name> ,
        ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ALL ROW ACCESS POLICIES
  }
  |
  {
      SET AGGREGATION POLICY <policy_name> [ FORCE ]
      | UNSET AGGREGATION POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] [ FORCE ]
      | UNSET MASKING POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET PROJECTION POLICY <policy_name>
          [ FORCE ]
      | UNSET PROJECTION POLICY
  }
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> SET TAG
      <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
      , [ COLUMN ] <col2_name> SET TAG
          <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
                  , [ COLUMN ] <col2_name> UNSET TAG <tag_name> [ , <tag_name> ... ]

Copy

パラメーター¶

table_name

変更するテーブルの識別子。

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

詳細については、識別子の要件をご参照ください。

SET ...

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

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

クエリ結果で、無効な UTF -8文字をUnicode置換文字（�）で置き換えるかどうかを指定します。このパラメーターを設定できるのは、外部Icebergカタログを使用するテーブルのみです。

TRUE の場合は、無効な UTF -8文字がUnicode置換文字に置き換えられます。
FALSE の場合は、無効な UTF -8 文字は変更されません。Parquetデータファイルで無効な UTF -8 文字が検出された場合、Snowflakeはユーザーエラーメッセージを返します。

指定しない場合、Icebergテーブルのデフォルトはスキーマ、データベース、またはアカウントのパラメーター値になります。スキーマはデータベースより優先され、データベースはアカウントより優先されます。

デフォルト: FALSE

CATALOG_SYNC = 'snowflake_open_catalog_integration_name': Snowflake Open Catalog 用に構成されたカタログ統合の名前を指定します。Snowflakeは、 Snowflake Open Catalog アカウントの外部カタログとテーブルを同期します。詳細については、 Snowflakeで管理されたテーブルを Snowflake Open Catalog と同期するをご参照ください。

DATA_RETENTION_TIME_IN_DAYS = integer

Snowflake管理テーブルの履歴データに対してTime Travelアクション（SELECT、 CLONE、 UNDROP）を実行できるように、テーブルの保持期間を指定します。詳細については、 Time Travelの理解と使用をご参照ください。

このオブジェクトレベルパラメーターの詳細な説明、およびオブジェクトパラメーターの詳細については、パラメーターをご参照ください。

値：

Standard Edition： 0 または 1

Enterprise Edition: 永続テーブルの場合は 0 ～ 90

デフォルト：

Standard Edition： 1

Enterprise Edition（またはそれ以上）： 1 （スキーマ、データベースまたはアカウントレベルで別のデフォルト値が指定されていない場合）

注釈

0 の値は、テーブルのTime Travelを効果的に無効化します。

AUTO_REFRESH = { TRUE | FALSE }

自動リフレッシュを使用する場合に、メタデータの更新のために、Snowflake がテーブルに関連付けられた外部 Iceberg カタログを自動的にポーリングするかどうかを指定します。カタログ統合の REFRESH_INTERVAL_SECONDS パラメータに値が指定されていない場合、Snowflake はデフォルトの更新間隔 30 秒を使用します。

デフォルト: FALSE

UNSET

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

REPLACE_INVALID_CHARACTERS

クラスタリングアクション（`clusteringAction`）¶

注釈

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

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

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

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

SUSPEND | RESUME RECLUSTER

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

DROP CLUSTERING KEY

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

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

データガバナンス方針とタグアクション（`dataGovnPolicyTagAction`）¶

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

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

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

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

policy_name: ポリシーの識別子。スキーマに対して一意である必要があります。

以下の句は、テーブル、ビュー、イベントテーブルなど、行アクセスポリシーをサポートするすべての種類のテーブルに適用されます。簡略化するために、句は単に「テーブル」を指しています。

ADD ROW ACCESS POLICY policy_name ON (col_name [ , ... ])
行アクセスポリシーをテーブルに追加します。

少なくとも1つの列名を指定する必要があります。追加の列は、各列名をコンマで区切って指定できます。この式を使用して、イベントテーブルと外部テーブルの両方に行アクセスポリシーを追加します。

DROP ROW ACCESS POLICY policy_name
テーブルから行アクセスポリシーをドロップします。

テーブルからポリシーをドロップするには、この句を使用します。

DROP ROW ACCESS POLICY policy_name, ADD ROW ACCESS POLICY policy_name ON ( col_name [ , ... ] )
テーブルに設定されている行アクセスポリシーをドロップし、1つの SQL ステートメントで同じテーブルに行アクセスポリシーを追加します。

DROP ALL ROW ACCESS POLICIES
テーブルからすべての行アクセスポリシーの関連付けをドロップします。

この式は、イベントテーブルからポリシーをドロップする前に、スキーマから行アクセスポリシーをドロップするときに役立ちます。この式を使用して、テーブルから行アクセスポリシーの関連付けをドロップします。

SET AGGREGATION POLICY policy_name

[ ENTITY KEY (col_name [ , ... ]) ] [ FORCE ]
テーブルに集計ポリシーを割り当てます。

オプションの ENTITY KEY パラメーターを使用して、テーブル内でエンティティを一意に識別する列を定義します。詳細については、集計ポリシーによるエンティティレベルのプライバシーの実装をご参照ください。

既存の集計ポリシーを新しい集計ポリシーにアトミックに置き換えるには、オプションの FORCE パラメーターを使用します。

UNSET AGGREGATION POLICY
テーブルから集計ポリシーをデタッチします。

{ ALTER | MODIFY } [ COLUMN ] ...

USING ( col_name , cond_col_1 ... )

条件付きマスキングポリシー SQL 式に渡す引数を指定します。

リストの最初の列は、データをマスクまたはトークン化するポリシー条件の列を指定し、マスキングポリシーが設定されている列と一致する必要があります。

追加の列は、最初の列でクエリが実行されたときに、クエリ結果の各行のデータをマスクするかトークン化するかを決定するために評価する列を指定します。

USING 句が省略されている場合、Snowflakeは条件付きマスキングポリシーを通常のマスキングポリシーとして扱います。

FORCE

単一のステートメント内で、列に現在設定されているマスキングまたは投影ポリシーを別のポリシーに置き換えます。

マスキングポリシーで FORCE キーワードを使用するには、 ALTER TABLE ステートメント（つまり STRING）内のポリシーのデータ型が、列に現在設定されているマスキングポリシーのデータ型（つまり STRING）と一致している必要があります。

現在列にマスキングポリシーが設定されていない場合は、このキーワードを指定しても効果はありません。

詳細については、列のマスキングポリシーを置き換えるまたは投影ポリシーの置き換えをご参照ください。

アクセス制御の要件¶

この 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 TABLE コマンドを実行すると、Iceberg テーブルでデータメトリック関数を使用できます。詳細については、データメトリック関数の操作をご参照ください。
メタデータについて:

注意

Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールドをご参照ください。
CATALOG_SYNC パラメーターの変更に関するトラブルシューティングについては、 CATALOG_SYNC パラメーターを指定した際、Icebergテーブルを変更することができないをご参照ください。

例¶

次の例では、Icebergテーブルに値 customer のタグ（my_tag）を設定します。

ALTER ICEBERG TABLE my_iceberg_table SET TAG my_tag = 'customer';

Copy

ALTER ICEBERG TABLE¶

構文¶

パラメーター¶

クラスタリングアクション（clusteringAction）¶

データガバナンス方針とタグアクション（dataGovnPolicyTagAction）¶

アクセス制御の要件¶

使用上の注意¶

例¶

クラスタリングアクション（`clusteringAction`）¶

データガバナンス方針とタグアクション（`dataGovnPolicyTagAction`）¶