ディレクトリテーブルの管理

このトピックでは、ディレクトリテーブルを使用して外部ステージまたは内部ステージを作成および管理する方法について説明します。

このトピックの内容:

ディレクトリテーブルのメタデータ自動更新

ディレクトリテーブルのメタデータは、クラウドストレージサービスのイベントメッセージングサービスを使用して自動的に更新できます。

更新操作は、メタデータを外部ステージと外部パスの関連ファイルの最新セットと同期します。つまり、

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

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

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

自動的に更新されるディレクトリテーブルを使用してステージを作成する手順については、 ディレクトリテーブルの自動化されたメタデータ更新 をご参照ください。

注釈

メタデータを自動的に更新する機能は、外部クラウドストレージを参照する内部ステージのディレクトリテーブルでは使用できません。これらの型のステージでは、ディレクトリテーブルのメタデータを手動で更新する必要があります。手順については、 ディレクトリテーブルのメタデータ手動更新 (このトピック内)をご参照ください。

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

ディレクトリテーブルのメタデータ手動更新

このセクションでは、ディレクトリテーブルを階層化してステージングされたファイルに関するメタデータを保存するステージを(CREATE STAGE を使用して)作成する手順について説明します。この手順を使用して作成されたディレクトリテーブルでは、手動でメタデータを更新する必要があります。

現在、内部ステージのディレクトリテーブルでは、手動でメタデータを更新する必要があります。外部ステージにディレクトリテーブルを含めて、手動でメタデータを更新することもできます。メタデータ自動更新の詳細については、 ディレクトリテーブルのメタデータ自動更新 (このトピック内)をご参照ください。

注釈

外部ステージでメタデータを手動で更新すると、同時に実行されている自動更新操作はブロックされます。手動更新が完了すると、自動更新が再開されます。

ディレクトリテーブルを使用してステージを作成するための構文は、標準の外部ステージまたは内部ステージを作成する場合とほぼ同じです。オプションの DIRECTORY パラメーターを TRUE に設定します。

完全な構文とパラメーターの説明については、 CREATE STAGE をご参照ください。

構文

