カテゴリ:

DML コマンド - データのアンロード

COPY INTO <場所>

テーブル(またはクエリ)から次のいずれかの場所にある1つ以上のファイルにデータをアンロードします。

  • 内部ステージ(またはテーブル/ユーザーステージ)という名前。その後、ファイルは GET コマンドを使用してステージ/場所からダウンロードできます。

  • 外部の場所を参照する名前付きの外部ステージ(Amazon S3、Google Cloud Storage、またはMicrosoft Azure)。

  • 外部の場所(Amazon S3、Google Cloud Storage、またはMicrosoft Azure)。

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

COPY INTO <テーブル>

このトピックの内容:

構文

COPY INTO { internalStage | externalStage | externalLocation }
     FROM { [<namespace>.]<table_name> | ( <query> ) }
[ PARTITION BY <expr> ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
                    TYPE = { CSV | JSON | PARQUET } [ formatTypeOptions ] } ) ]
[ copyOptions ]
[ HEADER ]

条件:

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>[/<path>]
  | @~[/<path>]
externalStage ::=
  @[<namespace>.]<ext_stage_name>[/<path>]
externalLocation (for Amazon S3) ::=
  's3://<bucket>[/<path>]'
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( {  { AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' [ AWS_TOKEN = '<string>' ] } } ) } ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] |
                   [ TYPE = 'AWS_SSE_S3' ] |
                   [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] |
                   [ TYPE = NONE ] ) ]
externalLocation (for Google Cloud Storage) ::=
  'gcs://<bucket>[/<path>]'
  [ STORAGE_INTEGRATION = <integration_name> ]
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = NONE ] ) ]
externalLocation (for Microsoft Azure) ::=
  'azure://<account>.blob.core.windows.net/<container>[/<path>]'
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( [ AZURE_SAS_TOKEN = <string> ] ) } ]
  [ ENCRYPTION = ( [ TYPE = { 'AZURE_CSE' | NONE } ] [ MASTER_KEY = '<string>' ] ) ]
