カテゴリ:

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> ) }
[ 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バケット)にアンロードされます。追加のパラメーターが必要になる場合があります。詳細については、 追加のクラウドプロバイダーパラメーター (このトピック)をご参照ください。

'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 という名前のファイルを作成します。

注釈

外部の場所の URI 文字列(Amazon S3、Google Cloud Storage、またはMicrosoft Azure)は一重引用符で囲む 必要があります 。ただし、任意の文字列を一重引用符で囲むことができます。これにより、スペースを含む特殊文字を場所およびファイル名で使用できます。例:

-- Stages
COPY INTO '@mystage/path 1/file 1.csv' FROM mytable;
COPY INTO '@%mytable/path 1/file 1.csv' FROM mytable;
COPY INTO '@~/path 1/file 1.csv' FROM mytable;

-- S3 bucket
COPY INTO 's3://mybucket 1/prefix 1/file 1.csv' FROM mytable;

-- Azure container
COPY INTO 'azure://myaccount.blob.core.windows.net/mycontainer/encrypted_files/file 1.csv' FROM mytable;
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: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ビットキーである必要があります。

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

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 で始まる)を受け入れます。たとえば、ソーン(Þ)文字で区切られたレコードの場合、8進数(\\336)または16進数(0xDE)の値を指定します。 NONE の値も受け入れます。

指定された区切り文字は、ランダムなバイトのシーケンスではなく、有効な UTF-8文字でなければなりません。

複数文字の区切り文字もサポートされています。ただし、 RECORD_DELIMITER または FIELD_DELIMITER の区切り文字は、他のファイル形式オプション( FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb' など)の区切り文字の部分文字列にはできません。区切り文字は最大20文字に制限されています。 ESCAPE または ESCAPE_UNENCLOSED_FIELD などの他のファイル形式オプションに使用される文字を指定しないでください。

デフォルト:改行文字(\n)。

FIELD_DELIMITER = '文字' | NONE

入力ファイル(データのロード)またはアンロードされたファイル(データのアンロード)のフィールドを区切る1つ以上のシングルバイトまたはマルチバイト文字。

一般的なエスケープシーケンス、8進値( \\ で始まる)、または16進値( 0x で始まる)を受け入れます。たとえば、ソーン(Þ)文字で区切られたフィールドの場合、8進数(\\336)または16進数(0xDE)の値を指定します。 NONE の値も受け入れます。

指定された区切り文字は、ランダムなバイトのシーケンスではなく、有効な UTF-8文字でなければなりません。

複数文字の区切り文字もサポートされています。ただし、 RECORD_DELIMITER または FIELD_DELIMITER の区切り文字は、他のファイル形式オプション( FIELD_DELIMITER = 'aa' RECORD_DELIMITER = 'aabb' など)の区切り文字の部分文字列にはできません。区切り文字は最大20文字に制限されています。 ESCAPE または ESCAPE_UNENCLOSED_FIELD などの他のファイル形式オプションに使用される文字を指定しないでください。

デフォルト:コンマ(,

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
使用

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

定義

フィールド値のエスケープ文字として使用される1文字の文字列。エスケープ文字は、文字シーケンス内の後続の文字に対して代替解釈を呼び出します。ESCAPE 文字を使用して、データ内の FIELD_DELIMITER または RECORD_DELIMITER、または 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 コマンドがアンロードするファイルの名前と一致しない既存のファイルを 削除しません

デフォルト: FALSE

SINGLE = TRUE | FALSE

単一のファイルを生成するか複数のファイルを生成するかを指定するブール値。 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 ...
MAX_FILE_SIZE = 数値

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

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

デフォルト: 16000000 (16 MB)

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

注釈

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

INCLUDE_QUERY_ID = TRUE | FALSE

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

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

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

デフォルト: FALSE

注釈

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

  • SINGLE = TRUE

  • OVERWRITE = TRUE

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 操作はデータファイルをアンロード しません

  • COPY ステートメントが失敗しても、データファイルがアンロードされる可能性があります。たとえば、ステートメントがタイムアウト制限を超えてキャンセルされた場合などです。

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

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

フォルダー/ファイル名プレフィックス(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);

アンロードされたファイルの 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                    |
----+--------+----+-----------+------------+----------+-----------------+----+---------------------------------------------------------------------------+