COPY INTO <テーブル>¶

データファイルから既存のテーブルにデータをロードします。ファイルはすでに以下のいずれかの場所にある必要があります。

内部ステージ（またはテーブル/ユーザーステージ）という名前。ファイルは、 PUT コマンドを使用してステージングできます。
外部の場所を参照する名前付きの外部ステージ（Amazon S3、Google Cloud Storage、またはMicrosoft Azure）。

取得する前に復元が必要な、アーカイブクラウドストレージクラスに保持されているデータにアクセスすることはできません。これらのアーカイブストレージクラスには、たとえば、Amazon S3 Glacier Flexible RetrievalまたはGlacier Deep Archiveストレージクラス、またはMicrosoft Azure Archive Storageが含まれます。
外部の場所（Amazon S3、Google Cloud Storage、またはMicrosoft Azure）。

こちらもご参照ください。: COPY INTO <場所>

構文¶

/* Standard data load */
COPY INTO [<namespace>.]<table_name>
     FROM { internalStage | externalStage | externalLocation }
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
                    TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
[ copyOptions ]
[ VALIDATION_MODE = RETURN_<n>_ROWS | RETURN_ERRORS | RETURN_ALL_ERRORS ]

/* Data load with transformation */
COPY INTO [<namespace>.]<table_name> [ ( <col_name> [ , <col_name> ... ] ) ]
     FROM ( SELECT [<alias>.]$<file_col_num>[.<element>] [ , [<alias>.]$<file_col_num>[.<element>] ... ]
            FROM { internalStage | externalStage } )
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
                    TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
[ copyOptions ]

Copy

条件:

internalStage ::=
    @[<namespace>.]<int_stage_name>[/<path>]
  | @[<namespace>.]%<table_name>[/<path>]
  | @~[/<path>]

Copy

externalStage ::=
  @[<namespace>.]<ext_stage_name>[/<path>]

Copy

externalLocation (for Amazon S3) ::=
  '<protocol>://<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' ] ) ]

Copy