formatTypeOptions ::=
-- If FILE_FORMAT = ( TYPE = CSV ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     RECORD_DELIMITER = '<character>' | NONE
     FIELD_DELIMITER = '<character>' | NONE
     FILE_EXTENSION = '<string>'
     ESCAPE = '<character>' | NONE
     ESCAPE_UNENCLOSED_FIELD = '<character>' | NONE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     FIELD_OPTIONALLY_ENCLOSED_BY = '<character>' | NONE
     NULL_IF = ( '<string1>' [ , '<string2>' , ... ] )
     EMPTY_FIELD_AS_NULL = TRUE | FALSE
-- If FILE_FORMAT = ( TYPE = JSON ... )
     COMPRESSION = AUTO | GZIP | BZ2 | DEFLATE | RAW_DEFLATE | NONE
     FILE_EXTENSION = '<string>'
-- If FILE_FORMAT = ( TYPE = PARQUET ... )
     COMPRESSION = AUTO | SNAPPY | NONE
     SNAPPY_COMPRESSION = TRUE | FALSE
copyOptions ::=
     OVERWRITE = TRUE | FALSE
     SINGLE = TRUE | FALSE
     MAX_FILE_SIZE = <num>
     INCLUDE_QUERY_ID = TRUE | FALSE
     DETAILED_OUTPUT = TRUE | FALSE

必須パラメーター

INTO ...

データファイルがアンロードされる内部または外部の場所を指定します。

@[名前空間.]内部ステージ名[/パス]

指定された名前の内部ステージにファイルがアンロードされます。

@[名前空間.]外部ステージ名[/パス]

指定された名前の外部ステージにファイルがアンロードされます。

@[名前空間.]%テーブル名[/パス]

ファイルは、指定されたテーブルのステージにアンロードされます。

@~[/パス]

ファイルは、現在のユーザーのステージにアンロードされます。

's3://バケット[/パス]'

ファイルは、指定された外部の場所(S3バケット)にアンロードされます。追加のパラメーターが必要になる場合があります。詳細については、 追加のクラウドプロバイダーパラメーター (このトピック内)をご参照ください。 . . 政府リージョンなど、非公開 AWS リージョンのS3バケットはサポートされていないことに注意してください。

'azure://アカウント.blob.core.windows.net/コンテナ[/パス]'

ファイルは、指定された外部の場所(Azureコンテナー)にアンロードされます。追加のパラメーターが必要になる場合があります。詳細については、 追加のクラウドプロバイダーパラメーター (このトピック内)をご参照ください。

条件:

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

  • オプションの パス パラメーターは、アンロードされたデータを含むファイルのフォルダーとファイル名のプレフィックスを指定します。ファイル名のプレフィックスが パス に含まれていない場合、生成されたデータファイルのファイル名には data_ のプレフィックスが付きます。

    「パス」は名前のリテラルプレフィックスであるため、 /.//../ などの相対パス修飾子は文字どおりに解釈されます。例:

    -- S3 bucket
    COPY INTO 's3://mybucket/./../a.csv' FROM mytable;
    
    -- Azure container
    COPY INTO 'azure://myaccount.blob.core.windows.net/mycontainer/./../a.csv' FROM mytable;
    

    これらのCOPYステートメントで、Snowflakeは、保管場所に文字通り ./../a.csv という名前のファイルを作成します。

注釈

内部または外部のステージ、またはパス名にスペースなどの特殊文字が含まれている場合は、 INTO ... 文字列を一重引用符で囲みます。

FROM ...

アンロードするデータのソースを指定します。これは、テーブルまたはクエリのいずれかです。

[名前空間.]テーブル名

データのアンロード元のテーブルの名前を指定します。

名前空間は、オプションで、テーブルが存在するデータベースまたはスキーマ、あるいはその両方を データベース名.スキーマ名 または スキーマ名 の形式で指定します。ユーザーセッション内でデータベースとスキーマが現在使用されている場合は オプション です。それ以外の場合は必須です。

( クエリ )

SELECT ファイルにアンロードするデータを返すステートメント。クエリで LIMIT / FETCH 句を指定することにより、返される行の数を制限できます。

注釈

CAST、 :: 関数を使用して列値をデータ型にキャストする場合は、データ型がすべての列値をサポートしていることを確認してください。指定されたデータ型に対して長すぎる値は切り捨てられる可能性があります。

追加のクラウドプロバイダーパラメーター

STORAGE_INTEGRATION = 統合名 または . CREDENTIALS = ( クラウド固有の認証情報 )

アドホック COPY ステートメント(名前付き外部ステージを参照しないステートメント)で使用します。 クラウドプロバイダーに接続し、アンロードされたファイルがステージングされるプライベートストレージコンテナーにアクセスするためのセキュリティ認証情報を指定します。

外部のプライベートクラウドストレージの場所にアンロードする場合にのみ必要です。パブリックバケット/コンテナーには必要ありません

Amazon S3

STORAGE_INTEGRATION = 統合名

外部クラウドストレージの認証責任をSnowflake IDおよびアクセス管理(IAM)エンティティに委任するために使用されるストレージ統合の名前を指定します。詳細については、 CREATE STORAGE INTEGRATION をご参照ください。

注釈

ストレージ統合の使用を強くお勧めします。このオプションにより、ステージの作成時またはデータのロード時に CREDENTIALS パラメーターを使用してクラウドストレージの認証情報を提供する必要がなくなります。

CREDENTIALS = ( AWS_KEY_ID = '文字列' AWS_SECRET_KEY = '文字列' [ AWS_TOKEN = '文字列' ] ) または . CREDENTIALS = ( AWS_ROLE = '文字列' )

AWS に接続し、アンロードされたファイルがステージングされるプライベートS3バケットにアクセスするためのセキュリティ認証情報を指定します。詳細については、 Amazon S3へのセキュアアクセスの構成 をご参照ください。

指定する認証情報は、バケットのSnowflakeアクセス許可を AWS IAM (識別およびアクセス管理)ユーザーまたはロールに関連付けたかどうかによって異なります。

  • IAM ユーザー: 一時的な IAM 認証情報が必要です。一時的な(別名「スコープ」)認証情報は AWS セキュリティトークンサービス(STS)によって生成され、3つのコンポーネントで構成されます。

    • AWS_KEY_ID

    • AWS_SECRET_KEY

    • AWS_TOKEN

    プライベートバケットにアクセスするには、3つすべてが 必要 です。指定された期間が経過すると、仮認証情報は期限切れになり、使用できなくなります。そうすると、有効な一時的な認証情報の新しいセットを生成する必要があります。

    重要

    COPY コマンドには、複雑な構文と認証情報などの機密情報が含まれます。さらに、これらは頻繁に実行され、スクリプトまたはワークシートに保存されることが多いため、機密情報が誤って公開される可能性があります。 COPY コマンドを使用すると、永続的な(別名「長期」)認証情報を使用できます。ただし、セキュリティ上の理由から、 永久 認証情報を COPY コマンドで使用しないでください。代わりに、一時的な認証情報を使用します。

    永続的な認証情報を使用する必要がある場合は、 外部ステージ を使用します。認証情報が1回入力され、安全に保存されるため、暴露の可能性が最小限に抑えられます。

  • IAM ロール: セキュリティ認証情報とアクセスキーを省略し、代わりに AWS_ROLE を使用してロールを識別し、 AWS ロール ARN (Amazonリソース名)を指定します。

    重要

    AWS IAM ロールを使用してプライベートS3バケットにアクセスし、データをロードまたはアンロードする機能は廃止されました(つまり、サポートは将来のリリースで削除される予定)。この機能を使用する既存のS3ステージを変更して、代わりにストレージ統合オブジェクトを参照することを強くお勧めします。手順については、 オプション1:Amazon S3にアクセスするためのSnowflakeストレージ統合の構成 をご参照ください。

Google Cloud Storage

STORAGE_INTEGRATION = 統合名

外部クラウドストレージの認証責任をSnowflake IDおよびアクセス管理(IAM)エンティティに委任するために使用されるストレージ統合の名前を指定します。詳細については、 CREATE STORAGE INTEGRATION をご参照ください。

Microsoft Azure

STORAGE_INTEGRATION = 統合名

外部クラウドストレージの認証責任をSnowflake IDおよびアクセス管理(IAM)エンティティに委任するために使用されるストレージ統合の名前を指定します。詳細については、 CREATE STORAGE INTEGRATION をご参照ください。

注釈

ストレージ統合の使用を強くお勧めします。このオプションにより、ステージの作成時またはデータのロード時に CREDENTIALS パラメーターを使用してクラウドストレージの認証情報を提供する必要がなくなります。

CREDENTIALS = ( AZURE_SAS_TOKEN = '文字列' )

Azureに接続し、データを含むファイルがステージングされるプライベートコンテナーにアクセスするための SAS (共有アクセス署名)トークンを指定します。認証情報はAzureによって生成されます。

ENCRYPTION = ( クラウド固有の暗号化 )

アドホック COPY ステートメント(名前付き外部ステージを参照しないステートメント)で使用します。暗号化された保管場所のファイルにデータをアンロードする場合にのみ必要

Amazon S3

ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] | [ TYPE = 'AWS_SSE_S3' ] | [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] | [ TYPE = NONE ] )

TYPE = ...

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

  • AWS_CSE :クライアント側の暗号化( MASTER_KEY 値が必要)。現在、提供するクライアント側のマスターキーは対称キーのみです。 MASTER_KEY 値が指定されている場合、Snowflakeは TYPE = AWS_CSE と見なします(つまり、 MASTER_KEY 値が指定されている場合、 TYPE は不要です)。

  • AWS_SSE_S3 :追加の暗号化設定を必要としないサーバー側の暗号化。

  • AWS_SSE_KMS :オプションの KMS_KEY_ID 値を受け入れるサーバー側の暗号化。

