ALTER TABLE (イベントテーブル)

既存の イベントテーブル のプロパティ、列、または制約を変更します。

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

CREATE EVENT TABLEDROP TABLESHOW EVENT TABLESDESCRIBE EVENT TABLE

構文

ALTER TABLE [ IF EXISTS ] <name> RENAME TO <new_table_name>

ALTER TABLE [ IF EXISTS ] <name> clusteringAction

ALTER TABLE [ IF EXISTS ] <name> dataGovnPolicyTagAction

ALTER TABLE [ IF EXISTS ] <name> searchOptimizationAction

ALTER TABLE [ IF EXISTS ] <name> SET
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ CHANGE_TRACKING = { TRUE | FALSE  } ]
  [ COMMENT = '<string_literal>' ]

ALTER TABLE [ IF EXISTS ] <name> UNSET {
                                       DATA_RETENTION_TIME_IN_DAYS         |
                                       MAX_DATA_EXTENSION_TIME_IN_DAYS     |
                                       CHANGE_TRACKING                     |
                                       COMMENT                             |
                                       }
Copy

条件:

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
   | { 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
  }
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) をご参照ください。

パラメーター

name

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

RENAME TO new_table_name

指定されたイベントテーブルの名前を、スキーマ内の他のイベントテーブルで現在使用されていない新しい識別子に変更します。

イベントテーブル識別子の詳細については、 識別子の要件 をご参照ください。

オプションでオブジェクトの名前を変更して、オブジェクトを別のデータベースやスキーマに移動できます。これを実行するには、新しいデータベース名やスキーマ名をそれぞれ db_name.schema_name.object_name または schema_name.object_name の形式で含む、修飾された new_name 値を指定します。

注釈

  • 宛先データベースやスキーマはすでに存在している必要があります。また、同じ名前のオブジェクトが宛先データベースにすでに存在することはできません。存在する場合、ステートメントはエラーを返します。

  • オブジェクトをマネージドアクセススキーマに移動することは、オブジェクトの所有者(つまり、オブジェクトに対して OWNERSHIP 権限を持つロール)がターゲットスキーマも所有している場合を 除き 禁止されています。

オブジェクト(テーブル、列など)の名前が変更されると、それを参照する他のオブジェクトも新しい名前で更新する必要があります。

SET ...

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

DATA_RETENTION_TIME_IN_DAYS = integer

Time Travelのイベントテーブルの保持期間を変更するオブジェクトレベルのパラメーター。詳細については、 Time Travelの理解と使用 および 仮テーブルと一時テーブルの使用 をご参照ください。

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

値:

  • Standard Edition: 0 または 1

  • Enterprise Edition:

    • 永続イベントテーブルの場合は 090

    • 仮および一時イベントテーブルの場合は 0 または 1

注釈

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

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

Snowflakeがイベントテーブルのデータ保持期間を延長して、イベントテーブル上のストリームが古くなるのを防ぐことができる最大日数を指定するオブジェクトパラメーター。

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

CHANGE_TRACKING = TRUE | FALSE

イベントテーブルの変更追跡を有効または無効にするように指定します。

  • TRUE は、イベントテーブルの変更追跡を有効にします。このオプションは、非表示の列のペアをソースのイベントテーブルに追加し、列に変更追跡メタデータを保存し始めます。これらの列は少量のストレージを消費します。

    変更追跡メタデータのクエリには、 SELECT ステートメントの CHANGES 句を使用するか、イベントテーブルで1つ以上のストリームを作成し、クエリします。

  • FALSE イベントテーブルの変更追跡を無効にします。非表示の列のペアがイベントテーブルから削除されます。

COMMENT = 'string_literal'

イベントテーブルのコメントを追加するか、既存のコメントを上書きします。

UNSET ...

イベントテーブルの設定を解除する1つまたは複数のプロパティ/パラメーターを指定し、それらをデフォルトにリセットします。

  • DATA_RETENTION_TIME_IN_DAYS

  • MAX_DATA_EXTENSION_TIME_IN_DAYS

  • CHANGE_TRACKING

  • COMMENT

