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 } ]

必須パラメーター¶

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

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

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

コピーするファイルがステージされているソースロケーションを指定します。

INTO と FROM パラメーターでは、

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

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

  注釈

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

  • INTO ... と FROM ... の値はリテラル定数にする必要があります。値を 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 権限も必要であることに注意してください。

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

セキュリティ保護可能なオブジェクト に対して 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 Platform Consoleを使用してディレクトリを作成すると、Googleはディレクトリblobを作成します。

    この問題を回避するには、 PATTERN オプションを使用してコピーするファイルを指定します。例については、 パターンの一致を使用してファイルをコピーする をご参照ください。

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

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

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

  • コンピューティング: ファイルのコピーは、Snowflakeが管理するコンピューティングリソースに依存します。Snowflakeの請求書の COPY FILES コマンドの項目には、クラウドサービスの料金は含まれません。ただし、 Snowflake消費テーブル で詳しく説明するように、コマンドを呼び出すとクラウドサービスの料金が発生する場合があります。

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

  注釈

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