暗号化タイプの詳細については、 クライアント側の暗号化 または サーバー側の暗号化 の AWS ドキュメントをご参照ください。

MASTER_KEY = '文字列'AWS_CSE 暗号化のみに適用)

バケット内のファイルの暗号化に使用されたクライアント側マスターキーを指定します。マスターキーは、Base64エンコード形式の128ビットまたは256ビットキーである必要があります。

KMS_KEY_ID = '文字列'AWS_SSE_KMS 暗号化のみに適用)

オプションで、バケットに アンロードされた ファイルの暗号化に使用する AWS KMS 管理キーの ID を指定します。値が指定されていない場合、デフォルトの KMS キー ID を使用して、アンロード時にファイルが暗号化されます。

この値はデータのロードでは無視されることに注意してください。

Google Cloud Storage

ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = NONE ] )

TYPE = ...

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

  • GCS_SSE_KMS :オプションの KMS_KEY_ID 値を受け入れるサーバー側の暗号化。

詳細については、Google Cloud Platformのドキュメントをご参照ください。

KMS_KEY_ID = '文字列'GCS_SSE_KMS 暗号化のみに適用)

オプションで、バケットに アンロード されるファイルの暗号化に使用する KMS 管理キーの ID を指定します。値が指定されていない場合、バケットに対して設定されているデフォルトの KMS キー ID を使用して、アンロード時にファイルが暗号化されます。

この値はデータのロードでは無視されることに注意してください。サービスアカウントにバケット内のデータを復号化するための十分な権限がある場合、ロード操作は成功するはずです。

Microsoft Azure

ENCRYPTION = ( [ TYPE = 'AZURE_CSE' | NONE ] [ MASTER_KEY = '文字列' ] )

TYPE = ...

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

  • AZURE_CSE :クライアント側の暗号化( MASTER_KEY 値が必要)。詳細については、Microsoft Azureのドキュメントの クライアント側の暗号化情報 をご参照ください。

  • NONE :暗号化なし。

MASTER_KEY = '文字列' ( AZURE_CSE 暗号化のみに適用)

ファイルの暗号化に使用されるクライアント側マスターキーを指定します。マスターキーは、Base64エンコード形式の128ビットまたは256ビットキーである必要があります。

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

PARTITION BY

アンロードされたテーブルの行を個別のファイルに分割するために使用される式を指定します。文字列に評価されるすべての SQL 式をサポートします。

アンロード操作は、パーティション式に基づいてテーブルの行を分割し、データ量とウェアハウス内のコンピューティングリソースに分散された並列操作の数に基づいて、作成するファイルの数を決定します。

ファイル名には、パーティション列の値が含まれます。各パーティションの個々のファイル名は、ユニバーサル一意識別子(UUID)で識別されます。UUID は、データファイルをアンロードするために使用される COPY ステートメントのクエリ ID です。

ご用心

COPY INTO <場所> ステートメントは、パーティション列の値をアンロードされたファイル名に書き込みます。機密性が高い可能性のある文字列値または整数値ではなく、日付やタイムスタンプなどの一般的なデータ型でデータをパーティション分割することを強くお勧めします。

顧客がサポートケースを作成する際に問題のデバッグを支援するため、Snowflakeが維持する内部ログにはファイル URLs が含まれていることに注意してください。その結果、 PARTITION BY 式で参照される列のデータも、間接的に内部ログに保存されます。これらのログは、展開リージョン外で処理される可能性があります。したがって、ベストプラクティスとして、 PARTITION BY 式には日付、タイムスタンプ、ブールデータ型のみを含めます。

アカウントの COPY INTO <場所> ステートメントで PARTITION BY パラメーターを無効にする場合は、 Snowflakeサポート にお問い合わせください。

Snowflakeは、データのアンロード操作をさらに制限するためにパラメーターのセットを提供します。

  • PREVENT_UNLOAD_TO_INLINE_URL は、外部クラウドストレージの場所にアドホックデータをアンロードする操作を禁止します(つまり、クラウドストレージ COPY を指定し、ステートメント内の設定に直接アクセスする、INTO URL <場所> ステートメント)。

  • PREVENT_UNLOAD_TO_INTERNAL_STAGES は、ユーザーステージ、テーブルステージ、名前付き内部ステージなど、 任意の 内部ステージにデータをアンロードする操作を禁止します。

例については、 アンロードされた行のParquetファイルへのパーティション分割 (このトピック内)をご参照ください。

注釈

  • 次のコピーオプションは、 PARTITION BY との組み合わせではサポートされていません。

    • OVERWRITE

    • SINGLE

    • INCLUDE_QUERY_ID

  • PARTITION BY 式が NULL と評価された場合、出力ファイル名のパーティションパスは _NULL_ (例: mystage/_NULL_/data_01234567-0123-1234-0000-000000001234_01_0_0.snappy.parquet)です。

  • タイプ PARQUET のファイルにアンロードする場合、

    • 並列実行スレッドによってアンロードされた小さなデータファイルは、 MAX_FILE_SIZE コピーオプションの値に可能な限り一致する単一のファイルに自動的にマージされます。

    • すべての行グループのサイズは128 MB です。行グループは、データを行に論理的に水平に分割したものです。行グループに対して保証されている物理構造はありません。行グループは、データセットの各列の列チャンクで構成されます。

    • アンロード操作は、 MAX_FILE_SIZE コピーオプション設定にできるだけ近いサイズのファイルを生成しようとします。このコピーオプションのデフォルト値は16 MB です。この動作は、Parquetファイルにデータをアンロードする場合のみに適用されることに注意してください。

  • アンロードされたデータファイルからパーティション式の列を省略するオプションはありません。