データガバナンス方針とタグアクション(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 [ FORCE ]

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

UNSET AGGREGATION POLICY

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

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

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

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

重要

クラスタリングキーは、すべてのイベントテーブルに対して意図または推奨されているわけでは ありません。通常は、非常に大きな(つまり、マルチテラバイト)イベントテーブルに役立ちます。

イベントテーブルのクラスタリングキーを指定する前に、 Snowflakeテーブル構造について をご参照ください。

SUSPEND | RESUME RECLUSTER

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

DROP CLUSTERING KEY

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

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

検索最適化アクション( searchOptimizationAction

ADD SEARCH OPTIMIZATION

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

注意:

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

  • マテリアライズドビューに検索最適化を追加しようとすると、Snowflakeはエラーメッセージを返します。

ON search_method_with_target [, search_method_with_target ... ]

特定の列または VARIANT フィールド(イベントテーブル全体ではなく)に対して検索最適化を構成することを指定します。

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

<search_method>(<target> [, ...])
Copy

条件:

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

    検索方法

    説明

    EQUALITY

    等価および IN 述語。

    SUBSTRING

    部分文字列と正規表現に一致する述語(例: [ NOT ] LIKE[ NOT ] ILIKE[ NOT ] RLIKEREGEXP_LIKE など)

    GEO

    GEOGRAPHY 型を使用する述語。

  • target は、列、 VARIANT フィールド、またはアスタリスク(*)を指定します。

    search_method の値に応じて、次に挙げる型の列または VARIANT フィールドを指定できます。

    検索方法

    サポートされるターゲット

    EQUALITY

    VARIANTs 内のフィールドへのパスを含む、数値、文字列、バイナリ、および VARIANT データ型の列。

    VARIANT フィールドを指定するには、フィールドへのコロン区切りのパス(例: my_column:my_field_name:my_nested_field_name)を使用するか、 ドットまたはブラケット表記 (例: my_column:my_field_name.my_nested_field_name または my_column['my_field_name']['my_nested_field_name'])を使用します。

    VARIANT フィールドを指定すると、そのフィールドの下にネストされたすべてのフィールドに構成が適用されます。たとえば、 ON EQUALITY(src:a.b) を指定するとします。

    • この構成により、クエリ on src:a.b およびネストされたフィールド(例: src:a.b.csrc:a.b.c.d など)を改善できます。

    • この構成は、 src:a.b プレフィックスを使用しないクエリ(例: src:asrc:z など)には影響しません。

    SUBSTRING

    文字列データ型の列。

    GEO

    GEOGRAPHY データ型の列。

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

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

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

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

    次の式は指定できません。

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

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

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

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

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

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

ALTER 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 [, ... ]

特定の列または VARIANT フィールド(イベントテーブル全体の検索最適化をドロップするのではなく)の検索最適化構成をドロップすることを指定します。

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

  • search_method_with_target には、1つ以上の特定のターゲット(列または VARIANT フィールド)のクエリを最適化する方法を指定します。 前に説明されている構文 を使用します。

  • column_name には、検索最適化用に構成された列の名前を指定します。列名を指定すると、その列の VARIANT フィールドを使用する式を含む、その列のすべての式がドロップされます。

  • expression_id には、 DESCRIBE SEARCH OPTIMIZATION コマンドの出力にリストされた式の ID を指定します。

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

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

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

使用上の注意

  • イベントテーブルへの変更は、そのイベントテーブルで作成されたビューには自動的に反映されません。

  • イベントテーブルを変更するには、イベントテーブルの所有権限を持つロールを使用する必要があります。

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

  • 行アクセスポリシーの場合、

    • Snowflakeは、単一の SQL ステートメントで行アクセスポリシーの追加とドロップをサポートしています。

      たとえば、テーブルにすでに設定されている行アクセスポリシーを別のポリシーに置き換えるには、最初に行アクセスポリシーをドロップしてから、新しい行アクセスポリシーを追加します。

    • 特定のリソース(つまり、テーブルまたはビュー)の場合、行アクセスポリシーを ADD または DROP するには、スキーマに対する APPLY ROW ACCESS POLICY 権限、 または リソースに対する OWNERSHIP 権限と行アクセスポリシーリソースに対する APPLY 権限が必要です。

    • テーブルまたはビューは、一度に1つの行アクセスポリシーでのみ保護できます。ポリシー本体が、行アクセスポリシーによって保護されているテーブルまたはビューの列、またはマスキングポリシーによって保護されている列を参照している場合、ポリシーの追加は失敗します。

      同様に、マスキングポリシー本体が、行アクセスポリシーまたは別のマスキングポリシーによって保護されているテーブルを参照している場合、テーブル列へのマスキングポリシーの追加は失敗します。

    • 行アクセスポリシーは、システムビューまたはテーブル関数には適用できません。

    • 他の DROP <オブジェクト> 操作と同様に、行アクセスポリシーが追加されていないリソースから行アクセスポリシーをドロップしようとすると、Snowflakeはエラーを返します。

    • オブジェクトに行アクセスポリシーと1つ以上のマスキングポリシーの両方がある場合は、行アクセスポリシーが最初に評価されます。

  • 外部キーを作成する場合、 REFERENCES 句の列は、主キーの列と同じ順序でリストする必要があります。例:

    create table parent ... constraint primary_key_1 primary key (c_1, c_2) ...
    create table child  ... constraint foreign_key_1 foreign key (...) REFERENCES parent (c_1, c_2) ...
    
    Copy

    どちらの場合も、列の順序は c_1, c_2 です。外部キーの列の順序が異なっていた場合(例: c_2, c_1)、外部キーを作成する試みは失敗していました。

  • メタデータについて、

    注意

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

  • ALTER TABLE ... CHANGE_TRACKING = TRUE

    • 変更の追跡を有効にするためにイベントテーブルが変更されると、イベントテーブルは操作の間ロックされます。ロックにより、関連する DDL/DML オペレーションの一部で遅延が発生する可能性があります。詳細については、 リソースのロック をご参照ください。

イベントテーブル t1 の名前を a1 に変更します。

CREATE OR REPLACE TABLE t1(a1 number);

SHOW TABLES LIKE 't1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes | owner  | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
 Tue, 17 Mar 2015 16:52:33 -0700 | T1   | TESTDB        | MY_SCHEMA   | TABLE |         |            | 0    | 0     | PUBLIC | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+

ALTER TABLE t1 RENAME TO tt1;

SHOW TABLES LIKE 'tt1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes | owner  | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
 Tue, 17 Mar 2015 16:52:33 -0700 | TT1  | TESTDB        | MY_SCHEMA   | TABLE |         |            | 0    | 0     | PUBLIC | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------+----------------+
Copy

イベントテーブルのクラスタリングキーの順序を変更します。

CREATE OR REPLACE TABLE T1 (id NUMBER, date TIMESTAMP_NTZ, name STRING) CLUSTER BY (id, date);

SHOW TABLES LIKE 'T1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes |    owner     | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
 Tue, 21 Jun 2016 15:42:12 -0700 | T1   | TESTDB        | TESTSCHEMA  | TABLE |         | (ID,DATE)  | 0    | 0     | ACCOUNTADMIN | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+

-- Change the order of the clustering key
ALTER TABLE t1 CLUSTER BY (date, id);

SHOW TABLES LIKE 'T1';

---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
           created_on            | name | database_name | schema_name | kind  | comment | cluster_by | rows | bytes |    owner     | retention_time |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
 Tue, 21 Jun 2016 15:42:12 -0700 | T1   | TESTDB        | TESTSCHEMA  | TABLE |         | (DATE,ID)  | 0    | 0     | ACCOUNTADMIN | 1              |
---------------------------------+------+---------------+-------------+-------+---------+------------+------+-------+--------------+----------------+
Copy

次の例では、単一の列を指定しながら、イベントテーブルに行アクセスポリシーを追加します。ポリシーを設定した後、 Information Schema を確認することで検証できます。

ALTER TABLE t1
  ADD ROW ACCESS POLICY rap_t1 ON (empl_id);
Copy

次の例では、単一のイベントテーブルで2つの列を指定しながら、行アクセスポリシーを追加します。

ALTER TABLE t1
  ADD ROW ACCESS POLICY rap_test2 ON (cost, item);
Copy

次の例では、イベントテーブルから行アクセスポリシーをドロップします。 Information Schema にクエリを実行して、ポリシーがドロップされたことを検証します。

ALTER TABLE t1
  DROP ROW ACCESS POLICY rap_v1;
Copy

次の例は、テーブルの単一の SQL ステートメントで行アクセスポリシーの追加とドロップを組み合わせる方法を示しています。 Information Schema を確認して結果を検証します。

alter table t1
  drop row access policy rap_t1_version_1,
  add row access policy rap_t1_version_2 on (empl_id);
Copy