ALTER EXTERNAL TABLE

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

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

CREATE EXTERNAL TABLEDROP EXTERNAL TABLESHOW EXTERNAL TABLESDESCRIBE 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 }
Copy

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

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>'
Copy

パラメーター

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に通知する必要が あります。詳細については、ご使用のクラウドストレージサービスの手順をご参照ください。

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

  • このパラメーターを TRUE に設定することは、 S3互換の外部ステージ に格納されたデータファイルを参照する外部テーブルではサポート されません

TRUE

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

FALSE

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

デフォルト: TRUE

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

外部テーブルのパーティションタイプがユーザー指定(つまり、 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 アクションを実行するためのロールと権限付与に関する一般的な情報については、 アクセス制御の概要 をご参照ください。

使用上の注意

  • このコマンドを実行できるのは、外部テーブルの所有者(つまり、外部テーブルに対する 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> ) [, ...]
    
    Copy
    列の名前の変更:
    ALTER TABLE <name> RENAME COLUMN <col_name> to <new_col_name>
    
    Copy
    列のドロップ:
    ALTER TABLE <name> DROP COLUMN <col_name>
    
    Copy

    注釈

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

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

  • 外部テーブルに対して、行アクセスポリシーを追加またはドロップする、あるいはタグを設定または設定解除するには、 ALTER TABLE コマンドを使用します。

    しかし、行アクセスポリシーとタグを持つ外部テーブルを作成することはできます。 CREATE EXTERNAL TABLE をご参照ください。

  • メタデータについて。

    注意

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

メタデータを手動でリフレッシュする

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

ALTER EXTERNAL TABLE exttable_json REFRESH;
Copy

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

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/';
Copy

ファイルを手動で追加または削除する

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

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

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

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

明示的なトランザクションにある外部テーブルのメタデータの更新された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;
Copy

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

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

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

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

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

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

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