COPY FILES¶

構文¶

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM @[<namespace>.]<stage_name>[/<path>/]
  [ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
  [ PATTERN = '<regex_pattern>' ]
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]

COPY FILES INTO @[<namespace>.]<stage_name>[/<path>/]
  FROM ( SELECT <existing_url> [ , <new_filename> ] FROM ... )
  [ DETAILED_OUTPUT = { TRUE | FALSE } ]

必須パラメーター¶

INTO @[namespace.]stage_name[/path/]

コピーされたファイルのターゲットロケーションを指定します。

• namespace は、内部ステージまたは外部ステージが存在するデータベースまたはスキーマで、 database_name.schema_name または schema_name の形式です。データベースとスキーマがユーザーセッション内で現在使用されている場合、名前空間は オプション です。それ以外の場合は必須です。

• path は、ソースステージまたはターゲットステージの特定の場所からコピーするファイルのセットを指定するクラウドのストレージの場所にある、大文字と小文字を区別するオプションのパスです。クラウドストレージサービスによっては、パスを プレフィックス または フォルダー と呼ぶ場合があります。

注釈

• ターゲットパス名またはソースパス名に特殊文字やスペースが含まれている場合は、 INTO ... 値を一重引用符で囲む必要があります。

• INTO ... の値はリテラル定数にする必要があります。値を SQL 変数 にすることはできません。

オプションのパラメーター¶

FILES = ( 'file_name' [ , 'file_name' ... ] )

コピーするファイル名をコンマ区切りで1つ以上指定します。ファイルは、コマンドで指定したソースロケーションにあらかじめステージされている必要があります。Snowflakeは、見つからない指定されたファイルをスキップします。

最大1000個のファイル名を指定できます。

クエリからのファイルのコピーは、このオプションをサポートしていません。代わりに、クエリを使用してファイル名リストを提供します。

注釈

外部ステージのファイルパスを設定するために、Snowflakeはステージ定義にある URL をリスト内の各ファイル名の前に付加します。

しかし、Snowflakeは、パスとファイル名の間に区切り文字を挿入しません。ステージ定義の URL 末尾、または FILES リストにある各ファイル名の先頭のいずれかに区切り文字（/）を明示的に含める必要があります。

PATTERN = 'regex_pattern'

コピーするファイルのリストをフィルターするための正規表現パターンを指定します。このコマンドは、 FROM 句のストレージの場所全体に正規表現を適用します。

クエリからのファイルのコピーは、このオプションをサポートしていません。代わりに、パターンに一致するようにクエリを使用します。

Tip

最高のパフォーマンスを得るために、多数のファイルをフィルターするパターンは避けてください。

DETAILED_OUTPUT = { TRUE | FALSE }

コマンド出力が、コピー操作の結果を要約するか、コピーされた各ファイルをリストするかを指定します。

値:

• TRUE の場合、出力にはターゲットロケーションにコピーされた各ファイルの行が含まれます。file という名前の単一列には、コピーされた各ファイルのターゲットパス（該当する場合）とファイル名が含まれます。

• FALSE の場合、出力はコピーされたファイルの数を含む単一行になります。

デフォルト:

TRUE

アクセス制御の要件¶

この SQL コマンドの実行に使用される ロール には、少なくとも次の 権限 が必要です（ソースおよびターゲットロケーションによる）。

スキーマ内のオブジェクトに対して操作を実行するには、親データベースとスキーマに対する USAGE 権限が必要です。スキーマに対する 任意の権限を付与されたロールは、そのロールがスキーマを解決できることに注意してください。たとえば、スキーマに対するCREATE権限を付与されたロールは、そのスキーマにオブジェクトを作成できますが、そのスキーマに対するUSAGE*も*付与されている必要はありません。

指定された権限のセットを使用してカスタムロールを作成する手順については、 カスタムロールの作成 をご参照ください。

セキュリティ保護可能なオブジェクト に対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、 アクセス制御の概要 をご参照ください。

使用上の注意¶

• このコマンドは、次のアクションをサポートしていません。

  • テーブル ステージへの、またはそのテーブルからのファイルのコピー。

  • ステージをソースとして使用する場合は、 ユーザー ステージへ、またはそのステージからファイルをコピーします。

  • 取得する前に復元が必要な、アーカイブクラウドストレージクラスにあるデータのコピー。これらのアーカイブストレージクラスには、Amazon S3 Glacier Flexible Retrieval、Glacier Deep Archive、またはMicrosoft Azure Archive Storageが含まれます。

  • 5GB より大きいファイルのコピー。