FILE_FORMAT = ( FORMAT_NAME = 'ファイル形式名' ) または . FILE_FORMAT = ( TYPE = CSV | JSON | PARQUET [ ... ] )

アンロードされたデータを含むデータファイルの形式を指定します。

FORMAT_NAME = 'ファイル形式名'

テーブルからデータをアンロードするために使用する既存の名前付きファイル形式を指定します。名前付きファイル形式により、データファイルの形式タイプ(CSV、 JSON、 PARQUET)およびその他の形式オプションが決まります。詳細については、 CREATE FILE FORMAT をご参照ください。

TYPE = CSV | JSON | PARQUET [ ... ]

テーブルからアンロードされるファイルのタイプを指定します。

形式タイプが指定されている場合、追加の形式固有のオプションを指定できます。詳細については、 形式タイプオプション (このトピック)をご参照ください。

注釈

  • JSON タイプ VARIANT の列(つまり、 JSON データを含む列)からデータをアンロードするためにのみ使用できます。

  • 現在、 VARIANT 列のネストされたデータはParquet形式で正常にアンロードできません。

copyOptions

アンロードされたデータの1つ以上のコピーオプションを指定します。詳細については、 コピーオプション (このトピック)をご参照ください。

HEADER = TRUE | FALSE

出力ファイルにテーブルの列見出しを含めるかどうかを指定します。

  • 出力ファイルにテーブルの列見出しを含めるには、このオプションを TRUE に設定します。

    COPY 操作がデータを複数のファイルにアンロードする場合、列見出しは すべて ファイルに含まれることに注意してください。

    Parquet形式でデータをアンロードするとき、テーブルの列名は出力ファイルに保持されます。

  • このオプションを FALSE に設定して、次の動作を指定します。

    CSV

    出力ファイルにテーブルの列見出しを含めないでください。

    Parquet

    出力ファイルに一般的な列見出し(例: col1col2 など)を含めます。

デフォルト: FALSE

