カテゴリ：: DDLデータのロード/アンロード

CREATE STAGE¶

ファイルからSnowflakeテーブルにデータをロードし、テーブルからファイルにデータをアンロードするために使用する新しい名前付きの内部または外部ステージを作成します。

内部ステージ

Snowflake内にデータファイルを内部的に保存します。内部ステージは永続的または仮のいずれかです。詳細については、ローカルファイルに対する内部ステージの選択をご参照ください。

外部ステージ

Snowflake以外の場所に保存されているデータファイルを参照します。現在、次のクラウドストレージサービスがサポートされています。

Amazon S3バケット
Google Cloud Storageバケット
Microsoft Azureコンテナー

ストレージの場所は、プライベート/保護またはパブリックのいずれかです。

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

内部ステージまたは外部ステージには、 ディレクトリテーブル を含めることができます。ディレクトリテーブルは、ステージングされたファイルのカタログをクラウドストレージに保存します。

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

DROP STAGE、 ALTER STAGE、 SHOW STAGES、 DESCRIBE STAGE

PUT 、 COPY INTO <テーブル>

COPY INTO <場所> 、 GET

このトピックの内容：

構文¶

-- Internal stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <internal_stage_name>
    internalStageParams
    directoryTableParams
  [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] ) } ]
  [ COPY_OPTIONS = ( copyOptions ) ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ COMMENT = '<string_literal>' ]

-- External stage
CREATE [ OR REPLACE ] [ TEMPORARY ] STAGE [ IF NOT EXISTS ] <external_stage_name>
    externalStageParams
    directoryTableParams
  [ FILE_FORMAT = ( { FORMAT_NAME = '<file_format_name>' | TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] ) } ]
  [ COPY_OPTIONS = ( copyOptions ) ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ COMMENT = '<string_literal>' ]

条件：

internalStageParams ::=
  [ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE') ]

externalStageParams (for Amazon S3) ::=
  URL = 's3://<bucket>[/<path>/]'

  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( {  { AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' [ AWS_TOKEN = '<string>' ] } | AWS_ROLE = '<string>'  } ) ) } ]
  [ ENCRYPTION = ( [ TYPE = 'AWS_CSE' ] [ MASTER_KEY = '<string>' ] |
                   [ TYPE = 'AWS_SSE_S3' ] |
                   [ TYPE = 'AWS_SSE_KMS' [ KMS_KEY_ID = '<string>' ] ] |
                   [ TYPE = 'NONE' ] ) ]

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

externalStageParams (for Microsoft Azure) ::=
  URL = '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>' ] ) ]

directoryTableParams (for internal stages) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ REFRESH_ON_CREATE =  { TRUE | FALSE } ] ) ]

directoryTableParams (for Amazon S3) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ REFRESH_ON_CREATE =  { TRUE | FALSE } ]
                  [ AUTO_REFRESH = { TRUE | FALSE } ]

directoryTableParams (for Google Cloud Storage) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ AUTO_REFRESH = { TRUE | FALSE } ]
                  [ REFRESH_ON_CREATE =  { TRUE | FALSE } ]
                  [ NOTIFICATION_INTEGRATION = '<notification_integration_name>' ] ) ]

directoryTableParams (for Microsoft Azure) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ REFRESH_ON_CREATE =  { TRUE | FALSE } ]
                  [ AUTO_REFRESH = { TRUE | FALSE } ]
                  [ NOTIFICATION_INTEGRATION = '<notification_integration_name>' ] ) ]

formatTypeOptions ::=
-- If TYPE = CSV
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     RECORD_DELIMITER = '<character>' | NONE
     FIELD_DELIMITER = '<character>' | NONE
     FILE_EXTENSION = '<string>'
     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
     VALIDATE_UTF8 = TRUE | FALSE
     EMPTY_FIELD_AS_NULL = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE
     ENCODING = '<string>' | UTF8
-- If 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
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
     FILE_EXTENSION = '<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 TYPE = AVRO
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If TYPE = ORC
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If TYPE = PARQUET
     COMPRESSION = AUTO | LZO | SNAPPY | NONE
     SNAPPY_COMPRESSION = TRUE | FALSE
     BINARY_AS_TEXT = TRUE | FALSE
     TRIM_SPACE = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If 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_SNOWFLAKE_DATA = TRUE | FALSE
     DISABLE_AUTO_CONVERT = TRUE | FALSE
     SKIP_BYTE_ORDER_MARK = TRUE | FALSE

copyOptions ::=
     ON_ERROR = { CONTINUE | SKIP_FILE | SKIP_FILE_<num> | 'SKIP_FILE_<num>%' | ABORT_STATEMENT }
     SIZE_LIMIT = <num>
     PURGE = TRUE | FALSE
     RETURN_FAILED_ONLY = TRUE | FALSE
     MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE
     ENFORCE_LENGTH = TRUE | FALSE
     TRUNCATECOLUMNS = TRUE | FALSE
     FORCE = TRUE | FALSE

必須パラメーター¶

内部ステージ名 または . 外部ステージ名

ステージの識別子を指定します。ステージが作成されるスキーマに対して一意である必要があります。

また、識別子はアルファベット文字で始まる必要があり、識別子文字列全体が二重引用符で囲まれていない限り、スペースや特殊文字を含めることはできません（例： "My object"）。二重引用符で囲まれた識別子も大文字と小文字が区別されます。

詳細については、識別子の要件をご参照ください。

注釈

外部ステージを作成するときは、 URL も必要です。詳細については、外部ステージパラメーター（このトピック）をご参照ください。

URL が指定されていない場合、Snowflakeはデフォルトで内部ステージを作成します。

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

TEMPORARY

作成されたステージが仮であり、作成されたセッションの終了時にドロップされることを指定します。注意：