• このコマンドを実行する際の注意事項:

  • COPY FILES ステートメントは、ターゲットロケーションにある、名前が一致する既存のファイルをすべて上書きします。このコマンドは、 コピーされたファイル名と一致しない既存のファイルを削除 しません。

  • ファイルコピー操作が失敗した場合、Snowflakeは自動クリーンアップを実行しません。

  • Google Cloud Storageからのファイルのコピー: 外部ステージのオブジェクトリストに1つ以上のディレクトリblobが含まれていると、 COPY FILES ステートメントが失敗する可能性があります。 ディレクトリblob は、スラッシュ文字（/）で終わるパスです。以下の LIST @<stage> の出力例では、 my_gcs_stage/load/ はディレクトリblobです。

    +---------------------------------------+------+----------------------------------+-------------------------------+
    | name                                  | size | md5                              | last_modified                 |
    |---------------------------------------+------+----------------------------------+-------------------------------|
    | my_gcs_stage/load/                    |  12  | 12348f18bcb35e7b6b628ca12345678c | Mon, 11 Aug 2022 16:57:43 GMT |
    | my_gcs_stage/load/data_0_0_0.csv.gz   |  147 | 9765daba007a643bdff4eae10d43218y | Mon, 11 Aug 2022 18:13:07 GMT |
    +---------------------------------------+------+----------------------------------+-------------------------------+
    

    Google Cloudコンソールを使用してディレクトリを作成すると、Googleはディレクトリblobを作成します。

    この問題を回避し、コピーするファイルを指定するには、 PATTERN オプション（ステージからコピーする場合）または FROM オプション（クエリからコピーする場合）を使用します。

    例については、 パターンの一致を使用してファイルをコピーする をご参照ください。

  • Snowflakeは、Amazon S3およびGoogle Cloud Storageへのアップロード時にマルチパートアップロードを使用します。不完全なアップロードが蓄積されないようにするには、ライフサイクルルールを設定することを推奨します。手順については、Amazon S3 または Google Cloud Storage ドキュメントをご参照ください。

• COPY FILES コマンドには、データ転送とコンピューティングコストがかかります。

  • データ転送: クラウドプロバイダーは、各自のネットワークから転送されたデータ分に課金する場合があります。これらの費用を回収するため、Snowflakeは、Snowflakeの内部ステージから、異なる リージョン または異なるクラウドプロバイダーの外部ステージにファイルをコピーする際に、バイトごとの手数料を請求します。Snowflakeでは、データのイングレス（外部ステージから内部ステージにファイルをコピーする場合など）には課金されません。

    データ転送請求の詳細については、 データ転送のコストについて をご参照ください。

  • コンピューティング: COPY FILES は サーバーレス 機能で、仮想ウェアハウスを必要としません。Snowflakeの請求書の COPY FILES コマンドの項目には、クラウドサービスの料金は含まれません。

    コンピューティングリソースの請求の詳細については、 コンピューティングコストについて をご参照ください。

  注釈

  Native Appsやワークシートなど、一部のSnowflake機能では COPY FILES の料金が発生します。その結果、 COPY FILES コマンドを実行していなくても、 COPY FILES の料金が表示される場合があります。これらの料金の詳細については、 Snowflakeサポート にお問い合わせください。

• Snowflakeは、このコマンドのファイルコピー履歴を維持しません。

例¶

COPY FILES
  INTO @trg_stage
  FROM @src_stage;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  FILES = ('file1.csv', 'file2.csv');

COPY FILES
  INTO @trg_stage/trg_path/
  FROM @src_stage/src_path/;

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*/.*/.*[.]csv[.]gz';

COPY FILES
  INTO @trg_stage
  FROM @src_stage
  PATTERN='.*sales.*[.]csv';

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt');

COPY FILES
  INTO @trg_stage
  FROM (SELECT '@src_stage/file.txt', 'new_filename.txt');

-- Create a table with URLs
CREATE TABLE urls(src_file STRING, trg_file STRING);
INSERT INTO urls VALUES ('@src_stage/file.txt', 'new_filename.txt');

-- Insert additional URLs here
COPY FILES
  INTO @trg_stage
  FROM (SELECT src_file, trg_file FROM urls);

COPY FILES
  INTO @trg_stage
  FROM (SELECT src_file, trg_file FROM urls WHERE src_file LIKE '%file%');

COPY FILES
  INTO @trg_stage
  FROM (SELECT relative_path FROM directory(@src_stage) WHERE relative_path LIKE '%.txt');