カテゴリ：

テーブル、ビュー、シーケンス DDL

ALTER EXTERNAL TABLE

既存のストリームのプロパティ、列、または制約を変更します。

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

CREATE EXTERNAL TABLE 、 DROP EXTERNAL TABLE 、 SHOW EXTERNAL TABLES

このトピックの内容：

構文

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> REFRESH [ '<relative-path>' ]

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> ADD FILES ( '<path>/[<filename>]' [ , [ '<path>/[<filename>'] ] )

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> REMOVE FILES ( '<path>/[<filename>]' [ , [ '<path>/[<filename>]' ] )

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> SET
  [ AUTO_REFRESH = { TRUE | FALSE } ]

ALTER EXTERNAL TABLE [ IF EXISTS ] <name>
  ADD ROW ACCESS POLICY <policy_name> ON (<col_name> [ , ... ])

ALTER EXTERNAL TABLE [ IF EXISTS ] <name>
  DROP ROW ACCESS POLICY <policy_name>

ALTER EXTERNAL TABLE [ IF EXISTS ] <name>
  ADD ROW ACCESS POLICY <policy_name> ON (<col_name> [ , ... ])
  , DROP ROW ACCESS POLICY <policy_name>

パラメーター

名前

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

REFRESH [ '相対サブパス' ]

外部テーブル定義で参照されるステージングされたデータファイルにアクセスし、テーブルメタデータを更新します。

  • パス内の新しいファイルがテーブルメタデータに追加されます。

  • パス内のファイルへの変更は、テーブルメタデータで更新されます。

  • パス内になくなったファイルは、テーブルメタデータから削除されます。

任意で、相対パスを指定して、データファイルの特定のサブセットに対するメタデータを更新します。

このパラメーターの使用は、外部テーブルの作成時に一度だけ行う必要があります。このステップでは、外部テーブル定義のステージおよびパスにある関連ファイルの最新セットとメタデータが同期されます。また、このステップにより、外部テーブルが指定されたステージとパスのデータファイルを読み取ることができ、外部テーブル定義に欠落しているファイルがないことを確認します。

ADD FILES

指定したファイルのコンマ区切りリストを外部テーブルのメタデータに追加します。通常、 ADD FILES および REMOVE FILES パラメーターは、外部テーブルのメタデータを手動で更新するために使用されます（つまり、 AUTO_REFRESH = FALSE の場合）。ファイル参照は、外部テーブル定義の[ WITH ] LOCATION に相対するパスとして表されます。詳細については、 CREATE EXTERNAL TABLE をご参照ください。

各ファイルのパスとファイル名をリストします。

ALTER EXTERNAL TABLE ステートメントは、外部テーブルのメタデータを自動的に更新し、指定された保存場所に存在する場合はファイルを追加します。

REMOVE FILES

指定されたファイルのコンマ区切りリストを外部テーブルのメタデータから削除します。通常、 ADD FILES および REMOVE FILES パラメーターは、外部テーブルのメタデータを手動で更新するために使用されます（つまり、 AUTO_REFRESH = FALSE の場合）。ファイル参照は、外部テーブル定義の[ WITH ] LOCATION に相対するパスとして表されます。詳細については、 CREATE EXTERNAL TABLE をご参照ください。

各ファイルのパスとファイル名をリストします。

ALTER EXTERNAL TABLE ステートメントは、外部テーブルのメタデータを自動的に更新し、ファイルを削除します。

SET ...

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

AUTO_REFRESH = TRUE | FALSE

[ WITH ] LOCATION = 設定で指定された名前付き外部ステージで 新しいまたは更新された データファイルが使用可能な場合に、Snowflakeが外部テーブルメタデータの自動更新のトリガーを有効にするかどうかを指定します。

注釈

  • ストレージの場所（つまり、Amazon S3またはMicrosoft Azure）のイベント通知を構成して、外部テーブルメタデータに読み込む新しいデータまたは更新されたデータが利用可能になったときにSnowflakeに通知する 必要があります 。詳細については、 Amazon S3に対する外部テーブルの自動更新 （S3）または Azure Blobストレージに対する外部テーブルの自動更新 （Azure）をご参照ください。

  • 現在、メタデータを自動的に更新する機能は、Google Cloud Storageステージを参照する外部テーブルでは使用できません。

    回避策として、 データファイルをステージングするためのベストプラクティス に従うとともに、欠落したファイルを登録するために、 ALTER EXTERNAL TABLE ... REFRESH ステートメントを定期的に実行するようにお勧めします。満足のいくパフォーマンスを得るために、 ALTER EXTERNAL TABLE で選択的パスプレフィックスを使用して、リストと既存登録の有無を確認する必要のあるファイル数を減らすようにお勧めします（例: ボリュームに応じて、 バケット名/YYYY/MM/DD/ または バケット名/YYYY/MM/DD/HH/）。

TRUE

Snowflakeを使用すると、外部テーブルメタデータの自動更新をトリガーできます。

FALSE

Snowflakeは、外部テーブルメタデータの自動更新のトリガーを有効にしません。 ALTER EXTERNAL TABLE ... REFRESH を使用して、外部テーブルのメタデータを手動で定期的に更新し、メタデータをステージパスにあるファイルの現在のリストと同期する必要があります。

デフォルト: TRUE

ポリシー名

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

ADD ROW ACCESS POLICY <ポリシー名> ON (<列名> [ , ... ])

行アクセスポリシーをテーブルに追加します。

少なくとも1つの列名を指定する必要があります。追加の列は、各列名をコンマで区切って指定できます。

DROP ROW ACCESS POLICY <ポリシー名>

テーブルまたはビューから行アクセスポリシーをドロップします。

使用上の注意

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

  • 次のコマンドは、明示的なトランザクションで使用できます（ BEGIN ... COMMIT を使用）。

    • ALTER EXTERNAL TABLE ... REFRESH

    • ALTER EXTERNAL TABLE ... ADD FILES

    • ALTER EXTERNAL TABLE ... REMOVE FILES

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

  • 次の構文を使用して、外部テーブルの列を追加または削除します。

    列の追加
    ALTER TABLE <name> ADD COLUMN ( <col_name> <col_type> AS <expr> ) [, ...]
    列の名前の変更
    ALTER TABLE <name> RENAME COLUMN <col_name> to <new_col_name>
    列のドロップ
    ALTER TABLE <name> DROP COLUMN <col_name>

    注釈

    デフォルトの VALUE および METADATA$FILENAME 列はドロップできません。

    例については、 ALTER TABLE トピックをご参照ください。

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

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

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

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

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

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

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

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

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

例

参照されるデータファイルの変更に基づいて、外部テーブルのメタデータのセット全体を手動で更新します。

ALTER EXTERNAL TABLE exttable_json REFRESH;

最初の例に似ていますが、外部テーブルのメタデータのサブパスのみを手動で更新します。

CREATE OR REPLACE STAGE mystage
  URL='<cloud_platform>://twitter_feed/logs/'
  .. ;

-- Create the external table
-- 'daily' path includes paths in </YYYY/MM/DD/> format
CREATE OR REPLACE EXTERNAL TABLE daily_tweets
  WITH LOCATION = @twitter_feed/daily/;

-- Refresh the metadata for a single day of data files by date
ALTER EXTERNAL TABLE exttable_part REFRESH '2018/08/05/';

外部テーブルのメタデータにファイルの明示的なリストを追加します。

ALTER EXTERNAL TABLE exttable1 ADD FILES ('path1/sales4.json.gz', 'path1/sales5.json.gz');

外部テーブルメタデータからファイルの明示的なリストを削除します。

ALTER EXTERNAL TABLE exttable1 REMOVE FILES ('path1/sales4.json.gz', 'path1/sales5.json.gz');

明示的なトランザクションにある外部テーブルのメタデータの更新された2019年12月のログファイルを置き換えます。

BEGIN;

ALTER EXTERNAL TABLE extable1 REMOVE FILES ('2019/12/log1.json.gz');

ALTER EXTERNAL TABLE extable1 ADD FILES ('2019/12/log1.json.gz');

COMMIT;

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

alter external table t1
  add row access policy rap_t1 on (empl_id);

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

alter external table t1
  add row access policy rap_test2 on (cost, item);

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

alter external table t1
  drop row access policy rap_v1;

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

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