仮の外部ステージがドロップされると、ステージ自体のみがドロップされます。データファイルは削除されません。

仮の内部ステージがドロップされると、ロードステータスに関係なく、ステージ内のすべてのファイルがSnowflakeからパージされます。これにより、仮の内部ステージのファイルがデータストレージを使用することでストレージ料金が発生することを防ぎます。ただし、これは、ステージがドロップされると、Snowflakeを介してステージングされたファイルを回復できないことも意味します。

ちなみに

仮の内部ステージを作成して使用する予定がある場合は、Snowflakeの外部にデータファイルのコピーを保持する必要があります。

ステージのファイル形式を指定します。次のいずれかです。

FORMAT_NAME = 'ファイル形式名'
ステージに使用する既存の名前付きファイル形式を指定します。指定されたファイル形式は、このステージを使用してロードされるデータファイルの形式タイプ（CSV、 JSONなど）およびその他の形式オプションを決定します。詳細については、 CREATE FILE FORMAT をご参照ください。

TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ]
ステージのファイルのタイプを指定します。

ステージからのデータのロード（ COPY INTO <テーブル> を使用）は、サポートされているすべての形式タイプに対応しています。

（ COPY INTO <場所> を使用して）ステージにデータをアンロードすることは、 CSV、 JSON、または PARQUET に対応します。

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

デフォルト： TYPE = CSV

注釈

FORMAT_NAME と TYPE は相互に排他的です。ステージに指定できるのはどちらか一方のみです。

COPY_OPTIONS = ( ... )

ステージの1つ（または複数）のコピーオプションを指定します。詳細については、コピーオプション（copyOptions）（このトピック内）をご参照ください。

TAG ( タグ名 = 'タグ値' [ , タグ名 = 'タグ値' , ... ] )

タグ名（つまり、キー）とタグ値を指定します。

タグ値は常に文字列であり、タグ値の最大文字数は256です。オブジェクトに設定できる一意のタグキーの最大数は20です。

COMMENT = '文字列リテラル'

ステージのコメントを指定します。

デフォルト: 値なし

内部ステージパラメーター（`internalStageParams`）¶