externalLocation (for Google Cloud Storage) ::=
  'gcs://<bucket>[/<path>]'
  [ STORAGE_INTEGRATION = <integration_name> ]
  [ ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' ] [ KMS_KEY_ID = '<string>' ] | [ TYPE = 'NONE' ] ) ]

Copy

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>' ] ) ]

Copy

formatTypeOptions ::=
-- If FILE_FORMAT = ( TYPE = CSV ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     RECORD_DELIMITER = '<string>' | NONE
     FIELD_DELIMITER = '<string>' | NONE
     MULTI_LINE = TRUE | FALSE
     PARSE_HEADER = TRUE | FALSE
     SKIP_HEADER = <integer>
     SKIP_BLANK_LINES = TRUE | FALSE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     ESCAPE = '<character>' | NONE
     ESCAPE_UNENCLOSED_FIELD = '<character>' | NONE
     TRIM_SPACE = TRUE | FALSE
     FIELD_OPTIONALLY_ENCLOSED_BY = '<character>' | NONE
     NULL_IF = ( [ '<string>' [ , '<string>' ... ] ] )
     ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     EMPTY_FIELD_AS_NULL = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
     ENCODING = '<string>' | UTF8
-- If FILE_FORMAT = ( TYPE = JSON ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     DATE_FORMAT = '<string>' | AUTO
     TIME_FORMAT = '<string>' | AUTO
     TIMESTAMP_FORMAT = '<string>' | AUTO
     BINARY_FORMAT = HEX | BASE64 | UTF8
     TRIM_SPACE = TRUE | FALSE
     MULTI_LINE = TRUE | FALSE
     NULL_IF = ( [ '<string>' [ , '<string>' ... ] ] )
     ENABLE_OCTAL = TRUE | FALSE
     ALLOW_DUPLICATE = TRUE | FALSE
     STRIP_OUTER_ARRAY = TRUE | FALSE
     STRIP_NULL_VALUES = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     IGNORE_UTF8_ERRORS = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
-- If FILE_FORMAT = ( TYPE = AVRO ... )
     COMPRESSION = AUTO | GZIP | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( [ '<string>' [ , '<string>' ... ] ] )
-- If FILE_FORMAT = ( TYPE = ORC ... )
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( [ '<string>' [ , '<string>' ... ] ] )
-- If FILE_FORMAT = ( TYPE = PARQUET ... )
     COMPRESSION = AUTO | SNAPPY | NONE
     BINARY_AS_TEXT = TRUE | FALSE
     USE_LOGICAL_TYPE = TRUE | FALSE
     TRIM_SPACE = TRUE | FALSE
     USE_VECTORIZED_SCANNER = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( [ '<string>' [ , '<string>' ... ] ] )
-- If FILE_FORMAT = ( TYPE = XML ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     IGNORE_UTF8_ERRORS = TRUE | FALSE
     PRESERVE_SPACE = TRUE | FALSE
     STRIP_OUTER_ELEMENT = TRUE | FALSE
     DISABLE_AUTO_CONVERT = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE

Copy

copyOptions ::=
     CLUSTER_AT_INGEST_TIME = TRUE | FALSE
     ENFORCE_LENGTH = TRUE | FALSE
     FILE_PROCESSOR = (SCANNER = <custom_scanner_type> SCANNER_OPTIONS = (<scanner_options>))
     FORCE = TRUE | FALSE
     INCLUDE_METADATA = ( <column_name> = METADATA$<field> [ , <column_name> = METADATA${field} ... ] )
     LOAD_MODE = { FULL_INGEST | ADD_FILES_COPY }
     LOAD_UNCERTAIN_FILES = TRUE | FALSE
     MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
     ON_ERROR = { CONTINUE | SKIP_FILE | SKIP_FILE_<num> | 'SKIP_FILE_<num>%' | ABORT_STATEMENT }
     PURGE = TRUE | FALSE
     RETURN_FAILED_ONLY = TRUE | FALSE
     SIZE_LIMIT = <num>
     TRUNCATECOLUMNS = TRUE | FALSE

Copy

必須パラメーター¶

[namespace.]table_name

データがロードされるテーブルの名前を指定します。

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

FROM ...

ロードするデータを含むファイルがステージングされる内部または外部ロケーションを指定します。

@[namespace.]int_stage_name[/path]

ファイルは指定された名前付き内部ステージにあります。

@[namespace.]ext_stage_name[/path]

ファイルは指定された名前付き外部ステージにあります。

@[namespace.]%table_name[/path]

ファイルは指定されたテーブルのステージにあります。

@~[/path]

ファイルは現在のユーザーのステージにあります。

'protocol://bucket[/path]'

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

'gcs://bucket[/path]'

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

'azure://account.blob.core.windows.net/container[/path]'

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

条件:

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

protocol は以下のいずれかです。

s3 プレフィックスは、中国以外のパブリック AWS リージョンのS3ストレージを参照します。

s3china プレフィックスは、中国のパブリック AWS リージョンのS3ストレージを参照します。

s3gov プレフィックスは、政府リージョンのS3ストレージを参照します。

ストレージ統合を使用した政府リージョンのクラウドストレージへのアクセスは、同じ政府リージョンでホストされているSnowflakeアカウントに限定されています。

同様に、中国の地域のクラウドストレージにアクセスする必要がある場合は、中国の同じ地域でホストされているSnowflakeアカウントからのみストレージ統合を使用できます。

このような場合、 CREDENTIALS パラメーター（ CREATE STAGE コマンド内の）を使用して（ストレージ統合を使用するのではなく）、認証用の認証情報を提供します。

bucket はバケットの名前です。

account は、Azureアカウントの名前です（例: myaccount）。Data Lake Storage Gen2を含む、サポートされているすべてのタイプのAzure BLOBストレージアカウントに、 blob.core.windows.net エンドポイントを使用します。

現在、ストレージ統合を使用した政府リージョンのAzure BLOBストレージへのアクセスは、同じ政府リージョンのAzureでホストされているSnowflakeアカウントに限定されていることに注意してください。直接認証情報を使用した、政府リージョン外でホストされているアカウントからBLOBストレージへのアクセスがサポートされています。

container は、Azureコンテナーの名前です（例: mycontainer）。
path は、ロードするファイルのセットを制限するクラウドストレージの場所にある、ファイルの大文字と小文字を区別するオプションのパスです（つまり、ファイルの名前は一般的な文字列で開始）。パスは、別のクラウドストレージサービスによって プレフィックス または フォルダー と呼ばれることもあります。

「パス」は名前のリテラルプレフィックスであるため、 /./ や /../ などの相対パス修飾子は文字どおりに解釈されます。例：
-- S3 bucket
COPY INTO mytable FROM 's3://mybucket/./../a.csv';

-- Google Cloud Storage bucket
COPY INTO mytable FROM 'gcs://mybucket/./../a.csv';

-- Azure container
COPY INTO mytable FROM 'azure://myaccount.blob.core.windows.net/mycontainer/./../a.csv';
Copy
これらのCOPYステートメントでは、Snowflakeは外部の場所で文字通り ./../a.csv という名前のファイルを探します。

注釈

内部または外部のステージ、またはパス名にスペースなどの特殊文字が含まれている場合は、 FROM ... 文字列を一重引用符で囲みます。
FROM ... 値は、リテラル定数にする必要があります。値を SQL 変数にすることはできません。

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

STORAGE_INTEGRATION = integration_name または . CREDENTIALS = ( cloud_specific_credentials )

COPY ステートメントの FROM 値が、外部ステージ名ではなく外部ストレージ URI の場合にサポートされます。

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

クラウドプロバイダーに接続し、データファイルがステージされるプライベート/保護されたストレージコンテナーにアクセスするためのセキュリティ認証情報を指定します。

Amazon S3

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

注釈

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

CREDENTIALS = ( AWS_KEY_ID = 'string' AWS_SECRET_KEY = 'string' [ AWS_TOKEN = 'string' ] )
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リソース名）を指定します。

Google Cloud Storage

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

Microsoft Azure

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

注釈

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

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

ENCRYPTION = ( cloud_specific_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 値を受け入れるサーバー側の暗号化。

NONE ：暗号化なし。

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

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

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

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

Google Cloud Storage

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

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

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

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

https://cloud.google.com/storage/docs/encryption/customer-managed-keys

https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys

NONE ：暗号化なし。

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

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

Microsoft Azure

ENCRYPTION = ( [ TYPE = 'AZURE_CSE' | 'NONE' ] [ MASTER_KEY = 'string' ] )

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

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

NONE ：暗号化なし。

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

変換パラメーター¶

( SELECT [alias.]$file_col_num[.element] [ , [alias.]$file_col_num[.element] ... ] FROM ... [ alias ] )

ロード中にデータを変換するために必要

ステージングされたデータファイルからロードする明示的なフィールド/列のセット（カンマ区切り）を指定します。フィールド/列は、標準の SQL クエリ（つまり SELECT リスト）を使用してファイルから選択されます。条件：

alias

FROM 値のオプションのエイリアスを指定します（例: COPY INTO t1 (c1) FROM (SELECT d.$1 FROM @mystage/file1.csv.gz d); の d）。

file_col_num

ロードするデータを含む（ファイル内の）フィールド/列の位置番号を指定します（最初のフィールドには 1 、2番目のフィールドには 2 など）

element

データファイル内の繰り返し値のパスと要素名を指定します（半構造化データファイルにのみ適用）。

SELECT リストは、ロード元のデータファイル内のフィールド/列の番号付きセットを定義します。リストはターゲットテーブルの列のシーケンスと一致する必要があります。オプションの ( col_name [ , col_name ... ] ) パラメーターを使用して、ターゲットテーブルの特定の列にリストをマップできます。

データファイルの実際のフィールド/列の順序は、ターゲットテーブルの列の順序と異なる場合があることに注意してください。重要なのは、 SELECT リストがデータファイルのフィールド/列をテーブルの対応する列にマップすることです。

注釈

変換に使用される SELECT ステートメントは、すべての関数をサポートしているわけではありません。サポートされている関数の完全なリストと、例を含むデータ読み込み変換の詳細については、ロード中のデータの変換の使用上の注意をご参照ください。

また、データロード変換のみは、ユーザーステージおよび名前付きステージ（内部または外部）からのデータの選択をサポートしています。

( col_name [ , col_name ... ] )

オプションで、データを挿入するテーブル列の明示的なリスト（カンマ区切り）を指定します。

最初の列は、ロードされたファイルから抽出された最初のフィールド/列から生成された値を消費します。
2番目の列は、ロードされたファイルから抽出された2番目のフィールド/列から生成された値を消費します。
上記のように順序が指定されます。

このリストで列を繰り返すことはできません。この列リストから除外された列には、デフォルト値（指定されていない場合はNULL）が入力されます。ただし、除外された列は、デフォルト値としてシーケンスを持つことはできません。

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

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

ロードする1つ以上のファイル名のリスト（コンマで区切る）を指定します。ファイルは、コマンドで指定されたSnowflake内部の場所または外部の場所のいずれかに既にステージングされている必要があります。指定されたいずれのファイルも見つからない場合は、 COPY ステートメントで別の ON_ERROR オプションが明示的に設定されていない限り、デフォルトの動作 ON_ERROR = ABORT_STATEMENT はロード操作を中止します。

指定できるファイル名の最大数は1000です。

注釈

外部ステージのみ（つまり、Amazon S3、Google Cloud Storage、またはMicrosoft Azure）、ステージ定義の URL と解決されたファイル名のリストを連結することにより、ファイルパスが設定されます。

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

PATTERN = 'regex_pattern'

一致するファイル名やパスを指定する、単一引用符で囲まれた正規表現パターン文字列。

Tip

最高のパフォーマンスを得るには、多数のファイルをフィルターするパターンを適用しないようにしてください。

正規表現は、異なる方法で一括データロードとSnowpipeデータロードに適用されることに注意してください。

Snowpipeは、ステージ定義内のパスセグメントを保存場所からトリムし、残りのパスセグメントとファイル名に正規表現を適用します。ステージ定義を表示するには、ステージに対して DESCRIBE STAGE コマンドを実行します。URL プロパティは、バケット名またはコンテナー名と0個以上のパスセグメントで構成されます。たとえば、 COPY INTO <テーブル> ステートメントの FROM の場所が @s/path1/path2/ で、ステージ @s の URL の値が s3://mybucket/path1/ の場合、Snowpipeは保存場所から /path1/ をトリムします。 FROM 句で、正規表現を path2/ とパス内のファイル名に適用します。
一括データロード操作は、 FROM 句の保存場所全体に正規表現を適用します。

注釈

FILES と PATTERN オプションを一緒に使うと、 FILES オプションで指定したパスだけが読み込まれます。この2つのオプションは併用しないことをお勧めします。

ロードするデータの形式を指定します。

FORMAT_NAME = 'file_format_name': テーブルへのデータのロードに使用する既存の名前付きファイル形式を指定します。名前付きファイル形式は、データファイルの形式タイプ（CSV、 JSONなど）およびその他の形式オプションを決定します。詳細については、 CREATE FILE FORMAT をご参照ください。
TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ]: テーブルにロードするファイルのタイプを指定します。形式タイプが指定されている場合、追加の形式固有のオプションを指定できます。詳細については、形式タイプオプション（このトピック）をご参照ください。

注釈

FORMAT_NAME と TYPE は相互に排他的です。同じ COPY コマンドで両方を指定すると、予期しない動作が発生する可能性があります。

COPY_OPTIONS = ( ... )

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

VALIDATION_MODE = RETURN_n_ROWS | RETURN_ERRORS | RETURN_ALL_ERRORS

指定したテーブルにデータファイルをロードする代わりに、 COPY コマンドにデータファイルを検証するよう指示する文字列（定数）。つまり、 COPY コマンドはファイルのエラーをテストしますが、ロードしません。このコマンドは、ロードされるデータを検証し、指定された検証オプションに基づいて結果を返します。

サポートされる値	注意
`RETURN_n_ROWS` （例: `RETURN_10_ROWS`）	エラーが発生しない場合、指定された行数を検証します。そうでない場合、行で最初に発生したエラーで不合格となります。
`RETURN_ERRORS`	COPY ステートメントで指定されたすべてのファイルにわたるすべてのエラー（解析、変換など）を返します。
`RETURN_ALL_ERRORS`	ロード中に `ON_ERROR` コピーオプションが `CONTINUE` に設定されていたため、以前のロード中に部分的にロードされたエラーを含む、 COPY ステートメントで指定されたすべてのファイルにわたるすべてのエラーを返します。

注釈

VALIDATION_MODE は、ロード中にデータを変換する COPY ステートメントをサポートしません。パラメーターが指定されている場合、 COPY ステートメントはエラーを返します。
Icebergテーブルでは、VALIDATION_MODE はサポートされていません。
VALIDATE テーブル関数を使用して、以前のロード中に発生したすべてのエラーを表示します。この関数も、ロード中にデータを変換する COPY ステートメントをサポートしません。

形式タイプオプション（`formatTypeOptions`）¶

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

TYPE = CSV¶

ロードするデータファイルの現在の圧縮アルゴリズムを指定する文字列（定数）。Snowflakeはこのオプションを使用して、ファイル内の圧縮データをロード用に抽出できるように、圧縮済みデータファイルの圧縮方法を検出します。

サポートされる値	注意
`AUTO`	現在は自動検出できないBrotliで圧縮されたファイルを除き、圧縮アルゴリズムは自動的に検出されます。Brotliで圧縮されたファイルをロードする場合は、 `AUTO` ではなく `BROTLI` を明示的に使用してください。
`GZIP`
`BZ2`
`BROTLI`	Brotliで圧縮されたファイルをロードするときには、指定する必要があります。
`ZSTD`	Zstandard v0.8（およびそれ以上）がサポートされています。
`DEFLATE`	Deflate圧縮されたファイル（zlibヘッダー、 RFC1950を使用）。
`RAW_DEFLATE`	生Deflate圧縮ファイル（ヘッダーなし、 RFC1951）。
`NONE`	ロードするデータファイルは圧縮されていません。

デフォルト:: AUTO

RECORD_DELIMITER = 'string' | NONE

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

シングルバイト文字:

8進値（\\ でプレフィックス）、または16進値（0x または \x でプレフィックス）を受け入れます。たとえば、アクサンシルコンフレックス（^）文字で区切られた記録の場合は、8進数（\\136）または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 = 'string' | NONE

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

シングルバイト文字:

マルチバイト文字:

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

注釈

ASCII 以外の文字の場合は、16進数のバイトシーケンス値を使用して決定論的動作を得る必要があります。

NONE の値も受け入れます。

デフォルト:: コンマ（,）

MULTI_LINE = TRUE | FALSE

複数行を許すかどうかを指定するブール。

MULTI_LINE が FALSE に設定され、指定されたレコード区切り文字が CSV フィールド内に存在する場合、そのフィールドを含むレコードはエラーとして解釈されます。

デフォルト:: TRUE

注釈

RFC4180 仕様に従った大きな非圧縮 CSV ファイル（128MB より大きい）をロードする場合、MULTI_LINE が FALSE に、COMPRESSION が NONE に、ON_ERROR が ABORT_STATEMENT または CONTINUE に設定されているときは、Snowflakeはこれら CSV ファイルの平行スキャンをサポートします。

PARSE_HEADER = TRUE | FALSE

データファイルにある最初の行のヘッダーを使用して列名を決定するかどうかを指定するブール値。

このファイル形式オプションは、次のアクションにのみ適用されます。

INFER_SCHEMA 関数を使用した、列定義の自動検出。

INFER_SCHEMA 関数と MATCH_BY_COLUMN_NAME コピーオプションを使用した、個別の列への CSV データロード。

オプションが TRUE に設定されている場合は、最初の行のヘッダーが列名を決定するために使われます。デフォルト値 FALSE は、列名をc として返します。 は列の位置です。

なお、 SKIP_HEADER オプションは、 PARSE_HEADER = TRUE ではサポートされません。

デフォルト:: FALSE

SKIP_HEADER = integer

スキップするファイルの先頭の行数。

SKIP_HEADER は RECORD_DELIMITER または FIELD_DELIMITER の値を使用してヘッダー行を決定しないことに注意してください。むしろ、指定された数の CRLF （キャリッジリターン、ラインフィード）で区切られたファイル内の行を単にスキップします。ロードするデータの行を決定するのには、RECORD_DELIMITER および FIELD_DELIMITER が使用されます。

デフォルト:: 0

SKIP_BLANK_LINES = TRUE | FALSE

使用:: データのロードのみ
定義:: データファイルで検出された空白行のスキップを指定するブール値。それ以外の場合、空白行は記録終了エラーを生成します（デフォルトの動作）。
デフォルト:: FALSE

DATE_FORMAT = 'string' | AUTO

ロードするデータファイルの日付値の形式を定義する文字列。値が指定されていない場合、または AUTO の場合、 DATE_INPUT_FORMAT セッションパラメーターの値が使用されます。

デフォルト:: AUTO

TIME_FORMAT = 'string' | AUTO

ロードするデータファイルの時間値の形式を定義する文字列。値が指定されていない場合、または AUTO の場合、 TIME_INPUT_FORMAT セッションパラメーターの値が使用されます。

デフォルト:: AUTO

TIMESTAMP_FORMAT = 'string' | AUTO

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

デフォルト:: AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

バイナリ入力または出力のエンコード形式を定義する文字列（定数）。このオプションは、テーブルのバイナリ列にデータをロードする場合にのみ適用されます。

デフォルト:: HEX

ESCAPE = 'character' | NONE

使用:: データのロードとアンロード
定義:: 囲まれているフィールド値専用のエスケープ文字として使用されるシングルバイト文字。エスケープ文字は、文字シーケンス内の後続の文字に対して代替解釈を呼び出します。ESCAPE 文字を使用して、データ内の FIELD_OPTIONALLY_ENCLOSED_BY 文字のインスタンスをリテラルとして解釈できます。

一般的なエスケープシーケンス（例えば、 \t はタブ、 \n は改行、 \r はキャリッジリターン、 \\ はバックスラッシュ）、8進数値、16進数値を受け付けます。

注釈

このファイル形式オプションは、シングルバイト文字のみをサポートします。UTF-8文字エンコードは、上位の ASCII 文字をマルチバイト文字として表すことに注意してください。データファイルが UTF-8文字セットでエンコードされている場合は、オプション値として上位の ASCII 文字を指定することはできません。

さらに、上位の ASCII 文字を指定する場合は、データファイルの文字エンコードとして ENCODING = 'string' ファイル形式オプションを設定して、文字が正しく解釈されるようにすることをお勧めします。

デフォルト:: NONE

ESCAPE_UNENCLOSED_FIELD = 'character' | NONE

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

注釈

デフォルト値は \\ です。データファイルの行がバックスラッシュ（\）文字で終わる場合、この文字は RECORD_DELIMITER ファイル形式オプションに指定された改行文字または復帰文字をエスケープします。その結果、ロード操作はこの行と次の行を単一のデータ行として扱います。この問題を回避するには、この値を NONE に設定します。
このファイル形式オプションは、シングルバイト文字のみをサポートします。UTF-8文字エンコードは、上位の ASCII 文字をマルチバイト文字として表すことに注意してください。データファイルが UTF-8文字セットでエンコードされている場合は、オプション値として上位の ASCII 文字を指定することはできません。

さらに、上位の ASCII 文字を指定する場合は、データファイルの文字エンコードとして ENCODING = 'string' ファイル形式オプションを設定して、文字が正しく解釈されるようにすることをお勧めします。

デフォルト:: バックスラッシュ（\\）

TRIM_SPACE = TRUE | FALSE

フィールドから空白を削除するかどうかを指定するブール値。

たとえば、外部データベースソフトウェアがフィールドを引用符で囲み、先頭にスペースを挿入する場合、Snowflakeは引用符の先頭文字ではなく、先頭のスペースをフィールドの先頭として読み取ります（つまり、引用符はフィールドデータの文字列の一部として解釈されます）。このオプションを使用して、データのロード中に不要なスペースを削除します。

別の例として、文字列を囲む引用符を前後のスペースで囲む場合、 TRIM_SPACE オプションを使用して周囲のスペースを削除し、 FIELD_OPTIONALLY_ENCLOSED_BY オプションを使用して引用符を削除できます。引用符内のスペースは保持されることに注意してください。

例えば、フィールド区切り文字が | および FIELD_OPTIONALLY_ENCLOSED_BY = '"' であると仮定します。

|"Hello world"|
|" Hello world "|
| "Hello world" |

Copy

次のようになります：

+---------------+
| C1            |
|----+----------|
| Hello world   |
|  Hello world  |
| Hello world   |
+---------------+

Copy

デフォルト:: FALSE

FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE

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

デフォルト:: NONE

NULL_IF = ( [ 'string1' [ , 'string2' ... ] ] )

SQL NULL との間の変換に使用される文字列。Snowflakeはデータロードソースのこれらの文字列を SQL NULL に置き換えます。複数の文字列を指定するには、文字列のリストを括弧で囲み、各値をコンマで区切ります。

Snowflakeは、データ型に関係なく、値のすべてのインスタンスを NULL に変換することに注意してください。たとえば、 2 が値として指定されている場合は、文字列または数値としての 2 のインスタンスすべてが変換されます。

例:

NULL_IF = ('\N', 'NULL', 'NUL', '')

このオプションには空の文字列を含めることができます。

デフォルト:: \N （つまり、 NULL。これは ESCAPE_UNENCLOSED_FIELD 値が \\ （デフォルト）であると想定します）

ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE

入力データファイルの区切り列（つまり、フィールド）の数が対応するテーブルの列の数と一致しない場合に、解析エラーを生成するかどうかを指定するブール値。

FALSE に設定すると、エラーは生成されず、ロードが続行されます。ファイルが正常にロードされた場合：

入力ファイルに、テーブル内の列よりもフィールド数が多いレコードが含まれている場合、一致するフィールドはファイル内の出現順にロードされ、残りのフィールドはロードされません。
入力ファイルにテーブル内の列よりもフィールド数が少ない記録が含まれている場合、テーブル内の一致しない列は NULL 値でロードされます。

このオプションは、入力ファイル内のすべての記録が同じ長さであることを前提としています（つまり、長さの異なる記録を含むファイルは、このオプションに指定された値に関係なくエラーを返します）。

デフォルト:: TRUE

注釈

ロード中にデータを変換する場合（つまり、 COPY INTO <テーブル> コマンドのソースとしてクエリを使用する場合）、このオプションは無視されます。データファイルは、ターゲットテーブルと同数および同順序の列にする必要はありません。

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

無効な UTF -8文字をUnicode置換文字（�）で置き換えるかどうかを指定するブール値。コピーオプションは、1対1の文字置換を実行します。

TRUE に設定すると、Snowflakeは無効な UTF-8文字をUnicode置換文字に置き換えます。

FALSE に設定すると、無効な UTF-8文字エンコードが検出されたときにロード操作でエラーが生成されます。

デフォルト:: FALSE

EMPTY_FIELD_AS_NULL = TRUE | FALSE

入力ファイル内の空フィールドに対して SQL NULL を挿入するかどうかを指定するブール。空フィールドは2つの連続した区切り文字で表されます（例えば、 ,,）。

FALSE に設定すると、Snowflakeは空のフィールドを対応する列タイプにキャストしようとします。タイプ STRING の列に空の文字列が挿入されます。他の列タイプの場合、 COPYINTO <テーブル> コマンドはエラーを生成します。

デフォルト:: TRUE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

データファイルに存在する場合、 BOM （バイト順マーク）をスキップするかどうかを指定するブール値。BOM は、データファイルの先頭にある文字コードで、バイト順とエンコード形式を定義します。

FALSE に設定されている場合、Snowflakeはデータファイル内の BOM を認識し、 BOM がエラーの原因になるか、テーブルの最初の列にマージされる可能性があります。

デフォルト:: TRUE

ENCODING = 'string'

ソースデータの文字セットを指定する文字列（定数）。

文字セット	`ENCODING` 値	サポートされている言語	注意
Big5	`BIG5`	中国語（繁体字）
EUC-JP	`EUCJP`	日本語
EUC-KR	`EUCKR`	韓国語
GB18030	`GB18030`	中国語
IBM420	`IBM420`	アラビア語
IBM424	`IBM424`	ヘブライ語
IBM949	`IBM949`	韓国語
ISO-2022-CN	`ISO2022CN`	中国語（簡体字）
ISO-2022-JP	`ISO2022JP`	日本語
ISO-2022-KR	`ISO2022KR`	韓国語
ISO-8859-1	`ISO88591`	デンマーク語、オランダ語、英語、フランス語、ドイツ語、イタリア語、ノルウェー語、ポルトガル語、スウェーデン語
ISO-8859-2	`ISO88592`	チェコ語、ハンガリー語、ポーランド語、ルーマニア語
ISO-8859-5	`ISO88595`	ロシア語
ISO-8859-6	`ISO88596`	アラビア語
ISO-8859-7	`ISO88597`	ギリシャ語
ISO-8859-8	`ISO88598`	ヘブライ語
ISO-8859-9	`ISO88599`	トルコ語
ISO-8859-15	`ISO885915`	デンマーク語、オランダ語、英語、フランス語、ドイツ語、イタリア語、ノルウェー語、ポルトガル語、スウェーデン語	ユーロ通貨記号を含む8文字を除いて、 ISO-8859-1と同じです。
KOI8-R	`KOI8R`	ロシア語
Shift_JIS	`SHIFTJIS`	日本語
UTF-8	`UTF8`	すべての言語	区切りファイル（CSV、 TSVなど）からデータをロードする場合、 UTF-8がデフォルトです。. . サポートされている他のすべてのファイル形式（JSON、Avroなど）からデータをロードおよびアンロードする場合、サポートされる文字セットは UTF-8のみです。
UTF-16	`UTF16`	すべての言語
UTF-16BE	`UTF16BE`	すべての言語
UTF-16LE	`UTF16LE`	すべての言語
UTF-32	`UTF32`	すべての言語
UTF-32BE	`UTF32BE`	すべての言語
UTF-32LE	`UTF32LE`	すべての言語
windows-874	`WINDOWS874`	タイ
windows-949	`WINDOWS949`	韓国語
windows-1250	`WINDOWS1250`	チェコ語、ハンガリー語、ポーランド語、ルーマニア語
windows-1251	`WINDOWS1251`	ロシア語
windows-1252	`WINDOWS1252`	デンマーク語、オランダ語、英語、フランス語、ドイツ語、イタリア語、ノルウェー語、ポルトガル語、スウェーデン語
windows-1253	`WINDOWS1253`	ギリシャ語
windows-1254	`WINDOWS1254`	トルコ語
windows-1255	`WINDOWS1255`	ヘブライ語
windows-1256	`WINDOWS1256`	アラビア語

デフォルト:: UTF8

注釈

Snowflakeは、すべてのデータを UTF -8文字セットで内部に保存します。データは、Snowflakeにロードされる前に UTF-8に変換されます。

TYPE = JSON¶

サポートされる値	注意
`AUTO`	現在は自動検出できないBrotliで圧縮されたファイルを除き、圧縮アルゴリズムは自動的に検出されます。Brotliで圧縮されたファイルをロードする場合は、 `AUTO` ではなく `BROTLI` を明示的に使用してください。
`GZIP`
`BZ2`
`BROTLI`
`ZSTD`
`DEFLATE`	Deflate圧縮されたファイル（zlibヘッダー、 RFC1950を使用）。
`RAW_DEFLATE`	生Deflate圧縮ファイル（ヘッダーなし、 RFC1951）。
`NONE`	データをロードするためのファイルが圧縮されていないことを示します。

デフォルト:: AUTO

DATE_FORMAT = 'string' | AUTO

データファイルの日付文字列値の形式を定義します。値が指定されていない場合、または AUTO の場合は、 DATE_INPUT_FORMAT パラメーターの値が使用されます。

このファイル形式オプションは、次のアクションにのみ適用されます。

MATCH_BY_COLUMN_NAME コピーオプションを使用して、 JSON データを個別の列にロードします。
COPY ステートメント（つまり、 COPY 変換）でクエリを指定して、 JSON データを個別の列にロードします。

デフォルト:: AUTO

TIME_FORMAT = 'string' | AUTO

データファイルの時間文字列値の形式を定義します。値が指定されていない場合、または AUTO の場合は、 TIME_INPUT_FORMAT パラメーターの値が使用されます。

このファイル形式オプションは、次のアクションにのみ適用されます。

MATCH_BY_COLUMN_NAME コピーオプションを使用して、 JSON データを個別の列にロードします。
COPY ステートメント（つまり、 COPY 変換）でクエリを指定して、 JSON データを個別の列にロードします。

デフォルト:: AUTO

TIMESTAMP_FORMAT = string' | AUTO

データファイルのタイムスタンプ文字列値の形式を定義します。値が指定されていない場合、または AUTO の場合は、 TIMESTAMP_INPUT_FORMAT パラメーターの値が使用されます。

このファイル形式オプションは、次のアクションにのみ適用されます。

MATCH_BY_COLUMN_NAME コピーオプションを使用して、 JSON データを個別の列にロードします。
COPY ステートメント（つまり、 COPY 変換）でクエリを指定して、 JSON データを個別の列にロードします。

デフォルト:: AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

データファイル内のバイナリ文字列値のエンコード形式を定義します。このオプションは、テーブルのバイナリ列にデータをロードするときに使用できます。

このファイル形式オプションは、次のアクションにのみ適用されます。

MATCH_BY_COLUMN_NAME コピーオプションを使用して、 JSON データを個別の列にロードします。
COPY ステートメント（つまり、 COPY 変換）でクエリを指定して、 JSON データを個別の列にロードします。

デフォルト:: HEX

TRIM_SPACE = TRUE | FALSE

文字列から先頭と末尾の空白を削除するかどうかを指定するブール値。

たとえば、外部データベースソフトウェアがフィールドを引用符で囲み、先頭にスペースを挿入する場合、Snowflakeは引用符の先頭文字ではなく、先頭のスペースをフィールドの先頭として読み取ります（つまり、引用符はフィールドデータの文字列の一部として解釈されます）。このオプションを TRUE に設定すると、データのロード中に不要なスペースが削除されます。

このファイル形式オプションは、 MATCH_BY_COLUMN_NAME コピーオプションを使用して JSON データを個別の列にロードする場合にのみ、次のアクションに適用されます。

デフォルト:: FALSE

MULTI_LINE = TRUE | FALSE

複数行を許すかどうかを指定するブール。

MULTI_LINE が FALSE に設定され、 JSON レコード内に改行がある場合、改行を含むレコードはエラーとして解釈されます。

デフォルト:: TRUE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

例:

NULL_IF = ('\N', 'NULL', 'NUL', '')

このオプションには空の文字列を含めることができます。

デフォルト:: \N （つまり、 NULL）

ENABLE_OCTAL = TRUE | FALSE

8進数の解析を可能にするブール値。

デフォルト:: FALSE

ALLOW_DUPLICATE = TRUE | FALSE

オブジェクトフィールド名の重複を許可するブール値（最後のフィールドのみが保持されます）。

デフォルト:: FALSE

STRIP_OUTER_ARRAY = TRUE | FALSE

JSON パーサーに外括弧 [ ] を削除するように指示するブール値。

デフォルト:: FALSE

STRIP_NULL_VALUES = TRUE | FALSE

null 値を含むオブジェクトフィールドまたは配列要素を削除するように JSON パーサーに指示するブール値。たとえば、 TRUE に設定されている場合：

前	後
`[null]`	`[]`
`[null,null,3]`	`[,,3]`
`{"a":null,"b":null,"c":123}`	`{"c":123}`
`{"a":[1,null,2],"b":{"x":null,"y":88}}`	`{"a":[1,,2],"b":{"y":88}}`

デフォルト:: FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

無効な UTF -8文字をUnicode置換文字（�）で置き換えるかどうかを指定するブール値。コピーオプションは、1対1の文字置換を実行します。

TRUE に設定すると、Snowflakeは無効な UTF-8文字をUnicode置換文字に置き換えます。

FALSE に設定すると、無効な UTF-8文字エンコードが検出されたときにロード操作でエラーが生成されます。

デフォルト:: FALSE

IGNORE_UTF8_ERRORS = TRUE | FALSE

UTF-8エンコードエラーがエラー状態を引き起こすかどうかを指定するブール値。REPLACE_INVALID_CHARACTERS の代替構文です。

TRUE に設定すると、無効な UTF-8シーケンスはUnicode文字 U+FFFD （つまり、「置換文字」）で警告なしに置き換えられます。

FALSE に設定すると、無効な UTF-8文字エンコードが検出されたときにロード操作でエラーが生成されます。

デフォルト:: FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

入力ファイルに存在する BOM （バイト順マーク）をスキップするかどうかを指定するブール値。BOM は、データファイルの先頭にある文字コードで、バイト順とエンコード形式を定義します。

デフォルト:: TRUE

TYPE = AVRO¶

サポートされる値	注意
`AUTO`	現在は自動検出できないBrotliで圧縮されたファイルを除き、圧縮アルゴリズムは自動的に検出されます。Brotliで圧縮されたファイルをロードする場合は、 `AUTO` ではなく `BROTLI` を明示的に使用してください。
`GZIP`
`BROTLI`
`ZSTD`
`DEFLATE`	Deflate圧縮されたファイル（zlibヘッダー、 RFC1950を使用）。
`RAW_DEFLATE`	生Deflate圧縮ファイル（ヘッダーなし、 RFC1951）。
`NONE`	ロードするデータファイルは圧縮されていません。

デフォルト:: AUTO。

注釈

ファイル圧縮とコーデック圧縮の両方が決定されるため、デフォルトの AUTO オプションを使用することをお勧めします。圧縮オプションの指定は、ブロック（コーデック）の圧縮ではなく、ファイルの圧縮を意味します。

TRIM_SPACE = TRUE | FALSE

文字列から先頭と末尾の空白を削除するかどうかを指定するブール値。

このファイル形式オプションは、 MATCH_BY_COLUMN_NAME コピーオプションを使用してAvroデータを個別の列にロードする場合にのみ、次のアクションに適用されます。

デフォルト:: FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

無効な UTF -8文字をUnicode置換文字（�）で置き換えるかどうかを指定するブール値。コピーオプションは、1対1の文字置換を実行します。

TRUE に設定すると、Snowflakeは無効な UTF-8文字をUnicode置換文字に置き換えます。

FALSE に設定すると、無効な UTF-8文字エンコードが検出されたときにロード操作でエラーが生成されます。

デフォルト:: FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

例:

NULL_IF = ('\N', 'NULL', 'NUL', '')

このオプションには空の文字列を含めることができます。

デフォルト:: \N （つまり、 NULL）

TYPE = ORC¶

TRIM_SPACE = TRUE | FALSE

文字列から先頭と末尾の空白を削除するかどうかを指定するブール値。

このファイル形式オプションは、 MATCH_BY_COLUMN_NAME コピーオプションを使用してOrcデータを個別の列にロードする場合にのみ、次のアクションに適用されます。

デフォルト:: FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

無効な UTF -8文字をUnicode置換文字（�）で置き換えるかどうかを指定するブール値。コピーオプションは、1対1の文字置換を実行します。

TRUE に設定すると、Snowflakeは無効な UTF-8文字をUnicode置換文字に置き換えます。

FALSE に設定すると、無効な UTF-8文字エンコードが検出されたときにロード操作でエラーが生成されます。

デフォルト:: FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

例:

NULL_IF = ('\N', 'NULL', 'NUL', '')

このオプションには空の文字列を含めることができます。

デフォルト:: \N （つまり、 NULL）

TYPE = PARQUET¶

COMPRESSION = AUTO | SNAPPY | NONE

サポートされる値	注意
`AUTO`	圧縮アルゴリズムが自動的に検出されました。対応する圧縮アルゴリズム:Brotli、gzip、Lempel-Ziv-Oberhumer（LZO）、LZ4、Snappy、またはZstandard v0.8（およびそれ以上）。
`SNAPPY`
`NONE`	ロードするデータファイルは圧縮されていません。

デフォルト:: AUTO

BINARY_AS_TEXT = TRUE | FALSE

論理データ型が定義されていない列を UTF-8テキストとして解釈するかどうかを指定するブール値。FALSE に設定すると、Snowflakeはこれらの列をバイナリデータとして解釈します。

デフォルト:: TRUE

注釈

Snowflakeは、潜在的な変換の問題を回避するために、 BINARY_AS_TEXT を FALSE に設定することをお勧めします。

TRIM_SPACE = TRUE | FALSE

文字列から先頭と末尾の空白を削除するかどうかを指定するブール値。

このファイル形式オプションは、 MATCH_BY_COLUMN_NAME コピーオプションを使用してParquetデータを個別の列にロードする場合にのみ、次のアクションに適用されます。

デフォルト:: FALSE

USE_LOGICAL_TYPE = TRUE | FALSE

Parquet論理型を使用するかどうかを指定するブール値。このファイル形式オプションを使用すると、Snowflakeはデータのロード中にParquet論理型を解釈できます。詳細については、 Parquet理論型の定義をご参照ください。Parquet論理型を有効にするには、新しいファイル形式オプションを作成するときに USE_LOGICAL_TYPE を TRUE に設定します。

デフォルト:: FALSE

USE_VECTORIZED_SCANNER = TRUE | FALSE

Parquetファイルのロード時にベクトル化されたスキャナーを使用するかどうかを指定するブール値。

デフォルト値は FALSE です。将来の BCR では、デフォルト値は TRUE になります。新しいワークロードには USE_VECTORIZED_SCANNER = TRUE を設定し、既存のワークロードにはテスト後に設定することを推奨します。

ベクトル化されたスキャナーを使用すると、Parquetファイルをロードする際の待ち時間を大幅に短縮できます。このスキャナーは、 Parquet ファイルの列指向形式に適しているからです。スキャナーは、選択された列のサブセットなど、Parquetファイルの関連セクションのみをメモリにダウンロードします。

USE_VECTORIZED_SCANNER が TRUE に設定されている場合、ベクトル化されたスキャナーの動作は以下のようになります。

設定された実際の値にかかわらず、 BINARY_AS_TEXT オプションは常に FALSE として扱われ、 USE_LOGICAL_TYPE オプションは常に TRUE として扱われます。
ベクトル化されたスキャナーはParquetマップタイプをサポートしています。マップタイプのスキャンの出力は以下の通りです。
"my_map":
  {
   "k1": "v1",
   "k2": "v2"
  }
Copy
ベクトル化されたスキャナーは、次の例が示すように、出力で NULL 値を表示します。
"person":
 {
  "name": "Adam",
  "nickname": null,
  "age": 34,
  "phone_numbers":
  [
    "1234567890",
    "0987654321",
    null,
    "6781234590"
  ]
  }
Copy
ベクトル化されたスキャナーは、時間とタイムスタンプを次のように扱います。

Parquet

Snowflakeのベクトル化されたスキャナー

TimeType(isAdjustedToUtc=True/False, unit=MILLIS/MICROS/NANOS)

TIME

TimestampType(isAdjustedToUtc=True, unit=MILLIS/MICROS/NANOS)

TIMESTAMP_LTZ

TimestampType(isAdjustedToUtc=False, unit=MILLIS/MICROS/NANOS)

TIMESTAMP_NTZ

INT96

TIMESTAMP_LTZ

Parquet	Snowflakeのベクトル化されたスキャナー
TimeType(isAdjustedToUtc=True/False, unit=MILLIS/MICROS/NANOS)	TIME
TimestampType(isAdjustedToUtc=True, unit=MILLIS/MICROS/NANOS)	TIMESTAMP_LTZ
TimestampType(isAdjustedToUtc=False, unit=MILLIS/MICROS/NANOS)	TIMESTAMP_NTZ
INT96	TIMESTAMP_LTZ

USE_VECTORIZED_SCANNER が FALSE に設定されている場合、スキャナーは以下の動作をします。

このオプションはParquetマップをサポートしていません。マップタイプのスキャンの出力は以下の通りです。
"my_map":
 {
  "key_value":
  [
   {
          "key": "k1",
          "value": "v1"
      },
      {
          "key": "k2",
          "value": "v2"
      }
    ]
  }
Copy
次の例が示すように、このオプションはスキャン出力で NULL 値を明示的に表示しません。
"person":
 {
  "name": "Adam",
  "age": 34
  "phone_numbers":
  [
   "1234567890",
   "0987654321",
   "6781234590"
  ]
 }
Copy
このオプションは、時間とタイムスタンプを次のように扱います。

Parquet

USE_LOGICAL_TYPE = TRUE の場合

USE_LOGICAL_TYPE = FALSE の場合

TimeType(isAdjustedToUtc=True/False, unit=MILLIS/MICROS)

TIME

TIME （ConvertedType がある場合）

INTEGER （ConvertedType がない場合）

TimeType(isAdjustedToUtc=True/False, unit=NANOS)

TIME

INTEGER

TimestampType(isAdjustedToUtc=True, unit=MILLIS/MICROS)

TIMESTAMP_LTZ

TIMESTAMP_NTZ

TimestampType(isAdjustedToUtc=True, unit=NANOS)

TIMESTAMP_LTZ

INTEGER

TimestampType(isAdjustedToUtc=False, unit=MILLIS/MICROS)

TIMESTAMP_NTZ

TIMESTAMP_LTZ （ConvertedType がある場合）

INTEGER （ConvertedType がない場合）

TimestampType(isAdjustedToUtc=False, unit=NANOS)

TIMESTAMP_NTZ

INTEGER

INT96

TIMESTAMP_NTZ

TIMESTAMP_NTZ

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

Parquet	USE_LOGICAL_TYPE = TRUE の場合	USE_LOGICAL_TYPE = FALSE の場合
TimeType(isAdjustedToUtc=True/False, unit=MILLIS/MICROS)	TIME	TIME （ConvertedType がある場合） INTEGER （ConvertedType がない場合）
TimeType(isAdjustedToUtc=True/False, unit=NANOS)	TIME	INTEGER
TimestampType(isAdjustedToUtc=True, unit=MILLIS/MICROS)	TIMESTAMP_LTZ	TIMESTAMP_NTZ
TimestampType(isAdjustedToUtc=True, unit=NANOS)	TIMESTAMP_LTZ	INTEGER
TimestampType(isAdjustedToUtc=False, unit=MILLIS/MICROS)	TIMESTAMP_NTZ	TIMESTAMP_LTZ （ConvertedType がある場合） INTEGER （ConvertedType がない場合）
TimestampType(isAdjustedToUtc=False, unit=NANOS)	TIMESTAMP_NTZ	INTEGER
INT96	TIMESTAMP_NTZ	TIMESTAMP_NTZ

無効な UTF -8文字をUnicode置換文字（�）で置き換えるかどうかを指定するブール値。コピーオプションは、1対1の文字置換を実行します。

TRUE に設定すると、Snowflakeは無効な UTF-8文字をUnicode置換文字に置き換えます。

FALSE に設定すると、無効な UTF-8文字エンコードが検出されたときにロード操作でエラーが生成されます。

デフォルト:: FALSE

NULL_IF = ( 'string1' [ , 'string2' , ... ] )

例:

NULL_IF = ('\N', 'NULL', 'NUL', '')

このオプションには空の文字列を含めることができます。

デフォルト:: \N （つまり、 NULL）

TYPE = XML¶

サポートされる値	注意
`AUTO`	現在は自動検出できないBrotliで圧縮されたファイルを除き、圧縮アルゴリズムは自動的に検出されます。Brotliで圧縮されたファイルをロードする場合は、 `AUTO` ではなく `BROTLI` を明示的に使用してください。
`GZIP`
`BZ2`
`BROTLI`
`ZSTD`
`DEFLATE`	Deflate圧縮されたファイル（zlibヘッダー、 RFC1950を使用）。
`RAW_DEFLATE`	生Deflate圧縮ファイル（ヘッダーなし、 RFC1951）。
`NONE`	ロードするデータファイルは圧縮されていません。

デフォルト:: AUTO

IGNORE_UTF8_ERRORS = TRUE | FALSE

UTF-8エンコードエラーがエラー状態を引き起こすかどうかを指定するブール値。REPLACE_INVALID_CHARACTERS の代替構文です。

TRUE に設定すると、無効な UTF-8シーケンスはUnicode文字 U+FFFD （つまり、「置換文字」）で警告なしに置き換えられます。

FALSE に設定すると、無効な UTF-8文字エンコードが検出されたときにロード操作でエラーが生成されます。

デフォルト:: FALSE

PRESERVE_SPACE = TRUE | FALSE

XML パーサーが要素コンテンツの先頭と後続のスペースを保持するかどうかを指定するブール値。

デフォルト:: FALSE

STRIP_OUTER_ELEMENT = TRUE | FALSE

XML パーサーが外側の XML 要素を取り除き、2番目のレベルの要素を別のドキュメントとして公開するかどうかを指定するブール値。

デフォルト:: FALSE

DISABLE_AUTO_CONVERT = TRUE | FALSE

XML パーサーがテキストからネイティブ表現への数値およびブール値の自動変換を無効にするかどうかを指定するブール値。

デフォルト:: FALSE

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

無効な UTF -8文字をUnicode置換文字（�）で置き換えるかどうかを指定するブール値。コピーオプションは、1対1の文字置換を実行します。

TRUE に設定すると、Snowflakeは無効な UTF-8文字をUnicode置換文字に置き換えます。

FALSE に設定すると、無効な UTF-8文字エンコードが検出されたときにロード操作でエラーが生成されます。

デフォルト:: FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

デフォルト:: TRUE

コピーオプション（`copyOptions`）¶

次のコピーオプションを1つ以上指定できます（空白、コンマ、または改行で区切り）。

CLUSTER_AT_INGEST_TIME = TRUE | FALSE

定義:

クラスタリングキーで構成されているテーブルの取り込み中に、データを直接事前クラスタリングするかどうかを指定するブール値。

TRUE に設定されている場合、このオプションは Snowpipe Streaming（高性能アーキテクチャを持つ）に、データがコミットされる前に、ターゲットテーブルのクラスタリングキーに基づくデータをソートさせます。これにより、取り込み時にデータが最適な状態に整理され、ターゲットテーブルでのクエリパフォーマンスが大幅に向上します。

この機能は Snowpipe Streamingのハイパフォーマンスアーキテクチャでのみ使用できます。このオプションを有効にするには、ターゲットテーブルの構成でクラスタリングキーが定義されている必要があります。

デフォルト:

FALSE

重要

事前クラスタリング機能を使用する場合は、宛先テーブルで自動クラスタリング機能を無効にしていないことを確認してください。自動クラスタリングを無効にすると、時間の経過とともにクエリのパフォーマンスが低下する可能性があります。

例:

CREATE OR REPLACE PIPE TEST_PRECLUSTERED_PIPE
AS
    COPY INTO TEST_PRECLUSTERED_TABLE (num) FROM (
            SELECT $1:num::number as num FROM TABLE(
                DATA_SOURCE(
                    TYPE => 'STREAMING')
            ))
      CLUSTER_AT_INGEST_TIME=TRUE;

Copy

ENFORCE_LENGTH = TRUE | FALSE

定義:

リバースロジックを使用した TRUNCATECOLUMNS の代替構文（他のシステムとの互換性のため）

ターゲット列の長さを超えるテキスト文字列を切り捨てるかどうかを指定するブール値：

TRUE の場合、ロードされた文字列がターゲット列の長さを超えると、 COPY ステートメントはエラーを生成します。
FALSE の場合、文字列はターゲット列の長さに自動的に切り捨てられます。

このコピーオプションは、 CSV データと、リレーショナルテーブルの個別の列にロードされた場合の半構造化データの文字列値をサポートします。

デフォルト:

TRUE

注釈

ターゲット文字列の列の長さが最大に設定されている場合（例: VARCHAR (134217728)）、着信文字列はこの長さを超えることはできません。超えると、 COPY コマンドはエラーを生成します。
このパラメーターは機能的には TRUNCATECOLUMNS と同等ですが、逆の動作をします。他のデータベースとの互換性のために提供されています。必要な出力を生成するには、COPY ステートメントにこれら2つのパラメーターのいずれかを含めるだけです。

FILE_PROCESSOR = (SCANNER = custom_scanner_type SCANNER_OPTIONS = (scanner_options))

定義:

非構造化データの処理に使用するスキャナーとスキャナーオプションを指定します。

SCANNER （必須）: 非構造化データの処理に使用するカスタムスキャナーのタイプを指定します。現在、 document_ai カスタムスキャナータイプのみがサポートされています。
SCANNER_OPTIONS: カスタム・スキャナー・タイプのプロパティを指定します。例えば、 document_ai のタイプとして SCANNER を指定する場合、 document_ai のプロパティを指定する必要があります。次のリストは、document_ai のプロパティの事前定義されたセットを示しています。
- project_name: ドキュメント AI モデルを作成するプロジェクトの名前。
- model_name （document_ai では必須）:Document の AI モデル名。
- model_version （document_ai では必須）:Document AI モデルのバージョン。

詳細については、構造化されていないデータをドキュメント AI で読み込むをご参照ください。

注釈

このコピーオプションは MATCH_BY_COLUMN_NAME では動作しません。

FORCE = TRUE | FALSE

定義:: 以前にロードされたかどうか、ロード後に変更されなかったかどうかに関係なく、すべてのファイルをロードするよう指定するブール値。このオプションはファイルを再ロードし、テーブル内のデータを複製する可能性があります。
デフォルト:: FALSE

INCLUDE_METADATA = ( column_name = METADATA$field [ , column_name = METADATA$field ... ] )

定義:

ターゲットテーブルの既存の列と METADATA$ 列間のユーザー定義のマッピング。このコピーオプションは、 MATCH_BY_COLUMN_NAME コピーオプションと合わせてのみ使用できます。次のリストは、METADATA$field の有効な入力を示しています。

METADATA$FILENAME
METADATA$FILE_ROW_NUMBER
METADATA$FILE_CONTENT_KEY
METADATA$FILE_LAST_MODIFIED
METADATA$START_SCAN_TIME

メタデータ列の詳細については、ステージングされたファイルのメタデータのクエリをご参照ください。

このコピーオプションでマッピングが定義されると、次の例が示すように、 column_name 列に指定されたメタデータ値が入力されます。

COPY INTO table1 FROM @stage1
MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE
INCLUDE_METADATA = (
    ingestdate = METADATA$START_SCAN_TIME, filename = METADATA$FILENAME);

Copy

+-----+-----------------------+---------------------------------+-----+
| ... | FILENAME              | INGESTDATE                      | ... |
|---------------------------------------------------------------+-----|
| ... | example_file.json.gz  | Thu, 22 Feb 2024 19:14:55 +0000 | ... |
+-----+-----------------------+---------------------------------+-----+

デフォルト:

NULL

注釈

INCLUDE_METADATA ターゲット列名は、まずテーブルに存在する必要があります。ターゲット列名が存在しない場合は自動的に追加されません。
INCLUDE_METADATA 列には一意な列名を使用します。INCLUDE_METADATA ターゲット列にデータファイルの列と競合する名前がある場合は、INCLUDE_METADATA で定義された METADATA$ 値が優先されます。
INCLUDE_METADATA で CSV ファイルをロードする場合は、ファイル形式オプション ERROR_ON_COLUMN_COUNT_MISMATCH を FALSE に設定します。

LOAD_MODE = { FULL_INGEST | ADD_FILES_COPY }

定義:

ParquetファイルからSnowflake管理 Icebergテーブルにデータをロードする場合に使用するモードを指定します。

FULL_INGEST:Snowflakeはファイルをスキャンし、Icebergテーブルのベーステーブルの基になるParquetデータを書き換えます。Icebergテーブルにデータファイルを登録する前にデータの変換が必要な場合は、このオプションを使用します。
ADD_FILES_COPY:Snowflakeは、元のParquetファイルをIcebergテーブルのベーステーブルにサーバーサイドでコピーし、そのファイルをテーブルに登録します。このアクションにより、raw ParquetファイルのIcebergテーブルへのクロスリージョンまたはクロスクラウド取り込みが可能になります。

注釈

この ADD_FILES_COPY オプションは、Iceberg互換のraw Parquetファイルから変換なしでデータをロードする場合のみサポートされます。raw Iceberg互換ParquetファイルはIcebergカタログに登録されませんが、Iceberg互換データタイプを含んでいます。

ファイル読み取りのオーバーヘッドを避けるには、このオプションを使用します。ストレージコストを最小限に抑えるには、このオプションで PURGE = TRUE を使用します。こうすると、データのロードが成功した後、Snowflakeはデータファイルを元の場所から自動的に削除します。

その他の使用上の注意については、 LOAD_MODE の使用上の注意をご参照ください。例については、 IcebergテーブルへのIceberg互換Parquetデータのロードをご参照ください。

デフォルト:: FULL_INGEST

LOAD_UNCERTAIN_FILES = TRUE | FALSE

定義:

ロード状態が不明なファイルをロードすることを指定するブール値。COPY コマンドはデフォルトでこれらのファイルをスキップします。

次の条件のすべてが当てはまる場合、ロードステータスは不明です。

ファイルの LAST_MODIFIED 日付（つまり、ファイルがステージされた日付）が64日よりも前。
データの初期セットがテーブルにロードされたのが64日よりも前。
ファイルが既にテーブルに正常にロードされている場合、このイベントが発生したのが65日以上前。

ロードステータスが既知かどうかに関係なく、 COPY コマンドにすべてのファイルを強制的にロードさせるには、代わりに FORCE オプションを使用します。

ロードステータスの不確実性の詳細については、古いファイルをロードするをご参照ください。

デフォルト:

FALSE

MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE

定義:

データで表される対応する列と一致するターゲットテーブルの列に半構造化データをロードするかどうかを指定する文字列。

重要

すべての場合において、ロード中のデータ変換に MATCH_BY_COLUMN_NAME コピーオプションと SELECT ステートメントを合わせて使用することはしないでください。この2つのオプションを個別に使用することはできますが、併用することはできません。これを実行しようとすると、エラー、 SQL compilation error: match_by_column_name is not supported with copy transform. が発生します.

たとえば、次の構文は許可されていません。

COPY INTO [<namespace>.]<table_name> [ ( <col_name> [ , <col_name> ... ] ) ]
FROM ( SELECT [<alias>.]$<file_col_num>[.<element>] [ , [<alias>.]$<file_col_num>[.<element>] ... ]
    FROM { internalStage | externalStage } )
[ FILES = ( '<file_name>' [ , '<file_name>' ] [ , ... ] ) ]
[ PATTERN = '<regex_pattern>' ]
[ FILE_FORMAT = ( { FORMAT_NAME = '[<namespace>.]<file_format_name>' |
            TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] } ) ]
MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
[ other copyOptions ]

Copy

詳細については、ロード中のデータの変換をご参照ください。

このコピーオプションは、次のデータ形式でサポートされています。

JSON
Avro
ORC
Parquet
CSV

列が一致するには、次の条件を満たす必要があります。

データで表される列は、テーブルの列とまったく同じ名前である必要があります。コピーオプションは、列名の大文字と小文字を区別します。列の順序は関係ありません。
テーブルの列には、データで表される列の値と互換性のあるデータ型が必要です。例えば、文字列、数値、ブール値はすべてバリアント列にロードできます。

値:

CASE_SENSITIVE | CASE_INSENSITIVE

データで表される対応する列に一致するターゲットテーブルの列に半構造化データをロードします。列名は、大文字と小文字が区別される（CASE_SENSITIVE）または大文字と小文字が区別されない（CASE_INSENSITIVE）です。

COPY 操作は、ターゲットテーブルの少なくとも1つの列がデータファイルで表される列と一致することを確認します。一致が見つかった場合、データファイルの値が1つまたは複数の列にロードされます。一致が見つからない場合、ファイル内の各レコードの NULL 値のセットがテーブルにロードされます。

注釈

一致しない追加の列がデータファイルに存在する場合、これらの列の値はロードされません。
一致しない追加の列がターゲットテーブルに存在する場合、 COPY 操作はこれらの列に NULL 値を挿入します。これらの列は NULL 値をサポートする必要があります。

NONE

COPY 操作は、半構造化データをバリアント列にロードするか、クエリが COPY ステートメントに含まれている場合にデータを変換します。

デフォルト:

NONE

注釈

現在、次の制限が適用されます。

ターゲットテーブルにロードするのではなく、ステージングされたデータを検証するために、MATCH_BY_COLUMN_NAME を COPY ステートメントで VALIDATION_MODE パラメーターと共に使用することはできません。

:emph:` Parquetデータのみ。MATCH_BY_COLUMN_NAME が :code:`CASE_SENSITIVE または CASE_INSENSITIVE に設定されている場合、空の列値（例："col1": ""）はエラーを生成します。

ON_ERROR = CONTINUE | SKIP_FILE | SKIP_FILE_num | 'SKIP_FILE_num%' | ABORT_STATEMENT

使用:

データのロードのみ

定義:

ロード操作のエラー処理を指定する文字列（定数）。

重要

ON_ERROR コピーオプションの値を慎重に検討してください。デフォルト値は一般的なシナリオでは適切ですが、常に最良のオプションであるとは限りません。

値:

CONTINUE

エラーが見つかった場合は、ファイルのロードを続行します。COPY ステートメントは、データファイルごとに見つかった最大1つのエラーのエラーメッセージを返します。

ROWS_PARSED 列の値と ROWS_LOADED 列の値の差は、検出されたエラーを含む行の数を表します。ただし、これらの各行には複数のエラーが含まれる可能性があります。データファイルのすべてのエラーを表示するには、 VALIDATION_MODE パラメーターを使用するか、 VALIDATE 関数をクエリします。
SKIP_FILE

エラーが見つかった場合はファイルをスキップします。

SKIP_FILE アクションは、エラーが見つかったかどうかに関係なく、ファイル全体をバッファーします。このため、 SKIP_FILE は CONTINUE または ABORT_STATEMENT よりも低速です。少数のエラーで大型のファイルをスキップすると、遅延が発生し、クレジットが無駄になる可能性があります。論理的な叙述がないファイルから多数の記録をロードする場合（例: ファイルが大まかな間隔で自動的に生成された場合）は、代わりに CONTINUE を指定することを検討してください。

その他のパターン:

SKIP_FILE_num`（例: :code:`SKIP_FILE_10）
ファイル内で見つかったエラー行の数が指定された数以上の場合は、ファイルをスキップします。

'SKIP_FILE_num%'`（例: :code:'SKIP_FILE_10%'`）
ファイル内で見つかったエラー行の割合が指定された割合を超えた場合は、ファイルをスキップします。
ABORT_STATEMENT

データファイルにエラーが見つかった場合は、ロード操作を中止します。

ロード操作は、FILES パラメーターで明示的に指定されたデータファイルが見つからない場合にのみ中止されます。それ以外でデータファイルが見つからない（例: データファイルが存在しない、またはデータファイルにアクセスできない）場合、ロード操作は中止されません。

データファイルが取り込まれないため、終了した操作は COPY_HISTORY に表示されません。QUERY_HISTORY で故障箇所を検索することをお勧めします。

デフォルト:

COPY を使用した一括ロード:: ABORT_STATEMENT
Snowpipe:: SKIP_FILE

PURGE = TRUE | FALSE

定義:

データが正常にロードされた後、ステージからデータファイルを自動的に削除するかどうかを指定するブール値。

このオプションが TRUE に設定されている場合は、正常にロードされたデータファイルの削除を試みます。パージ操作が何らかの理由で失敗した場合、現在エラーは返されません。ステージングされたファイルを定期的にリストし（ LIST を使用）、正常にロードされたファイルがある場合は手動で削除することをお勧めします。

デフォルト:

FALSE

RETURN_FAILED_ONLY = TRUE | FALSE

定義:: ステートメント結果でロードに失敗したファイルのみを返すかどうかを指定するブール値。
デフォルト:: FALSE

SIZE_LIMIT = num

定義:

特定の COPY ステートメントに対してロードされるデータの最大サイズ（バイト単位）を指定する数値（> 0）。しきい値を超えると、 COPY 操作はファイルのロードを中止します。このオプションは、通常、複数の COPY ステートメントを使用してファイルの共通グループをロードするために使用されます。各ステートメントについて、次のステートメントに進む前に、指定された SIZE_LIMIT を超えるまでデータのロードが続行されます。

たとえば、ステージパス内の一連のファイルのサイズがそれぞれ10 MB であるとします。複数の COPY ステートメントが SIZE_LIMIT を 25000000 （25 MB）に設定すると、それぞれが3ファイルをロードします。つまり、 SIZE_LIMIT のしきい値を超えると、各 COPY 操作は中断されます。

ロードするファイルがない場合を除き、 SIZE_LIMIT に指定された値に関係なく、少なくとも1つのファイルがロードされます。

デフォルト:

null（サイズ制限なし）

TRUNCATECOLUMNS = TRUE | FALSE

定義:

リバースロジックを使用した ENFORCE_LENGTH の代替構文（他のシステムとの互換性のため）

ターゲット列の長さを超えるテキスト文字列を切り捨てるかどうかを指定するブール値：

TRUE の場合、文字列はターゲット列の長さに自動的に切り捨てられます。
FALSE の場合、ロードされた文字列がターゲット列の長さを超えると、 COPY ステートメントはエラーを生成します。

このコピーオプションは、 CSV データと、リレーショナルテーブルの個別の列にロードされた場合の半構造化データの文字列値をサポートします。

デフォルト:

FALSE

注釈

ターゲット文字列の列の長さが最大に設定されている場合（例: VARCHAR (134217728)）、着信文字列はこの長さを超えることはできません。超えると、 COPY コマンドはエラーを生成します。
このパラメーターは機能的には ENFORCE_LENGTH と同等ですが、逆の動作をします。他のデータベースとの互換性のために提供されています。必要な出力を生成するには、COPY ステートメントにこれら2つのパラメーターのいずれかを含めるだけです。

使用上の注意¶

一部のユースケースは完全にはサポートされておらず、以下のユースケースを含め、 ON_ERROR の動作に一貫性がなくなったり、予期しない動作が発生したりする可能性があります。
- SELECT ステートメントで DISTINCT キーワードを指定します。
- クラスター化されたテーブルで COPY を使用します。
パーティション化されたIcebergテーブルの場合:
- Snowflakeでパーティション変換時にエラーが発生すると、ON_ERROR = CONTINUE を設定してあっても、COPY ジョブは失敗します。
- LOAD_MODE = ADD_FILES_COPY はサポートされていません。
CSV データをロードする際、ストリームがターゲット・テーブル上にある場合、 ON_ERROR コピー・オプションが期待通りに機能しないことがあります。
Google Cloud Storageからのロードのみ：外部ステージに対して返されるオブジェクトのリストには、1つ以上の「ディレクトリBLOB」が含まれる場合があります。基本的に、スラッシュ文字（/）で終わるパスです。例：
```
LIST @my_gcs_stage;

+---------------------------------------+------+----------------------------------+-------------------------------+
| name                                  | size | md5                              | last_modified                 |
|---------------------------------------+------+----------------------------------+-------------------------------|
| my_gcs_stage/load/                    |  12  | 12348f18bcb35e7b6b628ca12345678c | Mon, 11 Sep 2019 16:57:43 GMT |
| my_gcs_stage/load/data_0_0_0.csv.gz   |  147 | 9765daba007a643bdff4eae10d43218y | Mon, 11 Sep 2019 18:13:07 GMT |
+---------------------------------------+------+----------------------------------+-------------------------------+
```
Copy
これらのは、Googleが提供する他のツールを使用するのではなく、 Google Cloud console でディレクトリが作成されるときにリストされます。

オブジェクトリストにディレクトリ BLOB が含まれていると、ステージを参照する COPY ステートメントが失敗する可能性があります。エラーを回避するために、ステージのファイルリストにディレクトリ BLOB が含まれる場合、ファイルパターンマッチングを使用して、含めるファイル（つまり PATTERN 句）を識別することをお勧めします。例については、このトピックのパターンマッチングを使用したロードをご参照ください。または、 COPY ステートメントで ON_ERROR = SKIP_FILE に設定します。
STORAGE_INTEGRATION 、 CREDENTIALS、および ENCRYPTION は、プライベート/保護されたストレージの場所から直接ロードする場合にのみ適用されます。
- パブリックバケットからロードする場合は、セキュアアクセスは必要ありません。
- 名前付きの外部ステージからロードする場合、ステージはバケットへのアクセスに必要なすべての認証情報を提供します。
COPY コマンドの実行中にエラーが発生した場合、コマンドの完了後、 VALIDATE テーブル関数を使用してエラーを生成したファイルを検証できます。

注釈

VALIDATE 関数は、標準のデータロードの実行に使用される COPY コマンドの出力のみを返します。データのロード中に変換を実行する COPY コマンドをサポートしません（データ列のサブセットの読み込みやデータ列の並べ替えなど）。
コピーオプションの1つとして明示的に FORCE = TRUE を指定しない限り、コマンドは既にテーブルにロードされたステージングされたデータファイルを無視します。データを再ロードするには、 FORCE = TRUE を指定するか、ファイルを変更して再度ステージングする必要があります。これにより、新しいチェックサムが生成されます。
COPY コマンドは、Parquetファイルのデータ型変換を検証しません。
ハイブリッド・テーブルのロードについては、データのロードをご参照ください。

Icebergテーブルでは、VALIDATION_MODE はサポートされていません。
Iceberg互換のParquetファイルから LOAD_MODE を使ってロードします。
- LOAD_MODE = ADD_FILES_COPY オプションを使用する場合は、以下の前提条件を満たす必要があります。
  - ターゲットテーブルは、ソースParquetファイルのデータ型と互換性のある列データ型を持つ、Snowflake管理のIcebergテーブルにする必要があります。詳細については、 Apache Iceberg™ テーブルのデータ型をご参照ください。
  - ソースファイルの形式はIceberg互換のParquetにする必要があり、ベクトル化されたスキャナー FILE_FORMAT = ( TYPE = PARQUET USE_VECTORIZED_SCANNER = TRUE) を使用する必要があります。
  - MATCH_BY_COLUMN_NAME オプションを CASE_SENSITIVE に設定する必要があります。
- LOAD_MODE = ADD_FILES_COPY を使用する場合は、以下のオプションはサポートされません。
  - クラウドストレージの場所とストレージ統合を指定した、ステージングされていないデータのコピー。
  - FILE_FORMAT = ( TYPE = PARQUET USE_VECTORIZED_SCANNER = TRUE) 以外のファイル形式構成。
  - MATCH_BY_COLUMN_NAME = CASE_INSENSITIVE | NONE。
  - ON_ERROR = CONTINUE | SKIP_FILE_N | SKIP_FILE_X%。
  - データをロードする前のデータの変換またはフィルター。データを変換するには、代わりに FULL_INGEST オプションを使用します。
- ADD_FILES_COPY の場合あｈ、より大きなウェアハウスを使用しても、 COPY クエリの所要時間は大幅には減少しません。COPY 操作の大部分はクラウドサービスのコンピューティングリソースに依存しています。
ストレージ統合を使用する外部ステージでこのコマンドを実行するには、ストレージ統合の USAGE 権限を持つか継承するロールを使用する必要があります。

詳細については、ステージ権限をご参照ください。
アウトバウンドプライベート接続の場合、外部の場所（外部ストレージ URI）からの直接の読み込みはサポートされていません。代わりに、外部プライベート接続用に構成されたストレージ統合の外部ステージを使用します。

出力¶

このコマンドは、次の列を返します。

列名	データ型	説明
FILE	TEXT	ソースファイルの名前およびファイルへの相対パス
STATUS	TEXT	ステータス：ロード済み、ロード失敗、または部分的にロード済み
ROWS_PARSED	NUMBER	ソースファイルから解析された行数
ROWS_LOADED	NUMBER	ソースファイルからロードされた行数
ERROR_LIMIT	NUMBER	エラーの数がこの制限に達した場合、中止します
ERRORS_SEEN	NUMBER	ソースファイル内のエラー行の数
FIRST_ERROR	TEXT	ソースファイルの最初のエラー
FIRST_ERROR_LINE	NUMBER	最初のエラーの行番号
FIRST_ERROR_CHARACTER	NUMBER	最初のエラー文字の位置
FIRST_ERROR_COLUMN_NAME	TEXT	最初のエラーの列名

例¶

データロード変換の例については、ロード中のデータの変換をご参照ください。

内部ステージからのファイルのロード¶

注釈

これらの例では、 PUT コマンドを使用して以前にファイルがステージにコピーされたことを想定しています。

名前付きの内部ステージからテーブルにファイルをロードします。

COPY INTO mytable
FROM @my_int_stage;

Copy

テーブルのステージからテーブルにファイルをロードします。

COPY INTO mytable
FILE_FORMAT = (TYPE = CSV);
Copy
注釈

テーブルの場所にあるファイルからデータをコピーする場合、Snowflakeはテーブルの場所にあるファイルを自動的にチェックするため、 FROM 句を省略できます。

ユーザーの個人用ステージからテーブルにファイルをロードします。

COPY INTO mytable from @~/staged
FILE_FORMAT = (FORMAT_NAME = 'mycsv');

Copy

名前付き外部ステージからのファイルのロード¶

CREATE STAGE コマンドを使用して以前に作成した名前付き外部ステージからファイルをロードします。名前付き外部ステージは外部の場所（Amazon S3、Google Cloud Storage、またはMicrosoft Azure）を参照し、場所にアクセスするために必要なすべての認証情報とその他の詳細が含まれます。

COPY INTO mycsvtable
  FROM @my_ext_stage/tutorials/dataloading/contacts1.csv;

Copy

列の一致を使用したファイルのロード¶

MATCH_BY_COLUMN_NAME コピーオプションを使用して、名前付きの外部ステージからテーブルにファイルをロードします。ファイル内の列名とテーブルで定義された列名を大文字と小文字を区別せずに一致させます。このオプションでは、ファイルの列の順序がテーブルの列の順序と一致する必要はありません。

COPY INTO mytable
  FROM @my_ext_stage/tutorials/dataloading/sales.json.gz
  FILE_FORMAT = (TYPE = 'JSON')
  MATCH_BY_COLUMN_NAME='CASE_INSENSITIVE';

Copy

外部ロケーションからのファイルの直接ロード¶

注釈

このオプションは、アウトバウンドプライベート接続ではサポートされていません。代わりに外部ステージを使用します。

次の例では、名前付きの my_csv_format ファイル形式を使用して、保存場所（Amazon S3、Google Cloud Storage、またはMicrosoft Azure）から data/files で始まるすべてのファイルをロードします。

Amazon S3

myint という名前の参照されたストレージ統合を使用して、参照されたS3バケットにアクセスします。どちらの例も MASTER_KEY 値を切り捨てることに注意してください。
COPY INTO mytable
  FROM s3://mybucket/data/files
  STORAGE_INTEGRATION = myint
  ENCRYPTION=(MASTER_KEY = 'eSx...')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy
提供された認証情報を使用して、参照されたS3バケットにアクセスします。
COPY INTO mytable
  FROM s3://mybucket/data/files
  CREDENTIALS=(AWS_KEY_ID='$AWS_ACCESS_KEY_ID' AWS_SECRET_KEY='$AWS_SECRET_ACCESS_KEY')
  ENCRYPTION=(MASTER_KEY = 'eSx...')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy

Google Cloud Storage

myint という名前の参照ストレージ統合を使用して、参照された GCS バケットにアクセスします。
COPY INTO mytable
  FROM 'gcs://mybucket/data/files'
  STORAGE_INTEGRATION = myint
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy

Microsoft Azure

myint という名前の参照ストレージ統合を使用して、参照されたコンテナーにアクセスします。どちらの例も MASTER_KEY 値を切り捨てることに注意してください。
COPY INTO mytable
  FROM 'azure://myaccount.blob.core.windows.net/data/files'
  STORAGE_INTEGRATION = myint
  ENCRYPTION=(TYPE='AZURE_CSE' MASTER_KEY = 'kPx...')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy
提供された認証情報を使用して、参照されたコンテナーにアクセスします。
COPY INTO mytable
  FROM 'azure://myaccount.blob.core.windows.net/mycontainer/data/files'
  CREDENTIALS=(AZURE_SAS_TOKEN='?sv=2016-05-31&ss=b&srt=sco&sp=rwdl&se=2018-06-27T10:05:50Z&st=2017-06-27T02:05:50Z&spr=https,http&sig=bgqQwoXwxzuD2GJfagRg7VOS8hzNr3QLT7rhS8OFRLQ%3D')
  ENCRYPTION=(TYPE='AZURE_CSE' MASTER_KEY = 'kPx...')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);
Copy

パターンの一致を使用したロード¶

任意のパスの圧縮された CSV ファイルからのみデータをロードするパターンマッチングを使用して、テーブルのステージからテーブルにファイルをロードします。

COPY INTO mytable
  FILE_FORMAT = (TYPE = 'CSV')
  PATTERN='.*/.*/.*[.]csv[.]gz';

Copy

ここで、 .* は、「任意の文字の0回以上の出現」と解釈されます。角括弧は、ファイル拡張子の前のピリオド文字（.）をエスケープします。

パターンマッチングを使用して、名前に文字列 sales が含まれる非圧縮 CSV ファイルのみをロードすることにより、テーブルステージからテーブルにファイルをロードします。

COPY INTO mytable
  FILE_FORMAT = (FORMAT_NAME = myformat)
  PATTERN='.*sales.*[.]csv';

Copy

VARIANT 列への JSON データのロード¶

次の例では、型 VARIANT の単一の列を持つテーブルに JSON データをロードします。

ステージされた JSON 配列は、改行で区切られた3つのオブジェクトで構成されます。

[{
    "location": {
      "city": "Lexington",
      "zip": "40503",
      },
      "sq__ft": "1000",
      "sale_date": "4-25-16",
      "price": "75836"
},
{
    "location": {
      "city": "Belmont",
      "zip": "02478",
      },
      "sq__ft": "1103",
      "sale_date": "6-18-16",
      "price": "92567"
}
{
    "location": {
      "city": "Winchester",
      "zip": "01890",
      },
      "sq__ft": "1122",
      "sale_date": "1-31-16",
      "price": "89921"
}]

Copy

/* Create a JSON file format that strips the outer array. */

CREATE OR REPLACE FILE FORMAT json_format
  TYPE = 'JSON'
  STRIP_OUTER_ARRAY = TRUE;

/* Create an internal stage that references the JSON file format. */

CREATE OR REPLACE STAGE mystage
  FILE_FORMAT = json_format;

/* Stage the JSON file. */

PUT file:///tmp/sales.json @mystage AUTO_COMPRESS=TRUE;

/* Create a target table for the JSON data. */

CREATE OR REPLACE TABLE house_sales (src VARIANT);

/* Copy the JSON data into the target table. */

COPY INTO house_sales
   FROM @mystage/sales.json.gz;

SELECT * FROM house_sales;

+---------------------------+
| SRC                       |
|---------------------------|
| {                         |
|   "location": {           |
|     "city": "Lexington",  |
|     "zip": "40503"        |
|   },                      |
|   "price": "75836",       |
|   "sale_date": "4-25-16", |
|   "sq__ft": "1000",       |
|   "type": "Residential"   |
| }                         |
| {                         |
|   "location": {           |
|     "city": "Belmont",    |
|     "zip": "02478"        |
|   },                      |
|   "price": "92567",       |
|   "sale_date": "6-18-16", |
|   "sq__ft": "1103",       |
|   "type": "Residential"   |
| }                         |
| {                         |
|   "location": {           |
|     "city": "Winchester", |
|     "zip": "01890"        |
|   },                      |
|   "price": "89921",       |
|   "sale_date": "1-31-16", |
|   "sq__ft": "1122",       |
|   "type": "Condo"         |
| }                         |
+---------------------------+

Copy

ファイルの再ロード¶

COPY コマンドに FORCE = TRUE を追加して、変更されていない（つまり、最初にロードされたときと同じチェックサムを持つ）ステージングされたデータファイルのセットからデータを再ロード（複製）します。

次の例では、最初のコマンドは指定されたファイルをロードし、2番目のコマンドはファイルの内容が変更されていなくても同じファイルを強制的に再ロードします（重複行を生成します）。

COPY INTO load1 FROM @%load1/data1/
    FILES=('test1.csv', 'test2.csv');

COPY INTO load1 FROM @%load1/data1/
    FILES=('test1.csv', 'test2.csv')
    FORCE=TRUE;

Copy

ロード後のファイルのパージ¶

テーブルのステージからテーブルにファイルをロードし、ロード後にファイルをパージします。デフォルトでは、 COPY はロードされたファイルをその場所からパージしません。ロード後にファイルをパージするには：

使用するアカウントに、ファイルが保存されているバケットまたはコンテナーへの書き込みアクセス権があることを確認してください。
テーブルに PURGE=TRUE を設定して、テーブルに正常にロードされたすべてのファイルがロード後にパージされるように指定します。
ALTER TABLE mytable SET STAGE_COPY_OPTIONS = (PURGE = TRUE); COPY INTO mytable;
Copy
COPY コマンドでコピーオプションを直接上書きすることもできます。
COPY INTO mytable PURGE = TRUE;
Copy

ファイルがテーブルにロードされた後、ファイルは保存元のバケットまたはコンテナーから削除されます。ファイルが削除プロセスを開始した後に、クエリをキャンセルすることはできません。

ステージングされたファイルの検証¶

ロードせずにステージでファイルを検証します。

検証モードで COPY コマンドを実行し、すべてのエラーを確認します。

COPY INTO mytable VALIDATION_MODE = 'RETURN_ERRORS';

+-------------------------------------------------------------------------------------------------------------------------------+------------------------+------+-----------+-------------+----------+--------+-----------+----------------------+------------+----------------+
|                                                         ERROR                                                                 |            FILE        | LINE | CHARACTER | BYTE_OFFSET | CATEGORY |  CODE  | SQL_STATE |   COLUMN_NAME        | ROW_NUMBER | ROW_START_LINE |
+-------------------------------------------------------------------------------------------------------------------------------+------------------------+------+-----------+-------------+----------+--------+-----------+----------------------+------------+----------------+
| Field delimiter ',' found while expecting record delimiter '\n'                                                               | @MYTABLE/data1.csv.gz  | 3    | 21        | 76          | parsing  | 100016 | 22000     | "MYTABLE"["QUOTA":3] | 3          | 3              |
| NULL result in a non-nullable column. Use quotes if an empty field should be interpreted as an empty string instead of a null | @MYTABLE/data3.csv.gz  | 3    | 2         | 62          | parsing  | 100088 | 22000     | "MYTABLE"["NAME":1]  | 3          | 3              |
| End of record reached while expected to parse column '"MYTABLE"["QUOTA":3]'                                                   | @MYTABLE/data3.csv.gz  | 4    | 20        | 96          | parsing  | 100068 | 22000     | "MYTABLE"["QUOTA":3] | 4          | 4              |
+-------------------------------------------------------------------------------------------------------------------------------+------------------------+------+-----------+-------------+----------+--------+-----------+----------------------+------------+----------------+

Copy

指定された行数に対して検証モードで COPY コマンドを実行します。この例では、最初の実行で指定した行数でエラーが発生せず、正常に完了し、テーブルにロードされたときに表示される情報が表示されます。2回目の実行では、指定された行数でエラーが発生し、エラーが発生した時点で失敗します。

COPY INTO mytable VALIDATION_MODE = 'RETURN_2_ROWS';

+--------------------+----------+-------+
|        NAME        |    ID    | QUOTA |
+--------------------+----------+-------+
| Joe Smith          |  456111  | 0     |
| Tom Jones          |  111111  | 3400  |
+--------------------+----------+-------+

COPY INTO mytable VALIDATION_MODE = 'RETURN_3_ROWS';

FAILURE: NULL result in a non-nullable column. Use quotes if an empty field should be interpreted as an empty string instead of a null
  File '@MYTABLE/data3.csv.gz', line 3, character 2
  Row 3, column "MYTABLE"["NAME":1]

Copy

IcebergテーブルへのIceberg互換Parquetデータのロード¶

この例では、Icebergテーブルを作成し、外部ステージにあるIceberg互換のParquetデータファイルからデータをロードします。

デモのため、この例では以下のリソースを使用します。

iceberg_ingest_vol という名前の外部ボリューム。外部ボリュームを作成するには、外部ボリュームの構成をご参照ください。
Iceberg互換のParquetファイルが置かれた my_parquet_stage という外部ステージ。外部ステージを作成するには、 CREATE STAGE をご参照ください。

Iceberg互換のParquetデータ（TYPE = PARQUET USE_VECTORIZED_SCANNER = TRUE）をコピーするために必要な構成を使用して、ステージングされたParquetファイルを説明するファイル形式オブジェクトを作成します。
```
CREATE OR REPLACE FILE FORMAT my_parquet_format
  TYPE = PARQUET
  USE_VECTORIZED_SCANNER = TRUE;
```
Copy

ソースParquetファイルのデータ型と互換性のあるデータ型の列を定義して、Snowflake管理のIcebergテーブルを作成します。

CREATE OR REPLACE ICEBERG TABLE customer_iceberg_ingest (
  c_custkey INTEGER,
  c_name STRING,
  c_address STRING,
  c_nationkey INTEGER,
  c_phone STRING,
  c_acctbal INTEGER,
  c_mktsegment STRING,
  c_comment STRING
)
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'iceberg_ingest_vol'
  BASE_LOCATION = 'customer_iceberg_ingest/';

Copy

注釈

このステートメント例では、Snowflakeデータ型にマップするIcebergデータ型を指定します。詳細については、 Apache Iceberg™ テーブルのデータ型をご参照ください。

COPY INTO ステートメントを使用して、ステージングされたParquetファイル（ステージ URL パスの直下にある）のデータをIcebergテーブルにロードします。

COPY INTO customer_iceberg_ingest
  FROM @my_parquet_stage
  FILE_FORMAT = 'my_parquet_format'
  LOAD_MODE = ADD_FILES_COPY
  PURGE = TRUE
  MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;

Copy

注釈

この例では、 LOAD_MODE = ADD_FILES_COPY を指定しています。これは、Snowflakeにファイルを外部ボリュームの場所にコピーし、そのファイルをテーブルに登録するように指示します。

SnowflakeはソースParquetファイルをスキャンしてデータを新しいParquetファイルに書き換えないため、このオプションを使用するとファイル課金が発生しません。

出力:

+---------------------------------------------------------------+--------+-------------+-------------+-------------+-------------+-------------+------------------+-----------------------+-------------------------+
| file                                                          | status | rows_parsed | rows_loaded | error_limit | errors_seen | first_error | first_error_line | first_error_character | first_error_column_name |
|---------------------------------------------------------------+--------+-------------+-------------+-------------+-------------+-------------+------------------+-----------------------+-------------------------|
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_008.parquet | LOADED |       15000 |       15000 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_006.parquet | LOADED |       15000 |       15000 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_005.parquet | LOADED |       15000 |       15000 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_002.parquet | LOADED |           5 |           5 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
| my_parquet_stage/snow_af9mR2HShTY_AABspxOVwhc_0_1_010.parquet | LOADED |       15000 |       15000 |           0 |           0 | NULL        |             NULL |                  NULL | NULL                    |
+---------------------------------------------------------------+--------+-------------+-------------+-------------+-------------+-------------+------------------+-----------------------+-------------------------+

テーブルをクエリします。

SELECT
    c_custkey,
    c_name,
    c_mktsegment
  FROM customer_iceberg_ingest
  LIMIT 10;

Copy

出力:

+-----------+--------------------+--------------+
| C_CUSTKEY | C_NAME             | C_MKTSEGMENT |
|-----------+--------------------+--------------|
|     75001 | Customer#000075001 | FURNITURE    |
|     75002 | Customer#000075002 | FURNITURE    |
|     75003 | Customer#000075003 | MACHINERY    |
|     75004 | Customer#000075004 | AUTOMOBILE   |
|     75005 | Customer#000075005 | FURNITURE    |
|         1 | Customer#000000001 | BUILDING     |
|         2 | Customer#000000002 | AUTOMOBILE   |
|         3 | Customer#000000003 | AUTOMOBILE   |
|         4 | Customer#000000004 | MACHINERY    |
|         5 | Customer#000000005 | HOUSEHOLD    |
+-----------+--------------------+--------------+

`@[namespace.]int_stage_name[/path]`	ファイルは指定された名前付き内部ステージにあります。
`@[namespace.]ext_stage_name[/path]`	ファイルは指定された名前付き外部ステージにあります。
`@[namespace.]%table_name[/path]`	ファイルは指定されたテーブルのステージにあります。
`@~[/path]`	ファイルは現在のユーザーのステージにあります。
`'protocol://bucket[/path]'`	ファイルは指定された外部の場所（S3バケット）にあります。追加のパラメーターが必要になる場合があります。詳細については、追加のクラウドプロバイダーパラメーター（このトピック内）をご参照ください。
`'gcs://bucket[/path]'`	ファイルは、指定された外部の場所（Google Cloud Storageバケット）にあります。追加のパラメーターが必要になる場合があります。詳細については、追加のクラウドプロバイダーパラメーター（このトピック内）をご参照ください。
`'azure://account.blob.core.windows.net/container[/path]'`	ファイルは指定された外部の場所（Azureコンテナー）にあります。追加のパラメーターが必要になる場合があります。詳細については、このトピックの追加のクラウドプロバイダーパラメーターをご参照ください。

`alias`	`FROM` 値のオプションのエイリアスを指定します（例: `COPY INTO t1 (c1) FROM (SELECT d.$1 FROM @mystage/file1.csv.gz d);` の `d`）。
`file_col_num`	ロードするデータを含む（ファイル内の）フィールド/列の位置番号を指定します（最初のフィールドには `1` 、2番目のフィールドには `2` など）
`element`	データファイル内の繰り返し値のパスと要素名を指定します（半構造化データファイルにのみ適用）。

COPY INTO <テーブル>¶

構文¶

必須パラメーター¶

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

変換パラメーター¶

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

形式タイプオプション（formatTypeOptions）¶

TYPE = CSV¶

TYPE = JSON¶

TYPE = AVRO¶

TYPE = ORC¶

TYPE = PARQUET¶

TYPE = XML¶

コピーオプション（copyOptions）¶

使用上の注意¶

出力¶

例¶

内部ステージからのファイルのロード¶

名前付き外部ステージからのファイルのロード¶

列の一致を使用したファイルのロード¶

外部ロケーションからのファイルの直接ロード¶

パターンの一致を使用したロード¶

VARIANT 列への JSON データのロード¶

ファイルの再ロード¶

ロード後のファイルのパージ¶

ステージングされたファイルの検証¶

IcebergテーブルへのIceberg互換Parquetデータのロード¶

形式タイプオプション（`formatTypeOptions`）¶

コピーオプション（`copyOptions`）¶