カテゴリ：

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

ALTER EXTERNAL TABLE

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

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

CREATE EXTERNAL TABLE、 DROP EXTERNAL TABLE、 SHOW EXTERNAL TABLES、 DESCRIBE EXTERNAL TABLE

このトピックの内容:

構文

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

ALTER EXTERNAL TABLE [ IF EXISTS ] <name> UNSET
  TAG <tag_name> [ , <tag_name> ... ]

手動で追加および削除されたパーティション

ALTER EXTERNAL TABLE <name> [ IF EXISTS ] ADD PARTITION ( <part_col_name> = '<string>' [ , <part_col_name> = '<string>' ] ) LOCATION '<path>'

ALTER EXTERNAL TABLE <name> [ IF EXISTS ] DROP PARTITION LOCATION '<path>'

パラメーター

名前

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

REFRESH [ '相対サブパス' ]

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

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

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

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

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

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

注釈

  • オブジェクト所有者がパーティションを手動で追加した場合（つまり、 PARTITION_TYPE = USER_SPECIFIED の場合）、このパラメーターは、パーティションされた外部テーブルではサポートされて いません。

  • TABLE_FORMAT = DELTA が外部テーブルで設定される場合、 REFRESH は、データファイルの特定のサブセットに対するメタデータを更新する相対パスをサポート しません。

ADD FILES

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

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

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

オブジェクト所有者がパーティションを手動で追加した場合（つまり、 PARTITION_TYPE = USER_SPECIFIED の場合）、このパラメーターは、パーティションされた外部テーブルではサポートされて いません。

REMOVE FILES

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

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

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

オブジェクト所有者がパーティションを手動で追加した場合（つまり、 PARTITION_TYPE = USER_SPECIFIED の場合）、このパラメーターは、パーティションされた外部テーブルではサポートされて いません。

SET ...

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

AUTO_REFRESH = TRUE | FALSE

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

注釈

  • ストレージの場所のイベント通知を構成して、外部テーブルメタデータに読み込む新しいデータまたは更新されたデータが利用可能になったときに、Snowflakeに通知する必要が あります。詳細については、ご使用のクラウドストレージサービスの手順をご参照ください。

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

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

  • オブジェクト所有者がパーティションを手動で追加した場合（つまり、 PARTITION_TYPE = USER_SPECIFIED の場合）、このパラメーターは、パーティションされた外部テーブルではサポートされて いません。

TRUE

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

FALSE

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

デフォルト: TRUE

TAG タグ名 = 'タグ値' [ , タグ名 = 'タグ値' , ... ]

タグ 名（つまり、キー）とタグ値を指定します。

タグ値は常に文字列であり、タグ値の最大文字数は256です。オブジェクトに設定できる 一意の タグキーの最大数は20です。

注釈

テーブルまたはビューとその列の場合、設定できる一意のタグキーの総数は20です。

たとえば、テーブル内にある単一列の1列に10個の一意のタグキーが設定されている場合、Snowflakeでは、その列、テーブル内にある他の列、テーブル自体、またはテーブルとその列をいくつか組み合わせたものに10個の一意のタグキーを追加で設定できます。一意のタグキーが20の制限に達すると、テーブルまたはその列に追加のタグキーを設定できなくなります。

UNSET

  • TAG タグ名 [ , タグ名 ... ]

手動で追加および削除されたパーティション

外部テーブルのパーティションタイプがユーザー指定（つまり、 PARTITION_TYPE = USER_SPECIFIED）の場合は、次のパラメーター使用してパーティションを追加または削除します。

ADD PARTITION ( <part_col_name> = '<string>' [ , <part_col_name> = '<string>' , ... ] ) LOCATION '<path>'

指定された場所（つまり、パス）にある外部テーブル用に定義された、1つ以上のパーティション列のパーティションを手動で追加します。

パーティションを追加すると、その場所にある新しいファイルまたは更新されたファイルも外部テーブルのメタデータに追加されます。

DROP PARTITION LOCATION '<path>'

指定された場所（つまり、パス）にある、すべてのパーティションを手動でドロップします。

パーティションを削除すると、その場所にあるすべてのファイルが外部テーブルのメタデータからも削除されます。

使用上の注意

  • このコマンドを実行できるのは、外部テーブルの所有者（つまり、外部テーブルに対する 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 トピックをご参照ください。

  • 外部テーブルに行アクセスポリシーを追加およびドロップするには、 ALTER TABLE コマンドを使用します。

  • メタデータについて。

    注意

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

例

メタデータを手動で更新する

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

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;

パーティションを手動で追加または削除する

パーティション列の指定された場所に、パーティションを手動で追加します。

ALTER EXTERNAL TABLE et2 ADD PARTITION(col1='2022-01-24', col2='a', col3='12') LOCATION '2022/01';

Snowflakeは、外部テーブルのメタデータにパーティションを追加します。この操作では、指定された場所にある新しいデータファイルもメタデータに追加されます。

指定した場所から、手動でパーティションを削除します。

ALTER EXTERNAL TABLE et2 DROP PARTITION LOCATION '2022/01';

Snowflakeは、外部テーブルのメタデータからパーティションを削除します。この操作では、指定された場所にあるすべてのデータファイルもメタデータから削除されます。

⇧
最上部に戻る