-- Internal stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <internal_stage_name>
  [ DIRECTORY = ( { ENABLE = TRUE | FALSE } ) ]
  [ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE') ]
  [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
  [ COPY_OPTIONS = ( copyOptions ) ]
  [ COMMENT = '<string_literal>' ]

-- External stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <external_stage_name>
      <cloud_storage_access_settings>
    [ DIRECTORY = ( { ENABLE = TRUE | FALSE } ) ]
    [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
    [ COPY_OPTIONS = ( copyOptions ) ]
    [ COMMENT = '<string_literal>' ]
Copy

条件:

ENABLE = TRUE | FALSE

ディレクトリテーブルをステージに追加するかどうかを指定します。値が TRUE の場合は、ステージとともにディレクトリテーブルが作成されます。

デフォルト: FALSE

[ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE') ]

ステージに格納されているすべてのファイルでサポートされている暗号化の型を指定します。

TYPE = ...

使用される暗号化タイプを指定します。可能な値は次のとおりです。

  • SNOWFLAKE_FULL: クライアント側の暗号化。ファイルは、クライアントが PUT を使用して内部ステージにアップロードするときに暗号化されます。

  • SNOWFLAKE_SSE: サーバー側の暗号化。ファイルは、ステージに着信した時に暗号化されます。

    ステージングされたファイルに対して事前署名されたURLsをクエリする場合は、サーバー側の暗号化を指定します。

    ステージ内のファイルがクライアント側で暗号化されている場合、ユーザーは暗号化キーにアクセスせずにステージングされたファイルを読み取ることはできません。

    サーバー側の暗号化のみを使用する内部の名前付きステージの詳細については、 CREATE STAGE をご参照ください。

デフォルト: SNOWFLAKE_FULL

使用上の注意

  • ディレクトリテーブルを使用してステージを作成した後、 ALTER STAGE ... REFRESH を実行して、ディレクトリテーブルのメタデータを手動で更新する 必要 があります。

ディレクトリテーブルを含む mystage という名前の内部ステージを作成します。ステージは myformat という名前のファイル形式を参照します。

CREATE STAGE mystage
  DIRECTORY = (ENABLE = TRUE)
  FILE_FORMAT = myformat;
Copy

ディレクトリテーブルを含む mystage という名前の外部ステージを作成します。ステージは、パスが filesload という名前のバケットまたはコンテナーを参照します。 my_storage_int ストレージ統合により、クラウドストレージの場所への安全なアクセスが提供されます。

注釈

URL 値の保存場所は、スラッシュ(/)で終わる必要があります。

Amazon S3

CREATE STAGE mystage
  URL='s3://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (ENABLE = TRUE);
Copy

Google Cloud Storage

CREATE STAGE mystage
  URL='gcs://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (ENABLE = TRUE);
Copy

Microsoft Azure

CREATE STAGE mystage
  URL='azure://myaccount.blob.core.windows.net/load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (ENABLE = TRUE);
Copy

ディレクトリテーブルの手動更新

ALTER STAGE コマンドを使用して、ディレクトリテーブルのメタデータを手動で更新します。

例:

ALTER STAGE mystage REFRESH;
Copy

ディレクトリテーブルからのファイル URLs の取得

ディレクトリテーブルをクエリします。

SELECT * FROM DIRECTORY( @<stage_name> )
Copy

条件:

stage_name

ディレクトリテーブルを含むステージの名前。

ステートメントとしての SELECT およびステートメント内の他の句の詳細については、 クエリ構文 をご参照ください。

出力

ディレクトリテーブルのクエリからの出力には、次の列が含まれる場合があります。

データ型

説明

RELATIVE_PATH

TEXT

ファイル URL を使用してアクセスするファイルへのパス。

SIZE

NUMBER

ファイルのサイズ(バイト単位)

LAST_MODIFIED

TIMESTAMP_LTZ

ステージでファイルが最後に更新されたときのタイムスタンプ。

MD5

HEX

ファイル用 MD5 チェックサム。

ETAG

HEX

ファイル用 ETag ヘッダー。

FILE_URL

TEXT

ファイルに対するSnowflakeホストファイルの URL。

ファイル URL の形式は次のとおりです。

https://<account_identifier>/api/files/<db_name>.<schema_name>.<stage_name>/<relative_path>
Copy

条件:

account_identifier

使用するステージのSnowflakeアカウントのホスト名。ホスト名は、アカウントロケーター(Snowflakeが提供)で始まり、Snowflakeドメイン(snowflakecomputing.com)で終わります。

account_locator.snowflakecomputing.com

詳細については、 アカウント識別子 をご参照ください。

注釈

Business Critical アカウントの場合は、アカウントでSnowflakeサービスへのプライベート接続が有効になっていなくても、 snowflakecomputing.comprivatelink.snowflakecomputing.com)の直前の URL に privatelink セグメントが追加されます。

db_name

ファイルが配置されているステージを含むデータベースの名前。

schema_name

ファイルが配置されているステージを含むスキーマの名前。

stage_name

ファイルが配置されているステージの名前。

relative_path

ファイル URL を使用してアクセスするファイルへのパス。

使用上の注意

  • 内部ステージからダウンロードしたファイルが破損している場合は、ステージに ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE') が設定されていることをステージの作成者で確認してください。

mystage という名前のステージのディレクトリテーブル内にあるすべてのメタデータ列を取得します。

SELECT * FROM DIRECTORY(@mystage);
Copy

同じディレクトリテーブルから FILE_URL 列の値を返します。サイズが100 Kバイトより大きいファイルの場合にのみファイル URLs を返します。

SELECT FILE_URL FROM DIRECTORY(@mystage) WHERE SIZE > 100000;
Copy

同じディレクトリテーブルから FILE_URL 列の値を返します。コンマ区切りの値ファイルの場合にのみ、ファイル URLs を返します。

SELECT FILE_URL FROM DIRECTORY(@mystage) WHERE RELATIVE_PATH ILIKE '%.csv';
Copy

ディレクトリテーブルのストリーム

ディレクトリテーブルの標準(つまり、デルタ)ストリームは、参照されたクラウドストレージの場所で追加またはドロップされたファイルを追跡します。SQL コマンドの構文と例については、 CREATE STREAM をご参照ください。