[ ENCRYPTION = (TYPE = 'SNOWFLAKE_FULL' | TYPE = 'SNOWFLAKE_SSE')

ステージに保存されているすべてのファイルでサポートされている暗号化の型を指定します。

TYPE = ...

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

SNOWFLAKE_FULL: クライアント側の暗号化。ファイルは、クライアントが PUT を使用して内部ステージにアップロードするときに暗号化されます。
SNOWFLAKE_SSE: サーバー側の暗号化。ファイルは、ステージに着信した時に暗号化されます。非構造化データファイルのサーバー側の暗号化を指定します。

注釈

この非構造化データファイルのサポートは、プレビュー機能として提供されます。

デフォルト: SNOWFLAKE_FULL

外部ステージパラメーター（`externalStageParams`）¶

URL = 'クラウド固有のURL'

このパラメーターを省略すると、SSnowflakenowflakeは内部ステージを作成します

重要

Snowflakeが文字列を識別するために、 URL を一重引用符（''）で囲みます。引用符を省略すると、指定した認証情報が履歴にプレーンテキストで表示される場合があります。 CREATE STAGE ステートメントの構文を実行する前に検証することを強くお勧めします。

Snowflakeウェブインターフェイスにステージを作成すると、インターフェイスは、必要に応じてフィールド値を引用符で自動的に囲みます。
URL にスラッシュ（/）を追加して、指定したフォルダーパスにフィルターをかけます。スラッシュを省略すると、指定したパスのプレフィックスで始まるすべてのファイルとフォルダーが含まれます。

ステージ内の非構造化データファイルにアクセスして取得するには、スラッシュが必須であることに注意してください。

Amazon S3

URL = 's3://バケット[/パス/]'
ロード/アンロード用のデータファイルの保存に使用される外部ロケーション（既存のS3バケット）の URL を指定します。この場合：

バケット は、S3バケットの名前です。

政府の地域などの非公開 AWS 地域のS3バケットはサポートされていないことに注意してください。

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

Google Cloud Storage

URL = 'gcs://バケット[/パス/]'
ロード/アンロード用のデータファイルの保存に使用される外部ロケーション（既存の GCS バケット）の URL を指定します。この場合：

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

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

Microsoft Azure

URL = 'azure://アカウント.blob.core.windows.net/コンテナー[/パス/]'
ロード用データファイルの保存に使用される外部ロケーション（既存のAzureコンテナー）の URL を指定します。この場合、

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

コンテナー は、Azureコンテナーの名前です（例： mycontainer）。

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

デフォルト：値なし（内部ステージが作成される）

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

ストレージの場所がプライベート/保護されている場合にのみ必要です。公共のバケット/コンテナーには必要ありません

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 コマンドは、永続的な（別名「長期」）認証情報の使用も許可します。ただし、セキュリティ上の理由から、Snowflakeはこれらの使用を推奨しません。永続的な認証情報を使用する必要がある場合、Snowflakeは外部ステージ用に新しい永続的な認証情報を定期的に生成することをお勧めします。

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

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 = ( クラウド固有の暗号化 )

暗号化されたファイルからのロード/アンロードにのみ必要です。保存場所とファイルが暗号化されていない場合は不要

データのロード: 保存場所内の暗号化されたファイルを復号化し、データを抽出するために使用する暗号化設定を変更します。
データのアンロード: ストレージの場所にアンロードされたファイルの暗号化に使用する暗号化設定を変更します。

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 ドキュメントをご参照ください。

NONE ：暗号化なし。

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' | 'NONE' ] [ KMS_KEY_ID = '文字列' ] )

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

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

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

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 = '文字列' （ 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ビットキーである必要があります。

ディレクトリテーブルパラメーター（`directoryTableParams`）¶

ENABLE = TRUE | FALSE

ディレクトリテーブルをステージに追加するかどうかを指定します。値が TRUE の場合は、ステージとともにディレクトリテーブルが作成されます。

デフォルト: FALSE

外部ステージ¶

Amazon S3

REFRESH_ON_CREATE = TRUE | FALSE
ステージが作成された直後に、ディレクトリテーブルのメタデータを1回自動的に更新するかどうかを指定します。ディレクトリテーブルのメタデータを更新すると、指定したステージパス内のデータファイルの現在のリストとメタデータが同期されます。このアクションは、メタデータが URL = 設定で指定された名前付きステージに既存のデータファイルを登録するために必要です。

TRUE
Snowflakeは、ステージの作成後にディレクトリテーブルのメタデータを自動的に更新します。

注釈

指定したクラウドストレージ URL に100万個近くかそれ以上のファイルが含まれている場合は、 REFRESH_ON_CREATE = FALSE を設定することをお勧めします。ステージを作成した後、メタデータにその場所のファイルすべてが含まれるまで、ストレージの場所のサブパス（つまり、更新に含めるファイルのサブセット）を指定する ALTER STAGE ... REFRESH ステートメントを実行して、ディレクトリテーブルのメタデータを段階的に更新します。

FALSE
Snowflakeは、ディレクトリテーブルのメタデータを自動的に更新しません。ステージに存在するデータファイルを登録するには、 ALTER STAGE ... REFRESH を使用してディレクトリテーブルのメタデータを手動で1回更新します。

デフォルト: TRUE

AUTO_REFRESH = TRUE | FALSE
[ WITH ] LOCATION = 設定で指定された名前付き外部ステージで新しいまたは更新されたデータファイルが使用可能な場合に、Snowflakeがディレクトリテーブルのメタデータの自動更新トリガーを有効にするかどうかを指定します。

TRUE
Snowflakeを使用すると、ディレクトリテーブルのメタデータの自動更新をトリガーできます。

FALSE
Snowflakeは、ディレクトリテーブルのメタデータの自動更新トリガーを有効にしません。 ALTER STAGE ... REFRESH を使用して、ディレクトリテーブルのメタデータを手動で定期的に更新し、メタデータをステージパスにあるファイルの現在のリストと同期する必要があります。

デフォルト: FALSE

Google Cloud Storage

REFRESH_ON_CREATE = TRUE | FALSE
ステージが作成された直後に、ディレクトリテーブルのメタデータを1回自動的に更新するかどうかを指定します。ディレクトリテーブルのメタデータを更新すると、指定したステージパス内のデータファイルの現在のリストとメタデータが同期されます。このアクションは、メタデータが URL = 設定で指定された名前付きステージに既存のデータファイルを登録するために必要です。

TRUE
Snowflakeは、ステージの作成後にディレクトリテーブルのメタデータを自動的に更新します。

注釈

指定したクラウドストレージ URL に100万個近くかそれ以上のファイルが含まれている場合は、 REFRESH_ON_CREATE = FALSE を設定することをお勧めします。ステージを作成した後、メタデータにその場所のファイルすべてが含まれるまで、ストレージの場所のサブパス（つまり、更新に含めるファイルのサブセット）を指定する ALTER STAGE ... REFRESH ステートメントを実行して、ディレクトリテーブルのメタデータを段階的に更新します。

FALSE
Snowflakeは、ディレクトリテーブルのメタデータを自動的に更新しません。ステージに存在するデータファイルを登録するには、 ALTER STAGE ... REFRESH を使用してディレクトリテーブルのメタデータを手動で1回更新します。

デフォルト: TRUE

AUTO_REFRESH = TRUE | FALSE
[ WITH ] LOCATION = 設定で指定された名前付き外部ステージで新しいまたは更新されたデータファイルが使用可能な場合に、Snowflakeがディレクトリテーブルのメタデータの自動更新トリガーを有効にするかどうかを指定します。

TRUE
Snowflakeを使用すると、ディレクトリテーブルのメタデータの自動更新をトリガーできます。

FALSE
Snowflakeは、ディレクトリテーブルのメタデータの自動更新トリガーを有効にしません。 ALTER STAGE ... REFRESH を使用して、ディレクトリテーブルのメタデータを手動で定期的に更新し、メタデータをステージパスにあるファイルの現在のリストと同期する必要があります。

NOTIFICATION_INTEGRATION = '<通知統合名>'
GCS Pub/Sub通知を使用して、ディレクトリテーブルのメタデータを自動的に更新するために使用される通知統合の名前を指定します。通知統合は、Snowflakeとサードパーティのクラウドメッセージキューサービス間のインターフェイスを提供するSnowflakeオブジェクトです。

Microsoft Azure

REFRESH_ON_CREATE = TRUE | FALSE
ステージが作成された直後に、ディレクトリテーブルのメタデータを1回自動的に更新するかどうかを指定します。ディレクトリテーブルのメタデータを更新すると、指定したステージパス内のデータファイルの現在のリストとメタデータが同期されます。このアクションは、メタデータが URL = 設定で指定された名前付きステージに既存のデータファイルを登録するために必要です。

TRUE
Snowflakeは、ステージの作成後にディレクトリテーブルのメタデータを自動的に更新します。

注釈

指定したクラウドストレージ URL に100万個近くかそれ以上のファイルが含まれている場合は、 REFRESH_ON_CREATE = FALSE を設定することをお勧めします。ステージを作成した後、メタデータにその場所のファイルすべてが含まれるまで、ストレージの場所のサブパス（つまり、更新に含めるファイルのサブセット）を指定する ALTER STAGE ... REFRESH ステートメントを実行して、ディレクトリテーブルのメタデータを段階的に更新します。

FALSE
Snowflakeは、ディレクトリテーブルのメタデータを自動的に更新しません。ステージに存在するデータファイルを登録するには、 ALTER STAGE ... REFRESH を使用してディレクトリテーブルのメタデータを手動で1回更新します。

デフォルト: TRUE

AUTO_REFRESH = TRUE | FALSE
[ WITH ] LOCATION = 設定で指定された名前付き外部ステージで新しいまたは更新されたデータファイルが使用可能な場合に、Snowflakeがディレクトリテーブルのメタデータの自動更新トリガーを有効にするかどうかを指定します。

TRUE
Snowflakeを使用すると、ディレクトリテーブルのメタデータの自動更新をトリガーできます。

FALSE
Snowflakeは、ディレクトリテーブルのメタデータの自動更新トリガーを有効にしません。 ALTER STAGE ... REFRESH を使用して、ディレクトリテーブルのメタデータを手動で定期的に更新し、メタデータをステージパスにあるファイルの現在のリストと同期する必要があります。

デフォルト: FALSE

NOTIFICATION_INTEGRATION = '<通知統合名>'
Azure Event Grid通知を使用して、ディレクトリテーブルのメタデータを自動的に更新するために使用される通知統合の名前を指定します。通知統合は、Snowflakeとサードパーティのクラウドメッセージキューサービス間のインターフェイスを提供するSnowflakeオブジェクトです。

形式の種類のオプション（`formatTypeOptions`）¶

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

TYPE = CSV¶

使用

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

定義

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

値

サポートされる値	メモ
`AUTO`	データをロードすると、圧縮アルゴリズムは自動的に検出されますが、Brotliで圧縮されたファイルは例外で、現在は自動検出できません。データをアンロードするとき、ファイルはデフォルトの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プラットフォーム上のファイルの改行として理解されることに注意してください。
データのアンロード: 改行文字（\n）。

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

使用: データのアンロードのみ
定義: ステージにアンロードされるファイルの拡張子を指定します。拡張子を受け入れます。目的のソフトウェアまたはサービスが読み取れるファイル拡張子を指定することは、ユーザーの責任です。
デフォルト: null、つまり、ファイル拡張子は形式タイプ、 .csv[圧縮] によって決定されます。 圧縮 は、 COMPRESSION が設定されている場合、圧縮方法によって追加された拡張子です。

注釈

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

SKIP_HEADER = 整数

使用: データのロードのみ
定義: スキップするファイルの先頭の行数。

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

デフォルト: 0

SKIP_BLANK_LINES = TRUE | FALSE

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

デフォルト： FALSE

DATE_FORMAT = '文字列' | AUTO

使用: データのロードとアンロード
定義: データファイル（データのロード）またはテーブル（データのアンロード）の日付値の形式を定義します。値が指定されていない、または AUTO の場合、 DATE_INPUT_FORMAT （データのロード）または DATE_OUTPUT_FORMAT （データのアンロード）パラメーターの値が使用されます。
デフォルト: AUTO

TIME_FORMAT = '文字列' | AUTO

使用: データのロードとアンロード
定義: データファイル（データのロード）またはテーブル（データのアンロード）の時間値の形式を定義します。値が指定されていない、または AUTO の場合、 TIME_INPUT_FORMAT （データのロード）または TIME_OUTPUT_FORMAT （データのアンロード）パラメーターの値が使用されます。
デフォルト: AUTO

TIMESTAMP_FORMAT = 文字列' | AUTO

使用: データのロードとアンロード
定義: データファイル（データのロード）またはテーブル（データのアンロード）のタイムスタンプ値の形式を定義します。値が指定されていない、または AUTO の場合、 TIMESTAMP_INPUT_FORMAT （データのロード）または TIMESTAMP_OUTPUT_FORMAT （データのアンロード）パラメーターの値が使用されます。
デフォルト: AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

使用: データのロードとアンロード
定義: バイナリ入力または出力のエンコード形式を定義します。このオプションは、テーブルのバイナリ列にデータをロードまたはアンロードするときに使用できます。
デフォルト: HEX

ESCAPE = '文字' | NONE

使用

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

定義

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

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

データのロード

囲まれたフィールド専用のエスケープ文字を指定します。 FIELD_OPTIONALLY_ENCLOSED_BY を設定して、フィールドを囲むのに使用する文字を指定します。

注釈

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

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

データのアンロード

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

デフォルト

NONE

ESCAPE_UNENCLOSED_FIELD = '文字' | NONE

使用

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

定義

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

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

データのロード

囲まれていないフィールド専用のエスケープ文字を指定します。

注釈

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

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

データのアンロード

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

デフォルト

バックスラッシュ（\\）

TRIM_SPACE = TRUE | FALSE

使用

データのロードのみ

定義

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

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

別の例として、先頭または後続のスペースが文字列を囲む引用符の前後にある場合、このオプションを使用して周囲のスペースを削除し、 FIELD_OPTIONALLY_ENCLOSED_BY オプションを使用して引用文字を削除できます。引用符内のスペースは保持されることに注意してください。例えば、 FIELD_DELIMITER = '|' と FIELD_OPTIONALLY_ENCLOSED_BY = '"' を想定した場合：

|"Hello world"|    /* loads as */  >Hello world<
|" Hello world "|  /* loads as */  > Hello world <
| "Hello world" |  /* loads as */  >Hello world<

（この例のブラケットはロードされておらず、ロードされた文字列の開始と終了を区別するために使用されます）

デフォルト

FALSE

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 に置き換えます。複数の文字列を指定するには、文字列のリストを括弧で囲み、各値をコンマで区切ります。

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

例:

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

このオプションには空の文字列を含めることができます。
データをアンロードする際、Snowflakeは SQL NULL 値をリストの最初の値に変換します。

デフォルト

\\N （つまり、 NULL、 ESCAPE_UNENCLOSED_FIELD 値が \\ であると想定）

ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE

使用

データのロードのみ

定義

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

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

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

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

デフォルト

TRUE

注釈

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

REPLACE_INVALID_CHARACTERS = TRUE | FALSE

使用: データのロードのみ
定義: 無効な UTF -8文字をUnicode置換文字（�）で置き換えるかどうかを指定するブール値。

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

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

デフォルト: FALSE

VALIDATE_UTF8 = TRUE | FALSE

使用

データのロードのみ

定義

文字列列データの UTF-8文字エンコードを検証するかどうかを指定するブール値。

TRUE に設定すると、Snowflakeは文字列の列データの UTF-8文字エンコードを検証します。無効な UTF-8文字エンコードが検出されると、 COPY コマンドはエラーを生成します。

デフォルト

TRUE

重要

このオプションは、Snowflakeの以前のバージョンとの後方互換性を確保するためにのみ提供されています。Snowflakeサポートの指示がない限り、このオプションを無効にしないでください。

EMPTY_FIELD_AS_NULL = TRUE | FALSE

使用

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

定義

データをロードするとき、2つの連続する区切り文字（例： ,,）で表される入力ファイルの空のフィールドに、 SQL NULL を挿入するかどうかを指定します。

FALSE に設定すると、Snowflakeは空のフィールドを対応する列タイプにキャストしようとします。タイプ STRINGの列に空の文字列が挿入されます。他の列タイプの場合、 COPY コマンドはエラーを生成します。
データをアンロードするとき、このオプションは FIELD_OPTIONALLY_ENCLOSED_BY と組み合わせて使用されます。 FIELD_OPTIONALLY_ENCLOSED_BY = NONE の場合、 EMPTY_FIELD_AS_NULL = FALSE を設定すると、テーブル内の空の文字列を、フィールド値を囲む引用符なしで空の文字列値にアンロードするように指定されます。

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

デフォルト

TRUE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

使用

データのロードのみ

定義

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

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

デフォルト

TRUE

ENCODING = '文字列'

使用

データのロードのみ

定義

データをテーブルにロードする際にソースデータの文字セットを指定する文字列（定数）。

文字セット	`ENCODING` 値	サポートされている言語	メモ
Big5	`BIG5`	中国語（繁体字）
EUC-JP	`EUCJP`	日本語
EUC-KR	`EUCKR`	韓国語
GB18030	`GB18030`	中国語
IBM420	`IBM420`	アラビア語
IBM424	`IBM424`	ヘブライ語
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`	トルコ語
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-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に変換されます。 VALIDATE_UTF8 ファイル形式オプションが TRUE の場合、Snowflakeは、元の文字エンコードから変換された後の文字列の列データの UTF-8文字エンコードを検証します。

TYPE = JSON¶

使用

データのロードのみ

定義

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

値

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

デフォルト

AUTO

DATE_FORMAT = '文字列' | AUTO

使用

データのロードのみ

定義

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

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

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

デフォルト

AUTO

TIME_FORMAT = '文字列' | AUTO

使用

データのロードのみ

定義

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

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

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

デフォルト

AUTO

TIMESTAMP_FORMAT = 文字列' | 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

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

使用

データのロードのみ

定義

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

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

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

例:

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

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

デフォルト

\\N （つまり、 NULL、 ESCAPE_UNENCLOSED_FIELD 値が \\ であると想定）

FILE_EXTENSION = '文字列' | NONE

使用: データのアンロードのみ
定義: ステージにアンロードされるファイルの拡張子を指定します。拡張子を受け入れます。目的のソフトウェアまたはサービスが読み取れるファイル拡張子を指定することは、ユーザーの責任です。
デフォルト: null。つまり、ファイル拡張子は形式タイプ： .json[圧縮] によって決定されます。 圧縮 は、 COMPRESSION が設定されている場合、圧縮方法によって追加された拡張子です。

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エンコードエラーがエラー状態を引き起こすかどうかを指定するブール値。 TRUE に設定すると、無効な UTF-8シーケンスはUnicode文字 U+FFFD （つまり、「置換文字」）で警告なしに置き換えられます。

注釈

このコピーオプションは、データの読み込み中に UTF-8以外のすべての文字を削除しますが、1対1の文字置換の保証はありません。代わりに、 REPLACE_INVALID_CHARACTERS コピーオプションを使用することをお勧めします。
デフォルト: FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

使用

データのロードのみ

定義

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

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

デフォルト

TRUE

TYPE = AVRO¶

使用

データのロードのみ

定義

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

値

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

デフォルト

AUTO

TRIM_SPACE = TRUE | FALSE

使用

データのロードのみ

定義

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

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

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

デフォルト

FALSE

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

使用

データのロードのみ

定義

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

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

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

例:

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

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

デフォルト

\\N （つまり、 NULL、 ESCAPE_UNENCLOSED_FIELD 値が \\ であると想定）

TYPE = ORC¶

TRIM_SPACE = TRUE | FALSE

使用

データのロードのみ

定義

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

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

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

デフォルト

FALSE

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

使用

データのロードのみ

定義

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

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

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

例:

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

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

デフォルト

\\N （つまり、 NULL、 ESCAPE_UNENCLOSED_FIELD 値が \\ であると想定）

TYPE = PARQUET¶

COMPRESSION = AUTO | LZO | SNAPPY | NONE

使用: データのロードとアンロード
定義

データをロードするときに、Parquetファイルにある列の現在の圧縮アルゴリズムを指定します。
データをアンロードする際、指定された圧縮アルゴリズムを使用してデータファイルを圧縮します。

値

サポートされる値	メモ
`AUTO`	データをロードするときに、圧縮アルゴリズムが自動的に検出されました。対応する圧縮アルゴリズム：Brotli、gzip、Lempel–Ziv–Oberhumer（LZO）、 LZ4、Snappy、またはZstandard v0.8（およびそれ以上）。 . データをアンロードすると、アンロードされたファイルはデフォルトで Snappy 圧縮アルゴリズムを使用して圧縮されます。
`LZO`	データをアンロードするとき、ファイルはデフォルトでSnappyアルゴリズムを使用して圧縮されます。LZO 圧縮ファイルにデータをアンロードする場合は、この値を指定します。
`SNAPPY`	データをアンロードするとき、ファイルはデフォルトでSnappyアルゴリズムを使用して圧縮されます。オプションでこの値を指定できます。
`NONE`	データをロードするとき、ファイルが圧縮されていないことを示します。データをアンロードするとき、アンロードされたファイルが圧縮されないことを指定します。

デフォルト

AUTO

SNAPPY_COMPRESSION = TRUE | FALSE

使用

データのアンロードのみ

AUTO | アンロードされたファイルは、デフォルトで Snappy 圧縮アルゴリズムを使用して圧縮されます。 SNAPPY | Snappy圧縮ファイルをアンロードする場合に指定できます。 NONE | データをロードするときに、ファイルが圧縮されていないことを示します。データをアンロードするとき、アンロードされたファイルが圧縮されないことを指定します。

定義

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

注釈

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

制限事項: データのアンロード操作についてのみサポートされています。
デフォルト: TRUE

BINARY_AS_TEXT = TRUE | FALSE

使用: データのロードのみ
定義: 論理データ型が定義されていない列を UTF-8テキストとして解釈するかどうかを指定するブール値。 FALSE に設定すると、Snowflakeはこれらの列をバイナリデータとして解釈します。
制限事項: データロード操作についてのみサポートされています。
デフォルト: TRUE

TRIM_SPACE = TRUE | FALSE

使用

データのロードのみ

定義

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

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

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

デフォルト

FALSE

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

使用

データのロードのみ

定義

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

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

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

例:

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

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

デフォルト

\\N （つまり、 NULL、 ESCAPE_UNENCLOSED_FIELD 値が \\ であると想定）

TYPE = XML¶

使用

データのロードのみ

定義

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

値

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

デフォルト

AUTO

IGNORE_UTF8_ERRORS = TRUE | FALSE

使用: データのロードのみ
定義: UTF-8エンコードエラーがエラー状態を引き起こすかどうかを指定するブール値。 TRUE に設定すると、無効な UTF-8シーケンスはUnicode文字 U+FFFD （「置換文字」）で警告なしに置き換えられます。
デフォルト: FALSE

PRESERVE_SPACE = TRUE | FALSE

使用: データのロードのみ
定義: XML パーサーが要素コンテンツの先頭と後続のスペースを保持するかどうかを指定するブール値。
デフォルト: FALSE

STRIP_OUTER_ELEMENT = TRUE | FALSE

使用: データのロードのみ
定義: XML パーサーが外側の XML 要素を取り除き、2番目のレベルの要素を個別のドキュメントとして公開するかどうかを指定するブール値。
デフォルト: FALSE

DISABLE_SNOWFLAKE_DATA = TRUE | FALSE

使用: データのロードのみ
定義: XML パーサーがSnowflake半構造化データタグの認識を無効にするかどうかを指定するブール値。
デフォルト: FALSE

DISABLE_AUTO_CONVERT = TRUE | FALSE

使用: データのロードのみ
定義: XML パーサーがテキストからネイティブ表現への数値およびブール値の自動変換を無効にするかどうかを指定するブール値。
デフォルト: FALSE

SKIP_BYTE_ORDER_MARK = TRUE | FALSE

使用

データのロードのみ

定義

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

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

デフォルト

TRUE

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

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

ON_ERROR = CONTINUE | SKIP_FILE | SKIP_FILE_数値 | 'SKIP_FILE_数値%' | 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_数値 （例 SKIP_FILE_10）: ファイル内で見つかったエラー行の数が指定された数以上の場合は、ファイルをスキップします。
'SKIP_FILE_数値%' （例 'SKIP_FILE_10%'）: ファイル内で見つかったエラー行の割合が指定された割合を超えた場合は、ファイルをスキップします。

ABORT_STATEMENT

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

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

このコピーオプションには、次の動作が適用されます。
- すべての ON_ERROR 値は、構造化データファイル（CSV、 TSV など）をロードするときに、解析エラーまたは変換エラーで期待どおりに機能します。
  
  しかし、半構造化データファイル（JSON、Avro、 ORC、Parquet、または XML）は、 CONTINUE、 SKIP_FILE_数値、または 'SKIP_FILE_数値%' に対して、これらの形式の設計が原因で ON_ERROR 値の構造化データファイルと同じ動作セマンティクスをサポートしていません。
- Parquetと ORC データのみ。 ON_ERROR が CONTINUE、 SKIP_FILE_数値、または 'SKIP_FILE_数値%' に設定されている場合は、解析エラーが発生するとデータファイルをスキップします。換算エラーまたは変換エラーは、選択したオプション値に関係なく、 ABORT_STATEMENT （COPY INTO <テーブル> ステートメント）または SKIP_FILE （Snowpipe）のデフォルトの動作に従います。
- JSON、 XML、および Avroデータのみ。 ON_ERROR が CONTINUE、 SKIP_FILE_数値、または 'SKIP_FILE_数値%' に設定されている場合は、解析エラーが含まれる記録までの全記録がロードされますが、データファイル内の残りの記録はスキップされます。換算エラーまたは変換エラーは、選択したオプション値に関係なく、 COPY （ABORT_STATEMENT）またはSnowpipe（SKIP_FILE）のデフォルトの動作に従います。

デフォルト

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

SIZE_LIMIT = 数値

使用

データのロードのみ

定義

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

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

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

デフォルト

null（サイズ制限なし）

PURGE = TRUE | FALSE

使用

データのロードのみ

定義

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

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

デフォルト

FALSE

RETURN_FAILED_ONLY = TRUE | FALSE

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

MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE

使用

データのロードのみ

定義

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

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

JSON
Avro
ORC
Parquet

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

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

値

CASE_SENSITIVE | CASE_INSENSITIVE

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

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

注釈

一致しない追加の列がデータファイルに存在する場合、これらの列の値はロードされません。
一致しない追加の列がターゲットテーブルに存在する場合、 COPY 操作はこれらの列に NULL 値を挿入します。これらの列は NULL 値をサポートする必要があります。
COPY ステートメントでは、ロード中にデータをさらに変換するクエリを指定できません（つまり、 COPY 変換）。

NONE

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

注釈

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

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

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

デフォルト: NONE

ENFORCE_LENGTH = TRUE | FALSE

使用

データのロードのみ

定義

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

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

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

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

注釈

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

デフォルト: TRUE

TRUNCATECOLUMNS = TRUE | FALSE

使用

データのロードのみ

定義

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

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

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

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

注釈

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

デフォルト

FALSE

FORCE = TRUE | FALSE

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

アクセス制御の要件¶

この SQL コマンドの実行に使用されるロールには、少なくとも次の権限が必要です。

権限	オブジェクト	メモ
USAGE	ストレージ統合	ストレージ統合を使用してクラウドストレージサービスにアクセスする場合にのみ必要です。
CREATE STAGE	スキーマ
USAGE	ファイル形式	ステージ定義で名前付きファイル形式を参照する場合にのみ必要です。

スキーマ内の任意のオブジェクトを操作するには、親データベースとスキーマに対する USAGE 権限も必要であることに注意してください。

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

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

使用上の注意¶

ご用心

ステージを再作成（CREATE OR REPLACE STAGE を使用）すると、次の潜在的に望ましくない結果が追加で発生します。

ステージの既存のディレクトリテーブルがある場合は、ドロップされます。ステージがディレクトリテーブルで再作成される場合、ディレクトリはデフォルトで空です。
ステージとそれを参照する外部テーブルとの関連付けは解除されます。

これは、外部テーブルがステージの名前ではなく、非表示の ID を使用してステージにリンクされているためです。バックグラウンドでは、 CREATE OR REPLACE 構文はオブジェクトをドロップし、別の非表示の ID でオブジェクトを再作成します。

1つ以上の外部テーブルにリンクされた後にステージを再作成する必要がある場合は、各外部テーブルを再作成（CREATE OR REPLACE EXTERNAL TABLE を使用）して、関連付けを再確立する必要があります。 GET_DDL 関数を呼び出して DDL ステートメントを取得し、各外部テーブルを再作成します。
ステージを参照するパイプは、データのロードを停止します。パイプの実行ステータスが STOPPED_STAGE_DROPPED に変わります。データのロードを再開するには、これらのパイプオブジェクトを再作成する必要があります（CREATE OR REPLACE PIPE 構文を使用）。

CREATE STAGE は、指定された URL または認証情報が有効かどうかをチェックしません。認証情報が有効でない場合、ステージを使用しようとすると、システムはエラーを返します。
現在の名前空間のファイル形式を参照する場合は、形式識別子を囲む単一引用符を省略できます。
メタデータについて。

注意

Snowflakeサービスを使用する場合、お客様は、個人データ（ユーザーオブジェクト向け以外）、機密データ、輸出管理データ、またはその他の規制されたデータがメタデータとして入力されていないことを確認する必要があります。詳細については、 Snowflakeのメタデータフィールドをご参照ください。

例¶

内部ステージ¶

デフォルトのファイル形式タイプ（CSV）で内部ステージを作成します。

対応するすべてのデフォルトの CSV ファイル形式オプションが使用されます。

ON_ERROR を除くすべてのデフォルトのコピーオプションが使用されます。このステージを参照する COPY INTO <テーブル> コマンドがいずれかの記録でデータエラーを検出した場合、ファイルをスキップします。
CREATE STAGE my_int_stage
  COPY_OPTIONS = (ON_ERROR='skip_file');

前の例と同様ですが、ステージにサーバー側の暗号化を指定します。

CREATE STAGE my_int_stage
  ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE')
  COPY_OPTIONS = (ON_ERROR='skip_file');

エラー時にファイルをスキップするコピーオプションを除き、前の例とすべて同じプロパティで仮内部ステージを作成します。

CREATE TEMPORARY STAGE my_temp_int_stage;

my_csv_format （ CREATE FILE FORMAT を使用して作成）という名前のファイル形式を参照する、仮内部ステージを作成します。

CREATE TEMPORARY STAGE my_int_stage
  FILE_FORMAT = my_csv_format;
COPY INTO <テーブル> ステートメントでステージを参照すると、ファイル形式オプションが自動的に設定されます。

ディレクトリテーブルを含む内部ステージを作成します。ステージは myformat という名前のファイル形式を参照します。

CREATE STAGE mystage
  DIRECTORY = (ENABLE = TRUE)
  FILE_FORMAT = myformat;

外部ステージ¶

Amazon S3

load という名前のプライベート/保護されたS3バケットと files という名前のフォルダーパスを使用して外部ステージを作成します。S3バケットへの安全なアクセスは、 myint ストレージ統合を介して提供されます。
CREATE STAGE my_ext_stage
  URL='s3://load/files/'
  STORAGE_INTEGRATION = myint;
load という名前のプライベート/保護されたS3バケットと files という名前のフォルダーパスを使用して外部ステージを作成します。S3バケットのSnowflakeアクセス許可は IAM ユーザーに関連付けられています。したがって、 IAM 認証情報が必要です。
CREATE STAGE my_ext_stage1
  URL='s3://load/files/'
  CREDENTIALS=(AWS_KEY_ID='1a2b3c' AWS_SECRET_KEY='4x5y6z');
この例で使用されている AWS_KEY_ID と AWS_SECRET_KEY の値は、説明のみを目的としています。
load という名前のS3バケットと encrypted_files いう名前のフォルダーパス、およびバケット内に保存されたファイルを復号化/暗号化するマスターキーによるクライアント側の暗号化（デフォルトの暗号化タイプ）を使用して、外部ステージを作成します。
CREATE STAGE my_ext_stage2
  URL='s3://load/encrypted_files/'
  CREDENTIALS=(AWS_KEY_ID='1a2b3c' AWS_SECRET_KEY='4x5y6z')
  ENCRYPTION=(MASTER_KEY = 'eSxX0jzYfIamtnBKOEOwq80Au6NbSgPH5r4BDDwOaO8=');
load という名前のS3バケットと encrypted_files という名前のフォルダーパス、およびバケット内に保存されたファイルを復号化/暗号化するマスターキー向け ID を有する AWS_SSE_KMS サーバー側の暗号化を使用して、外部ステージを作成します。
CREATE STAGE my_ext_stage3
  URL='s3://load/encrypted_files/'
  CREDENTIALS=(AWS_KEY_ID='1a2b3c' AWS_SECRET_KEY='4x5y6z')
  ENCRYPTION=(TYPE='AWS_SSE_KMS' KMS_KEY_ID = 'aws/key');
直前の例と同じ例ですが、S3バケットのSnowflakeアクセス許可は、 IAM ユーザーではなく IAM ロールに関連付けられています。認証情報は、 ENCRYPTION などの他のステージパラメーターとは別に処理されることに注意してください。これらの他のパラメーターのサポートは、外部S3バケットへのアクセスに使用する認証情報に関係なく同じです。
CREATE STAGE my_ext_stage3
  URL='s3://load/encrypted_files/'
  CREDENTIALS=(AWS_ROLE='arn:aws:iam::001234567890:role/mysnowflakerole')
  ENCRYPTION=(TYPE='AWS_SSE_KMS' KMS_KEY_ID = 'aws/key');
ユーザーセッションのアクティブスキーマで、ディレクトリテーブルを使用してステージを作成します。クラウドストレージ URL にはパス files が含まれています。ステージは my_storage_int という名前のストレージ統合を参照します。
CREATE STAGE mystage
  URL='s3://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (
    ENABLE = true
    AUTO_REFRESH = true
  );

Google Cloud Storage

load という名前のプライベート/保護された GCS バケットと files という名前のフォルダーパスを使用して外部ステージを作成します。 myint ストレージ統合により、 GCS バケットへの安全なアクセスが提供されます。
CREATE STAGE my_ext_stage
  URL='gcs://load/files/'
  STORAGE_INTEGRATION = myint;
ユーザーセッションのアクティブスキーマでディレクトリテーブルを使用して、 mystage という名前のステージを作成します。クラウドストレージ URL にはパス files が含まれています。ステージは my_storage_int という名前のストレージ統合を参照します。
CREATE STAGE mystage
  URL='gcs://load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (
    ENABLE = true
    AUTO_REFRESH = true
    NOTIFICATION_INTEGRATION = 'MY_NOTIFICATION_INT'
  );

Microsoft Azure

load という名前のプライベート/保護されたAzureコンテナーと files という名前のフォルダーパスを使用して、外部ステージを作成します。 myint ストレージ統合により、コンテナーへの安全なアクセスが提供されます。
CREATE STAGE my_ext_stage
  URL='azure://myaccount.blob.core.windows.net/load/files/'
  STORAGE_INTEGRATION = myint;
myaccount という名前のAzureストレージアカウントと mycontainer という名前のコンテナーを使用して、 files というフォルダーパスとクライアント側の暗号化を有効にし、外部ステージを作成します。ステージは my_csv_format という名前のファイル形式を参照します。
CREATE STAGE mystage
  URL='azure://myaccount.blob.core.windows.net/mycontainer/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 = 'kPxX0jzYfIamtnJEUTHwq80Au6NbSgPH5r4BDDwOaO8=')
  FILE_FORMAT = my_csv_format;
（この例で使用する AZURE_SAS_TOKEN および MASTER_KEY の値は実際の値ではありません。これらは説明のみを目的として提供されています。）
ユーザーセッションのアクティブスキーマで、ディレクトリテーブルを使用してステージを作成します。クラウドストレージ URL にはパス files が含まれています。ステージは my_storage_int という名前のストレージ統合を参照します。
CREATE STAGE mystage
  URL='azure://myaccount.blob.core.windows.net/load/files/'
  STORAGE_INTEGRATION = my_storage_int
  DIRECTORY = (
    ENABLE = true
    AUTO_REFRESH = true
    NOTIFICATION_INTEGRATION = 'MY_NOTIFICATION_INT'
  );

CREATE STAGE¶

構文¶

必須パラメーター¶

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

内部ステージパラメーター（internalStageParams）¶

外部ステージパラメーター（externalStageParams）¶

ディレクトリテーブルパラメーター（directoryTableParams）¶

外部ステージ¶

形式の種類のオプション（formatTypeOptions）¶

TYPE = CSV¶

TYPE = JSON¶

TYPE = AVRO¶

TYPE = ORC¶

TYPE = PARQUET¶

TYPE = XML¶

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

アクセス制御の要件¶

使用上の注意¶

例¶

内部ステージ¶

外部ステージ¶

内部ステージパラメーター（`internalStageParams`）¶

外部ステージパラメーター（`externalStageParams`）¶

ディレクトリテーブルパラメーター（`directoryTableParams`）¶

形式の種類のオプション（`formatTypeOptions`）¶

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