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 | tableColumnAction }

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> SET
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ CATALOG_SYNC = '<snowflake_open_catalog_integration_name>']
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

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

ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> searchOptimizationAction

Copy

条件:

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

Copy

tableColumnAction ::=
  {
     ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
        [ inlineConstraint ]
        [ COLLATE '<collation_specification>' ]

   | RENAME COLUMN <col_name> TO <new_col_name>

   | ALTER | MODIFY [ ( ]
                          , [ COLUMN ] <col1_name> { [ SET ] NOT NULL | DROP NOT NULL }
                          , [ COLUMN ] <col1_name> [ [ SET DATA ] TYPE ] <type>
                          , [ COLUMN ] <col1_name> COMMENT '<string>'
                          , [ COLUMN ] <col1_name> UNSET COMMENT
                        [ , [ COLUMN ] <col2_name> ... ]
                        [ , ... ]
                    [ ) ]

   | DROP [ COLUMN ] [ IF EXISTS ] <col1_name> [, <col2_name> ... ]
  }

  inlineConstraint ::=
    [ NOT NULL ]
    [ CONSTRAINT <constraint_name> ]
    { UNIQUE | PRIMARY KEY | { [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ] } }
    [ <constraint_properties> ]

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>
        [ ENTITY KEY ( <col_name> [, ... ] ) ]
        [ FORCE ]
    | UNSET AGGREGATION POLICY
  }
  |
  {
      SET JOIN POLICY <policy_name>
        [ FORCE ]
    | UNSET JOIN POLICY
  }
  |
  ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
    [ [ WITH ] MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] ]
    [ [ WITH ] PROJECTION POLICY <policy_name> ]
    [ [ WITH ] TAG ( <tag_name> = '<tag_value>'
          [ , <tag_name> = '<tag_value>' , ... ] ) ]
  |
  {
    { 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

searchOptimizationAction ::=
  {
     ADD SEARCH OPTIMIZATION [
       ON <search_method_with_target> [ , <search_method_with_target> ... ]
     ]

   | DROP SEARCH OPTIMIZATION [
       ON { <search_method_with_target> | <column_name> | <expression_id> }
          [ , ... ]
     ]
  }

Copy

詳細については、検索最適化アクション（searchOptimizationAction）をご参照ください。

パラメーター¶

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管理のIcebergテーブルとOpen Catalogの同期に関する情報については、 Snowflakeで管理されたテーブルを Snowflake Open Catalog と同期するをご参照ください。

このパラメーターの詳細については、 CATALOG_SYNC をご参照ください。

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 カタログを自動的にポーリングするかどうかを指定します。

Deltaベースのテーブルの場合、Snowflakeは外部クラウドストレージをポーリングして更新を確認します。

カタログ統合の REFRESH_INTERVAL_SECONDS パラメータに値が指定されていない場合、Snowflake はデフォルトの更新間隔 30 秒を使用します。

デフォルト: FALSE

CONTACT ( purpose = contact [ , purpose = contact ... ] ): プレビュー機能 --- オープン

すべてのアカウントで利用可能です。

既存のオブジェクトを、1つ以上の連絡先に関連付けます。

UNSET

現在、このコマンドで解除できるのは以下のパラメーターのみです。

REPLACE_INVALID_CHARACTERS

CATALOG_SYNC

CONTACT purpose

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

注釈

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

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

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

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

SUSPEND | RESUME RECLUSTER

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

DROP CLUSTERING KEY

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

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

テーブル列アクション（`tableColumnAction`）¶

ADD [ COLUMN ] [ IF NOT EXISTS ] col_name col_data_type . [ inlineConstraint ] [ COLLATE 'collation_specification' ] [ , ... ]

新しい列を追加します。インライン制約または照合順序仕様を指定できます。

テーブル列アクションの詳細については、次をご参照ください。

同じコマンドで複数の列に対して ADD COLUMN 操作を実行できます。

列が既に存在するかどうかわからない場合、列を追加する際に IF NOT EXISTS を指定できます。列が既に存在する場合、 ADD COLUMN は既存の列に影響を与えず、エラーにもなりません。

注釈

新しい列に以下のいずれかを指定している場合は、 IF NOT EXISTS を指定できません。

AUTOINCREMENT、または IDENTITY
UNIQUE、 PRIMARY KEY、または FOREIGN KEY

RENAME COLUMN col_name to new_col_name

指定された列の名前を、テーブル内の他の列で現在使用されていない新しい名前に変更します。

クラスタリングキーの一部である列の名前を変更することはできません。

オブジェクト（テーブル、列など）の名前を変更した場合、そのオブジェクトをリファレンスしている他のオブジェクトを新しい名前で更新する必要があります。

DROP COLUMN [ IF EXISTS ] col_name [ CASCADE | RESTRICT ]

指定した列をテーブルから削除します。

列が既に存在するかどうかわからない場合は、列を削除する際に IF EXISTS を指定できます。列が存在しない場合、 DROP COLUMN は何の効果もなく、エラーにもなりません。

列のドロップは、メタデータのみの操作です。マイクロパーティションを即時に書き換えるわけではないため、列が使っていたスペースが即時に解放されるわけではありません。通常、個々のマイクロパーティション内のスペースは、次にマイクロパーティションが再書き込みされるときに解放されます。これは通常、 DML （INSERT、 UPDATE、 DELETE）または再クラスタリングによって書き込みが完了した時点です。

データガバナンス方針とタグアクション（`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
テーブルから集計ポリシーをデタッチします。

SET JOIN POLICY policy_name

[ FORCE ]
結合ポリシーをテーブルに割り当てます。

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

UNSET JOIN POLICY
テーブルから結合ポリシーを削除します。

{ ALTER | MODIFY } [ COLUMN ] ...

USING ( col_name , cond_col_1 ... )

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

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

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

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

FORCE

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

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

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

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

検索最適化アクション（`searchOptimizationAction`）¶

ADD SEARCH OPTIMIZATION

テーブル全体の、またはオプションの ON 句を指定した場合は特定の列の検索最適化を追加します。

注釈

特にテーブル内のデータが頻繁に変更される場合、検索最適化は維持にコストがかかる可能性があります。詳細については、検索最適化のコスト見積もりおよび管理をご参照ください。

ON search_method_with_target [, search_method_with_target ... ]

（テーブル全体ではなく）特定の列に対して検索最適化を構成したいことを指定します。

search_method_with_target には、次の構文の式を使用します。

<search_method>( <target> [ , <target> , ... ] [ , ANALYZER => '<analyzer_name>' ] )

Copy

条件:

search_method は、特定の型の述語に対するクエリを最適化する次の方法のいずれかを指定します。

検索方法	説明
`FULL_TEXT`	VARCHAR （テキスト）タイプを使用する述語。
`EQUALITY`	等価および IN 述語。
`SUBSTRING`	部分文字列と正規表現に一致する述語（例えば、 [ NOT ] LIKE、 [ NOT ] ILIKE、 [ NOT ] RLIKE、および REGEXP_LIKE）。

target は列またはアスタリスク（*）を指定します。

search_method の値によっては、以下のタイプのいずれかの列を指定できます。

検索方法	サポートされるターゲット
`FULL_TEXT`	VARCHAR （テキスト）データ型の列。
`EQUALITY`	数値、文字列、バイナリデータ型の列。
`SUBSTRING`	VARCHAR （テキスト）データ型の列。

テーブル内の該当するすべての列をターゲットとして指定するには、アスタリスク（*）を使用します。

特定の検索方法に対して、アスタリスクと特定の列名の両方を指定することはできません。ただし、さまざまな検索方法でアスタリスクを指定できます。

たとえば、次の式を指定できます。

-- Allowed
ON SUBSTRING(*)
ON EQUALITY(*), SUBSTRING(*)

Copy

以下の式は指定できません。

-- Not allowed
ON EQUALITY(*, c1)
ON EQUALITY(c1, *)
ON EQUALITY(v1:path, *)
ON EQUALITY(c1), EQUALITY(*)

Copy

search_method が FULL_TEXT の場合、 ANALYZER => 'analyzer_name' がテキスト解析器の名前を指定します。

検索最適化アナライザーの詳細情報については、 ALTER TABLE をご参照ください。

ターゲットに複数の検索方法を指定するには、コンマを使用して後続の各メソッドとターゲットを区切ります。

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1), EQUALITY(c2, c3);

Copy

同じテーブルに対して ALTER ICEBERG TABLE ... ADD SEARCH OPTIMIZATION ON ... コマンドを複数回実行すると、後続の各コマンドがテーブルの既存の構成に追加されます。たとえば、次のコマンドを実行するとします。

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2);
ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c3, c4);

Copy

これにより、列c1、c2、c3、およびc4の等価述語がテーブルの構成に追加されます。これは、次のコマンドを実行するのと同じです。

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2, c3, c4);

Copy

例については、特定の列に対する検索最適化の有効化をご参照ください。

DROP SEARCH OPTIMIZATION

テーブル全体の、またはオプションの ON 句を指定した場合は特定の列から検索最適化を削除します。

注釈

テーブルに検索最適化プロパティがある場合、テーブルをドロップしてからドロップを解除すると、検索最適化プロパティが保持されます。
テーブルから検索最適化プロパティを削除した後に再度追加すると、最初に追加したときと同じコストがかかります。

ON search_method_with_target | column_name | expression_id [ , ... ]

（テーブル全体の検索最適化を削除するのではなく）特定の列の検索最適化構成を削除することを指定します。

ドロップする列構成を識別するには、次のいずれかを指定します。

search_method_with_target では、1つ以上の特定の列に対するクエリを最適化する方法を指定します。前に説明されている構文を使用します。
column_name には、検索最適化用に構成された列の名前を指定します。列名を指定すると、その列の式はすべて削除されます。
expression_id には、 DESCRIBE SEARCH OPTIMIZATION コマンドの出力にリストされた式の ID を指定します。

これらを複数指定するには、項目間にコンマを使用します。

ターゲット、列名、および式 IDs を使用して、検索方法を自由に組み合わせて指定できます。

例については、特定の列に対する検索最適化のドロップをご参照ください。

アクセス制御の要件¶

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

権限	オブジェクト	注意
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 テーブルでデータメトリック関数を使用できます。詳細については、データ測定関数を使用してデータ品質チェックを実行します。をご参照ください。
制限など、Icebergテーブルでの検索最適化の使用については、検索最適化ドキュメントの Apache 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 my_iceberg_table SET AUTO_REFRESH = TRUE;

Copy

次の例は、Icebergテーブルの検索最適化を追加および削除します。

ALTER ICEBERG TABLE my_iceberg_table ADD SEARCH OPTIMIZATION ON SUBSTRING(C6);

ALTER ICEBERG TABLE my_iceberg_table DROP SEARCH OPTIMIZATION ON EQUALITY(C7, C8);

Copy

ALTER ICEBERG TABLE¶

構文¶

パラメーター¶

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

テーブル列アクション（tableColumnAction）¶

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

検索最適化アクション（searchOptimizationAction）¶

アクセス制御の要件¶

使用上の注意¶

例¶

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

テーブル列アクション（`tableColumnAction`）¶

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

検索最適化アクション（`searchOptimizationAction`）¶