形式タイプオプション(formatTypeOptions

指定したファイル形式タイプ(FILE_FORMAT = ( TYPE = ... ))に応じて、次の形式固有のオプションを1つ以上含めることができます(空白、コンマ、または改行で区切る)。

TYPE = CSV

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

指定された圧縮アルゴリズムを使用して、アンロードされたデータファイルを圧縮することを指定する文字列(定数)。

サポートされる値

メモ

AUTO

アンロードされたファイルは、デフォルトのgzipを使用して自動的に圧縮されます。

GZIP

BZ2

BROTLI

Brotliで圧縮されたファイルをロードするときには、指定する必要があります。

ZSTD

Zstandard v0.8(およびそれ以上)がサポートされています。

DEFLATE

アンロードされたファイルは、Deflateを使用して圧縮されます(zlibヘッダー、 RFC1950 を使用)。

RAW_DEFLATE

アンロードされたファイルは、生Deflateを使用して圧縮されます(ヘッダーなし、 RFC1951)。

NONE

アンロードされたファイルは圧縮されません。

デフォルト: AUTO

RECORD_DELIMITER = '文字' | NONE

アンロードされたファイルの記録を区切る、1つ以上のシングルバイトまたはマルチバイト文字。一般的なエスケープシーケンス、または次のシングルバイトまたはマルチバイト文字を受け入れます。

シングルバイト文字

8進値(\\ でプレフィックス)、または16進値(0x または \x でプレフィックス)を受け入れます。たとえば、アクサンシルコンフレックス(^)文字で区切られた記録の場合は、8進数(\\5e)または16進数(0x5e)の値を指定します。

マルチバイト文字

16進値(\x でプレフィックス)。たとえば、セント(¢)文字で区切られた記録の場合は、16進数(\xC2\xA2)の値を指定します。

RECORD_DELIMITER または FIELD_DELIMITER の区切り文字は、他のファイル形式オプション(例: FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb')向けとして区切り文字の部分文字列にすることはできません。

指定された区切り文字は、ランダムなバイトのシーケンスではなく、有効な UTF-8文字でなければなりません。区切り文字は最大20文字に制限されていることにも注意してください。

NONE の値も受け入れます。

デフォルト: 改行文字。「改行」は論理的であるため、 \r\n がWindowsプラットフォーム上のファイルの改行として理解されることに注意してください。

FIELD_DELIMITER = '文字' | NONE

アンロードされたファイルのフィールドを区切る、1つ以上のシングルバイトまたはマルチバイト文字。一般的なエスケープシーケンス、または次のシングルバイトまたはマルチバイト文字を受け入れます。

シングルバイト文字

8進値(\\ でプレフィックス)、または16進値(0x または \x でプレフィックス)を受け入れます。たとえば、アクサンシルコンフレックス(^)文字で区切られた記録の場合は、8進数(\\5e)または16進数(0x5e)の値を指定します。

マルチバイト文字

16進値(\x でプレフィックス)。たとえば、セント(¢)文字で区切られた記録の場合は、16進数(\xC2\xA2)の値を指定します。

RECORD_DELIMITER または FIELD_DELIMITER の区切り文字は、他のファイル形式オプション(例: FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb')向けとして区切り文字の部分文字列にすることはできません。

指定された区切り文字は、ランダムなバイトのシーケンスではなく、有効な UTF-8文字でなければなりません。区切り文字は最大20文字に制限されていることにも注意してください。

NONE の値も受け入れます。

デフォルト: コンマ(,

FILE_EXTENSION = '文字列' | NONE

ステージにアンロードされるファイルの拡張子を指定する文字列。拡張子を受け入れます。ユーザーは、目的のソフトウェアまたはサービスで読み取れる有効なファイル拡張子を指定する必要があります。

注釈

SINGLE コピーオプションが TRUE の場合、 COPY コマンドはデフォルトでファイル拡張子のないファイルをアンロードします。ファイル拡張子を指定するには、 内部ロケーション または 外部ロケーション パスにファイル名と拡張子を指定します。例:

copy into @stage/data.csv ...

デフォルト:null。ファイル拡張子は、 .csv[圧縮] などの形式タイプによって決定されます。 圧縮 は、 COMPRESSION が設定されている場合、圧縮方法によって追加される拡張子です。

DATE_FORMAT = '文字列' | AUTO

アンロードされたデータファイルの日付値の形式を定義する文字列。値が指定されていないか、 AUTO に設定されている場合、 DATE_OUTPUT_FORMAT パラメーターの値が使用されます。

デフォルト: AUTO

TIME_FORMAT = '文字列' | AUTO

アンロードされたデータファイルの時間値の形式を定義する文字列。値が指定されていないか、 AUTO に設定されている場合、 TIME_OUTPUT_FORMAT パラメーターの値が使用されます。

デフォルト: AUTO

TIMESTAMP_FORMAT = '文字列' | AUTO

アンロードされたデータファイルのタイムスタンプ値の形式を定義する文字列。値が指定されていないか、 AUTO に設定されている場合、 TIMESTAMP_OUTPUT_FORMAT パラメーターの値が使用されます。

デフォルト: AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

バイナリ出力のエンコード形式を定義する文字列(定数)。このオプションは、テーブルのバイナリ列からデータをアンロードするときに使用できます。

デフォルト: HEX

ESCAPE = '文字' | NONE
使用

データのロードとアンロード

定義

囲まれているフィールド値、または囲まれていないフィールド値のエスケープ文字として使用される単一の文字列。エスケープ文字は、文字シーケンス内の後続の文字に対して代替解釈を呼び出します。ESCAPE 文字を使用して、データ内の FIELD_OPTIONALLY_ENCLOSED_BY 文字のインスタンスをリテラルとして解釈できます。エスケープ文字は、データ内のそれ自体のインスタンスをエスケープするためにも使用できます。

一般的なエスケープシーケンス、8進数値、または16進数値を受け入れます。

FIELD_OPTIONALLY_ENCLOSED_BY を設定して、フィールドを囲むのに使用する文字を指定します。

このオプションが設定されている場合は、 ESCAPE_UNENCLOSED_FIELD のエスケープ文字セットが上書きされます。

デフォルト

NONE

ESCAPE_UNENCLOSED_FIELD = '文字' | NONE
使用

データのロードとアンロード

定義

囲まれていないフィールド値専用のエスケープ文字として使用される単一の文字列。エスケープ文字は、文字シーケンス内の後続の文字に対して代替解釈を呼び出します。ESCAPE 文字を使用して、データ内の FIELD_DELIMITER または RECORD_DELIMITER 文字のインスタンスをリテラルとして解釈できます。エスケープ文字は、データ内のそれ自体のインスタンスをエスケープするためにも使用できます。

一般的なエスケープシーケンス、8進数値、または16進数値を受け入れます。

ESCAPE が設定されている場合は、そのファイルオプションのエスケープ文字セットがこのオプションを上書きします。

デフォルト

バックスラッシュ(\\

FIELD_OPTIONALLY_ENCLOSED_BY = '文字' | NONE

文字列を囲むのに使用される文字。値は、 NONE、一重引用符(')、または二重引用符(")のいずれかです。一重引用符を使用するには、8進数または16進数表現(0x27)または二重引用符で囲まれたエスケープ('')を使用します。

フィールドにこの文字が含まれる場合、同じ文字を使用してエスケープします。例えば、値が二重引用符であり、フィールドに文字列 A "B" C が含まれる場合、二重引用符を次のようにエスケープします。

A ""B"" C

デフォルト: NONE

NULL_IF = ( '文字列1' [ , '文字列2' ... ] )

SQL NULLからの変換に使用される文字列。Snowflakeは、 SQL NULL 値をリストの最初の値に変換します。

デフォルト: \\N (つまり、NULL、 ESCAPE_UNENCLOSED_FIELD=\\ と想定)

EMPTY_FIELD_AS_NULL = TRUE | FALSE

FIELD_OPTIONALLY_ENCLOSED_BY と組み合わせて使用します。 FIELD_OPTIONALLY_ENCLOSED_BY = NONE の場合、 EMPTY_FIELD_AS_NULL = FALSE を設定すると、フィールド値を囲む引用符なしで空の文字列値にアンロードするように、テーブル内の空の文字列を指定します。

TRUE に設定した場合、 FIELD_OPTIONALLY_ENCLOSED_BY は文字列を囲む文字を指定する必要があります。

デフォルト: TRUE

TYPE = JSON

COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE

文字列(定数)。指定された圧縮アルゴリズムを使用してデータファイルを圧縮します。

サポートされる値

メモ

AUTO

アンロードされたファイルは、デフォルトのgzipを使用して自動的に圧縮されます。

GZIP

BZ2

BROTLI

ZSTD

DEFLATE

アンロードされたファイルは、Deflateを使用して圧縮されます(zlibヘッダー、 RFC1950 を使用)。

RAW_DEFLATE

アンロードされたファイルは、生Deflateを使用して圧縮されます(ヘッダーなし、 RFC1951)。

NONE

アンロードされたファイルは圧縮されません。

デフォルト: AUTO

FILE_EXTENSION = '文字列' | NONE

ステージにアンロードされるファイルの拡張子を指定する文字列。拡張子を受け入れます。ユーザーは、目的のソフトウェアまたはサービスで読み取れる有効なファイル拡張子を指定する必要があります。

デフォルト:null。ファイル拡張子は形式タイプ(例: .csv[圧縮])によって決まります。 COMPRESSION が設定されている場合、 圧縮 は圧縮方法によって追加された拡張子です。

TYPE = PARQUET

COMPRESSION = AUTO | LZO | SNAPPY | NONE

文字列(定数)。指定された圧縮アルゴリズムを使用してデータファイルを圧縮します。

サポートされる値

メモ

AUTO

ファイルは、デフォルトの圧縮アルゴリズムであるSnappyを使用して圧縮されます。

LZO

デフォルトでは、Snappyアルゴリズムを使用してファイルが圧縮されます。代わりに、Lempel–Ziv–Oberhumer(LZO)圧縮を適用する場合は、この値を指定します。

SNAPPY

デフォルトでは、Snappyアルゴリズムを使用してファイルが圧縮されます。オプションでこの値を指定できます。

NONE

アンロードされたファイルが圧縮されないことを指定します。

デフォルト: AUTO

SNAPPY_COMPRESSION = TRUE | FALSE

アンロードされたファイルが SNAPPY アルゴリズムを使用して圧縮されるかどうかを指定するブール値。

注釈

非推奨。 代わりに COMPRESSION = SNAPPY を使用してください。

デフォルト: TRUE

コピーオプション(copyOptions

次のコピーオプションを1つ以上指定できます(空白、カンマ、または改行で区切られます):

OVERWRITE = TRUE | FALSE
定義

COPY コマンドが、ファイルが保存されている場所にある、一致する名前を持つ既存のファイルを上書きするかどうかを指定するブール値。このオプションは、 COPY コマンドがアンロードするファイルの名前と一致しない既存のファイルを削除 しません

多くの場合、このオプションを有効にすると、同じ COPY INTO <l場所> ステートメントが複数回実行されたときに、ターゲットステージでのデータの重複を防ぐことができます。しかし、アンロード操作により複数のファイルがステージに書き込まれるとき、Snowflakeは、各ファイル名が並列実行スレッド全体で一意であることを保証するサフィックスを追加します(例: data_0_1_0)。並列実行スレッドの数は、アンロード操作によって異なります。アンロード操作で書き込まれたファイルのファイル名が前の操作で書き込まれたファイルと同じでない場合、このコピーオプションを含む SQL ステートメントでは既存のファイルを置き換えることができず、ファイルが重複します。

加えて、まれにマシンまたはネットワークに障害が発生した場合、アンロードジョブは再試行されます。そのシナリオでは、アンロード操作は、最初の試行で以前に書き込まれたファイルを最初に削除せずに、追加のファイルをステージに書き込みます。

ターゲットステージでのデータの重複を避けるために、 OVERWRITE = TRUE の代わりに INCLUDE_QUERY_ID = TRUE コピーオプションを設定し、各アンロードジョブ間のターゲットステージとパスにある、すべてのデータファイルを削除(またはアンロード操作ごとに異なるパスを使用)することをお勧めします。

デフォルト

FALSE

SINGLE = TRUE | FALSE
定義

単一のファイルを生成するか複数のファイルを生成するかを指定するブール値。 FALSE の場合、ファイル名プレフィックスを パス に含める必要があります。

重要

SINGLE = TRUE の場合、 COPY は FILE_EXTENSION ファイル形式オプションを無視し、 データ という名前のファイルを出力します。ファイル拡張子を指定するには、内部または外部ロケーション パス にファイル名と拡張子を指定します。例:

COPY INTO @mystage/data.csv ...

さらに、 COMPRESSION ファイル形式オプションがサポートされている圧縮アルゴリズム( GZIP など)のいずれかに明示的に設定されている場合、指定された内部または外部ロケーション パス は、適切なツールを使用してファイルを圧縮解除できるよう、対応するファイル拡張子( gz など)を持つファイル名で終わる必要があります。例:

COPY INTO @mystage/data.gz ...

COPY INTO @mystage/data.csv.gz ...
デフォルト

FALSE

MAX_FILE_SIZE = 数値
定義

スレッドごとに並列に生成される各ファイルの上限サイズ(バイト単位)を指定する数値(> 0)。実際のファイルサイズとアンロードされるファイルの数は、並列処理に使用可能なデータの合計量とノードの数によって決定されることに注意してください。

Snowflakeは、並列実行を利用してパフォーマンスを最適化します。スレッドの数は変更できません。

最大:5 GB (Amazon S3、Google Cloud Storage、またはMicrosoft Azureステージ)

注釈

COPY コマンドは、一度に1セットのテーブル行をアンロードします。非常に小さな MAX_FILE_SIZE 値を設定すると、行セット内のデータ量が指定サイズを超える可能性があります。

デフォルト

16777216 (16 MB)

INCLUDE_QUERY_ID = TRUE | FALSE
定義

アンロードされたデータファイルのファイル名に汎用一意識別子(UUID)を含めることにより、アンロードされたファイルを一意に識別するかどうかを指定するブール値。このオプションは、同時 COPY ステートメントがアンロードされたファイルを誤って上書きしないようにするのに役立ちます。

TRUE の場合、アンロードされたファイルの名前に UUID が追加されます。 UUID は、データファイルをアンロードするために使用される COPY ステートメントのクエリ ID です。 UUID はファイル名のセグメントです。 <パス>/data_<UUID>_<名前>.<拡張子>

FALSE の場合、アンロードされたデータファイルに UUID は追加されません。

注釈

  • 次のコピーオプションのいずれかが設定されている場合、 INCLUDE_QUERY_ID = TRUE はサポート されません

    • SINGLE = TRUE

    • OVERWRITE = TRUE

    • PARTITION BY <式>

  • まれに、マシンまたはネットワークに障害が発生した場合、アンロードジョブは再試行されます。そのシナリオでは、アンロード操作により、現在のクエリ ID の UUID でステージに書き込まれたファイルがすべて削除され、データのアンロードが再試行されます。ステージに書き込まれた新しいファイルには、再試行されたクエリ ID が UUID として含まれています。

デフォルト

FALSE

DETAILED_OUTPUT = TRUE | FALSE
定義

コマンド出力がアンロード操作を説明するか、操作の結果としてアンロードされた個々のファイルを説明するかを指定するブール値。

  • TRUE の場合、コマンド出力には、指定されたステージにアンロードされた各ファイルの行が含まれます。列には、各ファイルのパスと名前、そのサイズ、およびファイルにアンロードされた行数が表示されます。

  • FALSE の場合、コマンド出力は、アンロード操作全体を説明する単一の行で構成されます。列には、圧縮前と圧縮後(該当する場合)にテーブルからアンロードされたデータの合計量と、アンロードされた行の総数が表示されます。

デフォルト

FALSE

使用上の注意

  • STORAGE_INTEGRATION または CREDENTIALS は、プライベートストレージの場所に直接アンロードする場合のみに適用されます(つまり、Amazon S3、Google Cloud Storage、またはMicrosoft Azure)パブリックバケットにアンロードする場合、安全なアクセスは必要ありません。名前付き外部ステージにアンロードする場合、ステージはバケットへのアクセスに必要なすべての認証情報を提供します。

  • 現在の名前空間のファイル形式を参照する場合、形式識別子を囲む単一引用符を省略できます。

  • JSON TYPE に指定できるのは、テーブルの VARIANT 列からデータをアンロードする場合のみです。

  • タイプ PARQUET のファイルにアンロードする場合、

    • VARIANT 列は、出力ファイルで単純な JSON 文字列に変換されます。

    • TIMESTAMP_TZ または TIMESTAMP_LTZ データをアンロードするとエラーが発生します。

  • ソーステーブルに0行が含まれている場合、 COPY 操作はデータファイルをアンロード しません

  • この SQL コマンドは、空ではない保管場所にアンロードするときに警告を返しません。保管場所のファイルがデータパイプラインによって消費されるときの予期しない動作を回避するために、空の保管場所のみに書き込むことをお勧めします。

  • アンロードの操作に失敗しても、データファイルがアンロードされる可能性があります。たとえば、ステートメントがタイムアウト制限を超えてキャンセルされた場合などです。また、別の地域のクラウドストレージへのアンロード操作が失敗すると、データ転送コストが発生します。

  • 列に 列レベルのセキュリティ マスキングポリシーが設定されている場合は、マスキングポリシーがデータに適用され、許可されていないユーザーに列内のマスキングされたデータが表示されます。

テーブルからテーブルステージのファイルにデータをアンロード

フォルダー/ファイル名プレフィックス(result/data_)、名前付きファイル形式(myformat)、およびgzip圧縮を使用して、 orderstiny テーブルからテーブルのステージにデータをアンロードします。

COPY INTO @%orderstiny/result/data_
  FROM orderstiny FILE_FORMAT = (FORMAT_NAME ='myformat' COMPRESSION='GZIP');

クエリから名前付き内部ステージのファイルにデータをアンロード

フォルダー/ファイル名プレフィックス(result/data_)、名前付きファイル形式(myformat)、およびgzip圧縮を使用して、名前付き内部ステージ(my_stage)にクエリの結果をアンロードします。

COPY INTO @my_stage/result/data_ FROM (SELECT * FROM orderstiny)
   file_format=(format_name='myformat' compression='gzip');

上記の例は、アンロードされたデータを含むファイルが orderstiny のテーブルの場所ではなく、 my_stage のステージの場所に保存されることを除いて、機能的に最初の例と同等です。

テーブルから外部ロケーションのファイルに直接データをアンロード

名前付き my_csv_format ファイル形式を使用して、テーブル内のすべてのデータを保存場所にアンロードします。

Amazon S3

myint という名前の参照されたストレージ統合を使用して、参照されたS3バケットにアクセスします。

COPY INTO 's3://mybucket/unload/'
  FROM mytable
  STORAGE_INTEGRATION = myint
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

提供された認証情報を使用して、参照されたS3バケットにアクセスします。

COPY INTO 's3://mybucket/unload/'
  FROM mytable
  CREDENTIALS = (AWS_KEY_ID='xxxx' AWS_SECRET_KEY='xxxxx' AWS_TOKEN='xxxxxx')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

Google Cloud Storage

myint という名前の参照ストレージ統合を使用して、参照された GCS バケットにアクセスします。

COPY INTO 'gcs://mybucket/unload/'
  FROM mytable
  STORAGE_INTEGRATION = myint
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

Microsoft Azure

myint という名前の参照ストレージ統合を使用して、参照されたコンテナーにアクセスします。

COPY INTO 'azure://myaccount.blob.core.windows.net/unload/'
  FROM mytable
  STORAGE_INTEGRATION = myint
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

提供された認証情報を使用して、参照されたコンテナーにアクセスします。

COPY INTO 'azure://myaccount.blob.core.windows.net/mycontainer/unload/'
  FROM mytable
  CREDENTIALS=(AZURE_SAS_TOKEN='xxxx')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

アンロードされた行のParquetファイルへのパーティション分割

次の例では、アンロードされた行を日付列と時間列の2つの列にある値に応じて、Parquetファイルに分割します。この例では、アンロードされた各ファイルの最大サイズを指定しています。

CREATE or replace TABLE t1 (
  dt date,
  ts time
  )
AS
  SELECT TO_DATE($1)
        ,TO_TIME($2)
    FROM VALUES
           ('2020-01-28', '18:05')
          ,('2020-01-28', '22:57')
          ,('2020-01-28', NULL)
          ,('2020-01-29', '02:15')
;

SELECT * FROM t1;

+------------+----------+
| DT         | TS       |
|------------+----------|
| 2020-01-28 | 18:05:00 |
| 2020-01-28 | 22:57:00 |
| 2020-01-28 | 22:32:00 |
| 2020-01-29 | 02:15:00 |
+------------+----------+

-- Partition the unloaded data by date and hour. Set ``32000000`` (32 MB) as the upper size limit of each file to be generated in parallel per thread.
COPY INTO @%t1
  FROM t1
  PARTITION BY ('date=' || to_varchar(dt, 'YYYY-MM-DD') || '/hour=' || to_varchar(date_part(hour, ts))) -- Concatenate labels and column values to output meaningful filenames
  FILE_FORMAT = (TYPE=parquet)
  MAX_FILE_SIZE = 32000000
  HEADER=true;

LIST @%t1;

+------------------------------------------------------------------------------------------+------+----------------------------------+------------------------------+
| name                                                                                     | size | md5                              | last_modified                |
|------------------------------------------------------------------------------------------+------+----------------------------------+------------------------------|
| __NULL__/data_019c059d-0502-d90c-0000-438300ad6596_006_4_0.snappy.parquet                |  512 | 1c9cb460d59903005ee0758d42511669 | Wed, 5 Aug 2020 16:58:16 GMT |
| date=2020-01-28/hour=18/data_019c059d-0502-d90c-0000-438300ad6596_006_4_0.snappy.parquet |  592 | d3c6985ebb36df1f693b52c4a3241cc4 | Wed, 5 Aug 2020 16:58:16 GMT |
| date=2020-01-28/hour=22/data_019c059d-0502-d90c-0000-438300ad6596_006_6_0.snappy.parquet |  592 | a7ea4dc1a8d189aabf1768ed006f7fb4 | Wed, 5 Aug 2020 16:58:16 GMT |
| date=2020-01-29/hour=2/data_019c059d-0502-d90c-0000-438300ad6596_006_0_0.snappy.parquet  |  592 | 2d40ccbb0d8224991a16195e2e7e5a95 | Wed, 5 Aug 2020 16:58:16 GMT |
+------------------------------------------------------------------------------------------+------+----------------------------------+------------------------------+

アンロードされたファイルの NULL/空のフィールドデータの保持

アンロードされたファイルの SQL NULL と空のフィールドを保持します。

-- View the table column values

select * from HOME_SALES;

+------------+-------+-------+-------------+--------+-----------+
| CITY       | STATE | ZIP   | TYPE        | PRICE  | SALE_DATE |
|------------+-------+-------+-------------+--------+-----------|
| Lexington  | MA    | 95815 | Residential | 268880 | 3/28/17   |
| Belmont    | MA    | 95815 | Residential |        | 2/21/17   |
| Winchester | MA    | NULL  | Residential |        | 1/31/17   |
+------------+-------+-------+-------------+--------+-----------+

-- Unload the table data into the current user's personal stage. The file format options retain both the NULL value and the empty values in the output file

copy into @~ from HOME_SALES
file_format=(type=csv null_if = ('NULL', 'null')
empty_field_as_null=false);

-- Contents of the output file

95815,MA-Lexington,268880,3/28/17
95815,MA-Belmont,,2/21/17
NULL,MA-Winchester,389921,1/31/17

単一ファイルへのデータのアンロード

SINGLE コピーオプションを使用して、すべての行を単一のデータファイルにアンロードします。

copy into @~ from HOME_SALES
single = true;

アンロードされたファイル名に UUID を含める

INCLUDE_QUERY_ID コピーオプションを TRUE に設定して、アンロードされたファイルの名前に UUID を含めます。

-- Unload rows from the T1 table into the T1 table stage:
COPY INTO @%t1
  FROM t1
  FILE_FORMAT=(TYPE=parquet)
  INCLUDE_QUERY_ID=true;

-- Retrieve the query ID for the COPY INTO location statement.
-- This optional step enables you to see that the query ID for the COPY INTO location statement
-- is identical to the UUID in the unloaded files.
SELECT last_query_id();
+--------------------------------------+
| LAST_QUERY_ID()                      |
|--------------------------------------|
| 019260c2-00c0-f2f2-0000-4383001cf046 |
+--------------------------------------+

LS @%t1;
+----------------------------------------------------------------+------+----------------------------------+-------------------------------+
| name                                                           | size | md5                              | last_modified                 |
|----------------------------------------------------------------+------+----------------------------------+-------------------------------|
| data_019260c2-00c0-f2f2-0000-4383001cf046_0_0_0.snappy.parquet |  544 | eb2215ec3ccce61ffa3f5121918d602e | Thu, 20 Feb 2020 16:02:17 GMT |
+----------------------------------------------------------------+------+----------------------------------+-------------------------------+

アンロードするデータの検証(クエリから)

検証モードで COPY を実行してクエリの結果を返し、 COPY が通常モードで実行された場合に orderstiny テーブルからアンロードされるデータを表示します。

COPY INTO @my_stage
FROM (SELECT * FROM orderstiny LIMIT 5)
VALIDATION_MODE='RETURN_ROWS';

----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+
 C1 |   C2   | C3 |    C4     |     C5     |    C6    |       C7        | C8 |                                    C9                                     |
----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+
 1  | 36901  | O  | 173665.47 | 1996-01-02 | 5-LOW    | Clerk#000000951 | 0  | nstructions sleep furiously among                                         |
 2  | 78002  | O  | 46929.18  | 1996-12-01 | 1-URGENT | Clerk#000000880 | 0  |  foxes. pending accounts at the pending\, silent asymptot                 |
 3  | 123314 | F  | 193846.25 | 1993-10-14 | 5-LOW    | Clerk#000000955 | 0  | sly final accounts boost. carefully regular ideas cajole carefully. depos |
 4  | 136777 | O  | 32151.78  | 1995-10-11 | 5-LOW    | Clerk#000000124 | 0  | sits. slyly regular warthogs cajole. regular\, regular theodolites acro   |
 5  | 44485  | F  | 144659.20 | 1994-07-30 | 5-LOW    | Clerk#000000925 | 0  | quickly. bold deposits sleep slyly. packages use slyly                    |
----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+