カテゴリ：: テーブル、ビュー、シーケンス 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>'

パラメーター¶

name

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

REFRESH [ 'relative-path' ]

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

パス内の新しいファイルがテーブルメタデータに追加されます。
パス内のファイルへの変更は、テーブルメタデータで更新されます。
パス内になくなったファイルは、テーブルメタデータから削除されます。

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

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

注釈

オブジェクト所有者がパーティションを手動で追加した場合（つまり、 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に通知する必要があります。詳細については、ご使用のクラウドストレージサービスの手順をご参照ください。
- Amazon S3
  
  Amazon S3に対する外部テーブルの自動更新
- Google Cloud Storage
  
  Google Cloud Storageの外部テーブルの自動更新
- Microsoft Azure
  
  Azure Blobストレージに対する外部テーブルの自動更新
現在、メタデータを自動的に更新する機能は、Google Cloud Storageステージを参照する外部テーブルでは使用できません。

回避策として、データファイルをステージングするためのベストプラクティスに従うとともに、欠落したファイルを登録するために、 ALTER EXTERNAL TABLE ... REFRESH ステートメントを定期的に実行するようにお勧めします。満足のいくパフォーマンスを得るために、 ALTER EXTERNAL TABLE で選択的パスプレフィックスを使用して、リストと既存登録の有無を確認する必要のあるファイル数を減らすようにお勧めします（例: ボリュームに応じて、 bucket_name/YYYY/MM/DD/ または bucket_name/YYYY/MM/DD/HH/）。
オブジェクト所有者がパーティションを手動で追加した場合（つまり、 PARTITION_TYPE = USER_SPECIFIED の場合）、このパラメーターは、パーティションされた外部テーブルではサポートされていません。

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

デフォルト: TRUE

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

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

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

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

UNSET

TAG tag_name [ , tag_name ... ]

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

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

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

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

注釈

ユーザー指定のパーティション列名の最大長は32文字です。

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

DROP PARTITION LOCATION '<path>'

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

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

アクセス制御の要件¶

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

権限	オブジェクト	メモ
OWNERSHIP	外部テーブル	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 アクションを実行するためのロールと権限付与に関する一般的な情報については、 Snowflakeのアクセス制御をご参照ください。

使用上の注意¶

このコマンドを実行できるのは、外部テーブルの所有者（つまり、外部テーブルに対する 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は、外部テーブルのメタデータからパーティションを削除します。この操作では、指定された場所にあるすべてのデータファイルもメタデータから削除されます。