COPY INTO

파일에서 기존 테이블로 데이터를 로드하는 명령이에요. 파일은 다음 위치 중 하나에 이미 있어야 해요:

이름 있는 내부 스테이지(또는 테이블/사용자 스테이지). 파일은 PUT 명령으로 스테이징할 수 있어요.
외부 위치(Amazon S3, Google Cloud Storage 또는 Microsoft Azure)를 참조하는 이름 있는 외부 스테이지.
외부 위치(Amazon S3, Google Cloud Storage 또는 Microsoft Azure).

검색 전에 복원해야 하는 보관용 클라우드 저장소 클래스에 보관된 데이터는 접근할 수 없어요. 이 보관 저장소 클래스에는 예를 들어 Amazon S3 Glacier Flexible Retrieval 또는 Glacier Deep Archive 저장소 클래스, 또는 Microsoft Azure Archive Storage가 포함돼요.

출처: 문서

본문

구문 (Syntax)

/* 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 ]

여기서:

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

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

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

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

externalLocation (for Microsoft Azure) ::=
  'azure://<account>.blob.core.windows.net/<container>[/<path>]'
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( [ AZURE_SAS_TOKEN = '<string>' ] ) } ]
  [ ENCRYPTION = ( [ TYPE = { 'AZURE_CSE' | 'NONE' } ] [ MASTER_KEY = '<string>' ] ) ]

formatTypeOptions ::=
-- If FILE_FORMAT = ( TYPE = CSV ... )
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     RECORD_DELIMITER = '<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

copyOptions ::=
     CLUSTER_AT_INGEST_TIME = TRUE | FALSE
     ENFORCE_LENGTH = TRUE | FALSE
     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

필수 파라미터

[*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 저장소.
<bucket>은 버킷의 이름이에요.
account는 Azure 계정의 이름(예: myaccount)이에요. Data Lake Storage Gen2를 포함한 모든 지원 유형의 Azure blob 저장소 계정에 대해 blob.core.windows.net 엔드포인트를 사용해요.
container는 Azure 컨테이너의 이름(예: mycontainer)이에요.
<path>는 클라우드 저장소 위치에 있는 파일의 선택적 대소문자 구분 경로(즉 공통 문자열로 시작하는 이름을 가진 파일)로, 로드할 파일 집합을 제한해요. 경로는 서로 다른 클라우드 저장소 서비스에서 접두사 또는 폴더라고도 불려요.

/./ 및 /../ 같은 상대 경로 수정자는 문맥상 "경로"가 이름의 리터럴 접두사이므로 문자 그대로 해석돼요. 예를 들어:

-- S3 bucket
COPY INTO mytable FROM 's3://mybucket/./../a.csv';

COPY INTO

문에 경로를 지정하면 Snowflake는 경로 값을 접두사로 취급하고 외부 위치의 파일 이름에 대해 접두사 일치를 수행해요.

내부 또는 외부 스테이지나 경로 이름에 공백을 포함한 특수 문자가 있으면 FROM ... 문자열을 작은따옴표로 묶어주세요. FROM ... 값은 리터럴 상수여야 해요. SQL 변수일 수 없어요.

추가 클라우드 공급자 파라미터

STORAGE_INTEGRATION = *integration_name* 또는 CREDENTIALS = ( *cloud_specific_credentials* ) COPY 문의 FROM 값이 외부 스테이지 이름이 아닌 외부 저장소 URI일 때 지원돼요. 외부 프라이빗/보호 클라우드 저장소 위치에서 로드할 때만 필요해요. 공용 버킷/컨테이너에는 필요하지 않아요.

데이터 파일이 스테이징된 프라이빗/보호 저장소 컨테이너에 접속하고 접근하기 위한 클라우드 공급자 보안 자격 증명을 지정해요.

Amazon S3

STORAGE_INTEGRATION = *integration_name* 외부 클라우드 저장소에 대한 인증 책임을 Snowflake IAM 엔티티에 위임하는 데 사용되는 스토리지 통합의 이름을 지정해요. 상세 내용은 CREATE STORAGE INTEGRATION을 참고하세요. 스토리지 통합의 사용을 권장해요.

CREDENTIALS = ( AWS_KEY_ID = '*string*' AWS_SECRET_KEY = '*string*' [ AWS_TOKEN = '*string*' ] ) AWS에 접속하고 로드할 파일이 스테이징된 프라이빗/보호 S3 버킷에 접근하기 위한 보안 자격 증명을 지정해요.

자격 증명은 버킷에 대한 Snowflake 접근 권한을 AWS IAM 사용자와 연결했는지 역할과 연결했는지에 따라 달라요:

IAM 사용자: 임시 IAM 자격 증명이 필요해요. 임시(또는 "scoped") 자격 증명은 AWS STS가 생성하며 AWS_KEY_ID, AWS_SECRET_KEY, AWS_TOKEN의 세 구성 요소로 구성돼요. 세 가지 모두 프라이빗/보호 버킷에 접근하는 데 필요해요. 기간이 지나면 만료되어 다시 사용할 수 없어요.

COPY 명령은 복잡한 구문과 자격 증명 같은 민감한 정보를 포함해요. 보안상의 이유로 COPY 명령에서 영구 자격 증명을 사용하지 마세요. 대신 임시 자격 증명을 사용하세요. 영구 자격 증명을 사용해야 한다면 외부 스테이지를 사용하세요.

IAM 역할: 보안 자격 증명과 접근 키를 생략하고 대신 AWS_ROLE로 역할을 식별하고 AWS 역할 ARN을 지정해요.

Google Cloud Storage STORAGE_INTEGRATION = *integration_name* 외부 클라우드 저장소에 대한 인증 책임을 Snowflake IAM 엔티티에 위임하는 데 사용되는 스토리지 통합의 이름을 지정해요.

Microsoft Azure STORAGE_INTEGRATION = *integration_name* 스토리지 통합의 이름을 지정해요. CREDENTIALS = ( AZURE_SAS_TOKEN = '*string*' ) Azure에 접속하고 데이터가 들어 있는 파일이 스테이징된 프라이빗/보호 컨테이너에 접근하기 위한 SAS 토큰을 지정해요.

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

AWS_CSE: 클라이언트 측 암호화(MASTER_KEY 값 필요). MASTER_KEY 값을 제공하면 Snowflake는 TYPE = AWS_CSE로 가정해요.
AWS_SSE_S3: 추가 암호화 설정이 필요 없는 서버 측 암호화.
AWS_SSE_KMS: 선택적 KMS_KEY_ID 값을 받는 서버 측 암호화.
NONE: 암호화 없음.

MASTER_KEY는 Base64로 인코딩된 128비트 또는 256비트 키여야 해요. KMS_KEY_ID 값은 데이터 로딩에 무시돼요.

Google Cloud Storage ENCRYPTION = ( [ TYPE = 'GCS_SSE_KMS' | 'NONE' ] [ KMS_KEY_ID = '*string*' ] )

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

변환 파라미터 (Transformation parameters)

( SELECT [*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 등).
element: 데이터 파일의 반복 값의 경로와 요소 이름(반정형 데이터 파일에만 적용).

SELECT 목록은 로드 중인 데이터 파일의 번호가 매겨진 필드/열 집합을 정의해요. 이 목록은 반드시 대상 테이블의 열 순서와 일치해야 해요. 선택적 ( *col_name* [ , ... ] ) 파라미터를 사용해 이 목록을 대상 테이블의 특정 열에 매핑할 수 있어요.

변환에 사용되는 SELECT 문은 모든 함수를 지원하지 않아요. 로드 중 데이터 변환은 사용자 스테이지와 이름 있는 스테이지(내부 또는 외부)에서만 데이터 선택을 지원해요.

( *col_name* [ , *col_name* ... ] ) 데이터를 삽입하려는 테이블 열의 명시적 목록(쉼표로 구분)을 선택적으로 지정해요. 첫 번째 열은 로드된 파일에서 추출된 첫 번째 필드/열에서 생성된 값을 소비하고, 두 번째 열은 두 번째 값을 소비하는 식으로 지정된 순서대로 돼요. 열은 이 목록에서 반복될 수 없어요. 이 열 목록에서 제외된 열은 기본값(NULL, 지정되지 않은 경우)으로 채워져요. 단, 제외된 열은 기본값으로 시퀀스를 가질 수 없어요.

선택 파라미터

FILES = ( '*file_name*' [ , '*file_name*' ... ] ) 로드할 하나 이상의 파일 이름(쉼표로 구분) 목록을 지정해요. 파일은 명령에 지정된 Snowflake 내부 위치 또는 외부 위치에 이미 스테이징되어야 해요. 지정된 파일 중 하나라도 찾을 수 없으면 기본 동작 ON_ERROR = ABORT_STATEMENT이 로드 작업을 중단해요. 지정할 수 있는 파일 이름의 최대 수는 1000이에요.

외부 스테이지의 경우 파일 경로는 스테이지 정의의 URL과 해석된 파일 이름 목록을 연결해 설정돼요. 단, Snowflake는 경로와 파일 이름 사이에 구분자를 암시적으로 삽입하지 않아요. 스테이지 정의의 URL 끝이나 이 파라미터에 지정된 각 파일 이름의 시작에 구분자(/)를 명시적으로 포함해야 해요.

PATTERN = '*regex_pattern*' 작은따옴표로 묶인 일치시킬 파일 이름 및/또는 경로를 지정하는 정규 표현식 패턴 문자열이에요. 성능을 위해 많은 파일을 필터링하는 패턴은 피하는 것이 좋아요.

정규 표현식은 벌크 데이터 로드와 Snowpipe 데이터 로드에 다르게 적용돼요:

Snowpipe는 스테이지 정의의 모든 경로 세그먼트를 저장소 위치에서 잘라내고 남은 경로 세그먼트와 파일 이름에 정규 표현식을 적용해요.
벌크 데이터 로드 작업은 FROM 절의 전체 저장소 위치에 정규 표현식을 적용해요.

FILES와 PATTERN 옵션을 함께 사용하면 FILES 옵션에 지정된 경로만 로드돼요. 이 두 옵션을 함께 사용하지 않는 것이 좋아요.

FORMAT_NAME은 테이블에 데이터를 로드하는 데 사용할 기존의 이름 있는 파일 형식을 지정해요. 이름 있는 파일 형식은 데이터 파일의 형식 유형(CSV, JSON 등)과 기타 형식 옵션을 결정해요.
TYPE은 테이블에 로드할 파일의 유형을 지정해요. 형식 유형을 지정하면 형식별 추가 옵션을 지정할 수 있어요.

FORMAT_NAME과 TYPE은 상호 배타적이에요. 같은 COPY 명령에 둘 다 지정하면 예기치 않은 동작이 발생할 수 있어요.

COPY_OPTIONS = ( ... ) 로드된 데이터에 대한 하나 이상의 copy 옵션을 지정해요.

VALIDATION_MODE = RETURN_*n*_ROWS | RETURN_ERRORS | RETURN_ALL_ERRORS COPY 명령이 파일을 지정된 테이블에 로드하는 대신 검증하도록 지시하는 문자열(상수)이에요. 즉 COPY 명령은 파일에 오류가 있는지 테스트하지만 로드하지는 않아요.

지원 값	참고
RETURN_n_ROWS (예: RETURN_10_ROWS)	오류가 없으면 지정된 수의 행을 검증하고, 그렇지 않으면 행에서 만난 첫 번째 오류에서 실패해요.
RETURN_ERRORS	COPY 문에 지정된 모든 파일의 모든 오류(파싱, 변환 등)를 반환해요.
RETURN_ALL_ERRORS	COPY 문에 지정된 모든 파일의 모든 오류를 반환하며, 이전 로드 중 ON_ERROR copy 옵션이 CONTINUE로 설정되어 부분적으로 로드된 오류가 있는 파일도 포함해요.

VALIDATION_MODE는 로드 중 데이터를 변환하는 COPY 문을 지원하지 않아요. 이 파라미터를 지정하면 COPY 문이 오류를 반환해요.
VALIDATION_MODE는 Iceberg 테이블에 지원되지 않아요.
이전 로드 중 만난 모든 오류를 보려면 VALIDATE 테이블 함수를 사용하세요. 이 함수도 로드 중 데이터를 변환하는 COPY 문을 지원하지 않아요.

형식 유형 옵션 (formatTypeOptions)

지정된 파일 형식 유형(FILE_FORMAT = ( TYPE = ... ))에 따라 하나 이상의 형식별 옵션을 포함할 수 있어요.

TYPE = CSV

지원 값	참고
AUTO	Brotli 압축 파일을 제외하고 압축 알고리즘을 자동 감지해요. Brotli 압축 파일을 로드하려면 AUTO 대신 BROTLI를 명시적으로 사용하세요.
GZIP
BZ2
BROTLI	Brotli 압축 파일을 로드할 때 반드시 지정해야 해요.
ZSTD	Zstandard v0.8(이상) 지원.
DEFLATE	Deflate 압축 파일(zlib 헤더 포함, RFC1950).
RAW_DEFLATE	Raw Deflate 압축 파일(헤더 없음, RFC1951).
NONE	로드할 데이터 파일이 압축되지 않았어요.

기본값: AUTO

RECORD_DELIMITER = 'string' | NONE 입력 파일에서 레코드를 구분하는 하나 이상의 문자예요. 싱글바이트 문자는 8진수 값(\\ 접두사) 또는 16진수 값(0x 또는 \\x 접두사)을 사용하고, 멀티바이트 문자는 16진수 값(\\x 접두사)을 사용해요. RECORD_DELIMITER 또는 FIELD_DELIMITER의 구분자는 다른 파일 형식 옵션의 구분자 하위 문자열일 수 없어요. 지정된 구분자는 유효한 UTF-8 문자여야 하고 최대 20자로 제한돼요. NONE 값도 허용돼요. 기본값: 새 줄 문자(Windows에서는 \r\n이 새 줄로 이해돼요).

FIELD_DELIMITER = 'string' | NONE 입력 파일에서 필드를 구분하는 하나 이상의 싱글바이트 또는 멀티바이트 문자예요. RECORD_DELIMITER와 같은 규칙이 적용돼요. 기본값: 쉼표(,).

MULTI_LINE = TRUE | FALSE 여러 줄이 허용되는지 지정하는 부울이에요. FALSE로 설정되고 지정된 레코드 구분자가 CSV 필드 안에 있으면 해당 필드를 포함한 레코드는 오류로 해석돼요. 기본값: TRUE.

RFC4180 사양을 따르는 큰 압축되지 않은 CSV 파일(128MB 초과)을 로드할 때, MULTI_LINE = FALSE, COMPRESSION = NONE, ON_ERROR = ABORT_STATEMENT 또는 CONTINUE로 설정하면 Snowflake는 병렬 스캔을 지원해요.

PARSE_HEADER = TRUE | FALSE 데이터 파일의 첫 행 헤더를 사용해 열 이름을 결정할지 지정하는 부울이에요. 이 파일 형식 옵션은 INFER_SCHEMA 함수로 열 정의를 자동 감지하는 경우와 MATCH_BY_COLUMN_NAME copy 옵션으로 CSV 데이터를 별도 열에 로드하는 경우에만 적용돼요. TRUE로 설정하면 첫 행 헤더가 열 이름을 결정하는 데 사용돼요. 기본값 FALSE는 열 이름을 c*(*는 열 위치)로 반환해요. PARSE_HEADER = TRUE에서는 SKIP_HEADER 옵션이 지원되지 않아요. 기본값: 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 감싸진 필드 값에만 사용되는 이스케이프 문자인 싱글바이트 문자예요. 데이터에서 FIELD_OPTIONALLY_ENCLOSED_BY 문자의 인스턴스를 리터럴로 해석하는 데 사용할 수 있어요. 일반적인 이스케이프 시퀀스(예: \t 탭, \n 새 줄, \r 캐리지 리턴, \\ 백슬래시), 8진수 값, 16진수 값을 허용해요. 이 파일 형식 옵션은 싱글바이트 문자만 지원해요. 기본값: NONE.

ESCAPE_UNENCLOSED_FIELD = 'character' | NONE 감싸지지 않은 필드 값에만 사용되는 이스케이프 문자인 싱글바이트 문자예요. 데이터에서 FIELD_DELIMITER 또는 RECORD_DELIMITER 문자의 인스턴스를 리터럴로 해석하는 데 사용할 수 있어요. 기본값은 \\(백슬래시)예요. 데이터 파일의 행이 백슬래시(\) 문자로 끝나면 이 문자는 RECORD_DELIMITER 파일 형식 옵션에 지정된 새 줄이나 캐리지 리턴 문자를 이스케이프해요. 그 결과 로드 작업은 이 행과 다음 행을 단일 데이터 행으로 취급해요. 이 문제를 피하려면 값을 NONE으로 설정하세요.

TRIM_SPACE = TRUE | FALSE 필드에서 공백을 제거할지 지정하는 부울이에요. 예를 들어 필드 구분자가 |이고 FIELD_OPTIONALLY_ENCLOSED_BY = '"'일 때:

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

는 다음이 돼요:

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

기본값: FALSE

FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE 문자열을 감싸는 데 사용되는 문자예요. 값은 NONE, 작은따옴표 문자(') 또는 큰따옴표 문자(")일 수 있어요. 기본값: NONE.

NULL_IF = ( [ 'string1' [ , 'string2' ... ] ] ) SQL NULL로 변환하는 데 사용되는 문자열이에요. Snowflake는 데이터 로드 소스에서 이러한 문자열을 SQL NULL로 대체해요. Snowflake는 데이터 유형과 관계없이 값의 모든 인스턴스를 NULL로 변환해요. 예를 들어 값으로 2를 지정하면 문자열이나 숫자로서의 2 인스턴스가 모두 변환돼요. 기본값: \N.

ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE 입력 데이터 파일의 구분 열(즉 필드) 수가 해당 테이블의 열 수와 일치하지 않으면 파싱 오류를 생성할지 지정하는 부울이에요. FALSE로 설정하면 오류가 생성되지 않고 로드가 계속돼요. 기본값: TRUE.

로드 중 데이터를 변환할 때(즉 COPY INTO

명령의 소스로 쿼리를 사용할 때) 이 옵션은 무시돼요.

REPLACE_INVALID_CHARACTERS = TRUE | FALSE 잘못된 UTF-8 문자를 유니코드 대체 문자(�)로 바꿀지 지정하는 부울이에요. TRUE로 설정하면 Snowflake는 잘못된 UTF-8 문자를 유니코드 대체 문자로 교체해요. FALSE로 설정하면 잘못된 UTF-8 문자 인코딩이 감지될 때 로드 작업이 오류를 생성해요. 기본값: FALSE.

EMPTY_FIELD_AS_NULL = TRUE | FALSE 두 개의 연속 구분자(예: ,,)로 표시되는 입력 파일의 빈 필드에 SQL NULL을 삽입할지 지정하는 부울이에요. FALSE로 설정하면 Snowflake는 빈 필드를 해당 열 유형으로 캐스팅하려고 시도해요. 기본값: TRUE.

SKIP_BYTE_ORDER_MARK = TRUE | FALSE 데이터 파일에 있으면 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, ISO-8859-2, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, ISO-8859-15, KOI8-R(KOI8R), Shift_JIS(SHIFTJIS), UTF-8(UTF8), UTF-16(UTF16), UTF-16BE(UTF16BE), UTF-16LE(UTF16LE), UTF-32(UTF32), UTF-32BE(UTF32BE), UTF-32LE(UTF32LE), windows-874, windows-949(한국어), windows-1250, windows-1251, windows-1252, windows-1253, windows-1254, windows-1255, windows-1256.

기본값: UTF8. Snowflake는 모든 데이터를 내부적으로 UTF-8 문자 집합으로 저장해요. 데이터는 Snowflake에 로드되기 전에 UTF-8로 변환돼요.

TYPE = JSON

DATE_FORMAT / TIME_FORMAT / TIMESTAMP_FORMAT 각각 JSON 데이터를 MATCH_BY_COLUMN_NAME copy 옵션으로 별도 열에 로드할 때와 COPY 문에 쿼리를 지정해(즉 COPY 변환) JSON 데이터를 별도 열에 로드할 때의 날짜/시간/타임스탬프 형식을 정의해요. 기본값: AUTO.

BINARY_FORMAT 데이터 파일의 바이너리 문자열 값의 인코딩 형식을 정의해요. 기본값: HEX.

TRIM_SPACE = TRUE | FALSE 문자열에서 선행/후행 공백을 제거할지 지정해요. 기본값: FALSE.

MULTI_LINE = TRUE | FALSE 여러 줄이 허용되는지 지정해요. FALSE로 설정되고 JSON 레코드 안에 새 줄이 있으면 그 레코드는 오류로 해석돼요. 기본값: TRUE.

NULL_IF SQL NULL로 변환하는 데 사용되는 문자열이에요. 기본값: \N.

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] → [], {"a":null,"b":null,"c":123} → {"c":123}이 돼요. 기본값: FALSE.

REPLACE_INVALID_CHARACTERS 잘못된 UTF-8 문자를 유니코드 대체 문자로 바꿀지 지정해요. 기본값: FALSE.

IGNORE_UTF8_ERRORS = TRUE | FALSE UTF-8 인코딩 오류가 오류 상태를 생성하는지 지정하는 부울이에요. REPLACE_INVALID_CHARACTERS의 대체 구문이에요. TRUE로 설정하면 잘못된 UTF-8 시퀀스는 조용히 유니코드 문자 U+FFFD("대체 문자")로 교체돼요. 기본값: FALSE.

SKIP_BYTE_ORDER_MARK 입력 파일에 있는 BOM을 건너뛸지 지정해요. 기본값: TRUE.

TYPE = AVRO

TRIM_SPACE 문자열에서 선행/후행 공백을 제거할지 지정해요(Avro 데이터를 MATCH_BY_COLUMN_NAME copy 옵션으로 별도 열에 로드할 때만 적용). 기본값: FALSE.

REPLACE_INVALID_CHARACTERS 잘못된 UTF-8 문자를 유니코드 대체 문자로 바꿀지 지정해요. 기본값: FALSE.

NULL_IF SQL NULL로 변환하는 데 사용되는 문자열이에요. 기본값: \N.

TYPE = ORC

TRIM_SPACE 기본값: FALSE. REPLACE_INVALID_CHARACTERS 기본값: FALSE. NULL_IF 기본값: \N. (자세한 설명은 CSV/AVRO와 동일해요.)

TYPE = PARQUET

COMPRESSION = AUTO | SNAPPY | NONE 로드할 데이터 파일의 현재 압축 알고리즘을 지정해요.

지원 값	참고
AUTO	압축 알고리즘을 자동 감지해요. Brotli, gzip, LZO, LZ4, Snappy, Zstandard v0.8(이상) 압축 알고리즘을 지원해요.
SNAPPY
NONE	로드할 데이터 파일이 압축되지 않았어요.

기본값: AUTO

BINARY_AS_TEXT = TRUE | FALSE 정의된 논리 데이터 유형이 없는 열을 UTF-8 텍스트로 해석할지 지정하는 부울이에요. FALSE로 설정하면 Snowflake는 이러한 열을 바이너리 데이터로 해석해요. 기본값: TRUE. 잠재적 변환 문제를 피하려면 BINARY_AS_TEXT를 FALSE로 설정하는 것이 좋아요.

USE_LOGICAL_TYPE = TRUE | FALSE Parquet 논리 유형을 사용할지 지정하는 부울이에요. 이 파일 형식 옵션에서 Snowflake는 데이터 로드 중 Parquet 논리 유형을 해석할 수 있어요. 기본값: FALSE.

USE_VECTORIZED_SCANNER = TRUE | FALSE Parquet 파일 로드에 벡터화 스캐너를 사용할지 지정하는 부울이에요. 기본값은 FALSE지만 향후 BCR에서 기본값은 TRUE가 될 예정이에요. 벡터화 스캐너를 사용하면 Parquet 파일 로드의 지연 시간을 크게 줄일 수 있어요. TRUE로 설정하면 BINARY_AS_TEXT 옵션은 항상 FALSE로, USE_LOGICAL_TYPE 옵션은 항상 TRUE로 처리돼요. 벡터화 스캐너는 Parquet 맵 유형을 지원하고, 출력에 NULL 값을 보여주며, Time/Timestamp 처리 방식이 다를 수 있어요.

REPLACE_INVALID_CHARACTERS 기본값: FALSE. NULL_IF 기본값: \N.

TYPE = XML

IGNORE_UTF8_ERRORS 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 기본값: FALSE. SKIP_BYTE_ORDER_MARK 기본값: TRUE.

Copy 옵션 (copyOptions)

하나 이상의 copy 옵션을 지정할 수 있어요.

CLUSTER_AT_INGEST_TIME = TRUE | FALSE 클러스터링 키로 구성된 테이블에 대해 수집 중 데이터를 직접 사전 클러스터링할지 지정하는 부울이에요. TRUE로 설정하면 이 옵션은 Snowpipe Streaming(고성능 아키텍처)이 데이터를 커밋하기 전에 대상 테이블의 클러스터링 키에 기반해 데이터를 정렬하도록 해요. 이 기능은 Snowpipe Streaming의 고성능 아키텍처에서만 사용할 수 있어요. 기본값: FALSE.

사전 클러스터링 기능을 사용할 때 대상 테이블의 자동 클러스터링 기능을 비활성화하지 마세요. 비활성화하면 시간이 지나면서 쿼리 성능이 저하될 수 있어요.

ENFORCE_LENGTH = TRUE | FALSE TRUNCATECOLUMNS의 대체 구문으로 논리가 반대예요(다른 시스템과의 호환성용). 대상 열 길이를 초과하는 텍스트 문자열을 자를지 지정하는 부울이에요. TRUE이면 로드된 문자열이 대상 열 길이를 초과하면 COPY 문이 오류를 생성해요. FALSE이면 문자열이 대상 열 길이로 자동 잘려요. 기본값: TRUE.

대상 문자열 열의 길이가 최대값(예: VARCHAR (134217728))으로 설정되면 들어오는 문자열은 이 길이를 초과할 수 없어요. 그렇지 않으면 COPY 명령이 오류를 생성해요. 이 파라미터는 기능적으로 TRUNCATECOLUMNS와 동일하지만 동작은 반대예요.

FORCE = TRUE | FALSE 이전에 로드되었고 로드 후 변경되지 않은 파일을 포함해 모든 파일을 로드할지 지정하는 부울이에요. 이 옵션은 파일을 다시 로드해 테이블의 데이터를 중복시킬 수 있어요. 기본값: FALSE.

INCLUDE_METADATA = ( *column_name* = METADATA$*field* [ , ... ] ) 대상 테이블의 기존 열을 METADATA$ 열에 매핑하는 사용자 정의 매핑이에요. 이 copy 옵션은 MATCH_BY_COLUMN_NAME copy 옵션에서만 사용할 수 있어요. METADATA$*field*의 유효한 입력: METADATA$FILENAME, METADATA$FILE_ROW_NUMBER, METADATA$FILE_CONTENT_KEY, METADATA$FILE_LAST_MODIFIED, METADATA$START_SCAN_TIME.

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

INCLUDE_METADATA 대상 열 이름은 먼저 테이블에 존재해야 해요. INCLUDE_METADATA 열에 고유한 열 이름을 사용하세요. INCLUDE_METADATA로 CSV 파일을 로드할 때 파일 형식 옵션 ERROR_ON_COLUMN_COUNT_MISMATCH를 FALSE로 설정하세요.

LOAD_MODE = { FULL_INGEST | ADD_FILES_COPY } Snowflake 관리 Iceberg 테이블에 Parquet 파일에서 데이터를 로드할 때 사용할 모드를 지정해요.

FULL_INGEST: Snowflake가 파일을 스캔하고 Iceberg 테이블의 기본 위치 아래에 Parquet 데이터를 다시 써요.
ADD_FILES_COPY: Snowflake가 원래 Parquet 파일을 Iceberg 테이블의 기본 위치로 서버 측 복사한 다음 파일을 테이블에 등록해요. 이 작업은 원시 Parquet 파일의 크로스 리전 또는 크로스 클라우드 수집을 가능하게 해요.

ADD_FILES_COPY 옵션은 변환 없이 Iceberg 호환 원시 Parquet 파일에서 데이터를 로드할 때만 지원돼요. 기본값: FULL_INGEST.

LOAD_UNCERTAIN_FILES = TRUE | FALSE 로드 상태가 알려지지 않은 파일을 로드할지 지정하는 부울이에요. COPY 명령은 기본적으로 이러한 파일을 건너뛰어요. 로드 상태는 다음 조건이 모두 참일 때 알 수 없어요: 파일의 LAST_MODIFIED 날짜가 64일보다 이전, 초기 데이터 세트가 64일보다 전에 테이블에 로드됨, 파일이 이미 성공적으로 로드된 경우 이 이벤트가 64일보다 전에 발생. 기본값: FALSE.

MATCH_BY_COLUMN_NAME = CASE_SENSITIVE | CASE_INSENSITIVE | NONE 반정형 데이터를 데이터에 표현된 해당 열과 일치하는 대상 테이블의 열에 로드할지 지정하는 문자열이에요.

로드 중 데이터를 변환하는 SELECT 문과 MATCH_BY_COLUMN_NAME copy 옵션을 함께 사용하지 마세요. 함께 사용하면 SQL compilation error: match_by_column_name is not supported with copy transform. 오류가 발생해요.

이 copy 옵션은 JSON, Avro, ORC, Parquet, CSV 형식을 지원해요. 열이 일치하려면 다음 조건이 참이어야 해요: 데이터에 표현된 열은 테이블의 열과 정확히 같은 이름이어야 하고, 테이블의 열은 데이터에 표현된 열의 값과 호환되는 데이터 유형이어야 해요.

CASE_SENSITIVE | CASE_INSENSITIVE: 데이터에 표현된 해당 열과 일치하는 대상 테이블의 열에 반정형 데이터를 로드해요. 열 이름은 대소문자를 구분하거나(CASE_SENSITIVE) 대소문자를 구분하지 않아요(CASE_INSENSITIVE). COPY 작업은 대상 테이블의 열 중 하나 이상이 데이터 파일에 표현된 열과 일치하는지 확인해요.
NONE: COPY 작업은 반정형 데이터를 VARIANT 열에 로드하거나, COPY 문에 쿼리가 포함되어 있으면 데이터를 변환해요.

기본값: NONE.

현재 제한 사항: MATCH_BY_COLUMN_NAME은 검증을 위해 VALIDATION_MODE 파라미터와 함께 사용할 수 없어요. Parquet 데이터의 경우 MATCH_BY_COLUMN_NAME이 CASE_SENSITIVE 또는 CASE_INSENSITIVE로 설정되면 빈 열 값(예: "col1": "")이 오류를 생성해요.

ON_ERROR = CONTINUE | SKIP_FILE | SKIP_FILE_*num* | 'SKIP_FILE_*num*%' | ABORT_STATEMENT 로드 작업의 오류 처리를 지정하는 문자열(상수)이에요.

CONTINUE: 오류가 발견되면 파일을 계속 로드해요. COPY 문은 데이터 파일당 최대 한 개의 오류에 대한 오류 메시지를 반환해요. ROWS_PARSED와 ROWS_LOADED 열 값의 차이는 감지된 오류를 포함한 행 수를 나타내요.
SKIP_FILE: 오류가 발견되면 파일을 건너뛰어요. SKIP_FILE 동작은 오류 유무와 관계없이 전체 파일을 버퍼링하므로 CONTINUE나 ABORT_STATEMENT보다 느려요.
- SKIP_FILE_*num*(예: SKIP_FILE_10): 파일에서 발견된 오류 행 수가 지정된 수와 같거나 초과하면 파일을 건너뛰어요.
- 'SKIP_FILE_*num*%'(예: 'SKIP_FILE_10%'): 파일에서 발견된 오류 행의 비율이 지정된 비율을 초과하면 파일을 건너뛰어요.
ABORT_STATEMENT: 데이터 파일에서 오류가 발견되면 로드 작업을 중지해요.

기본값: 벌크 로드(COPY 사용)는 ABORT_STATEMENT, Snowpipe는 SKIP_FILE.

PURGE = TRUE | FALSE 데이터가 성공적으로 로드된 후 스테이지에서 데이터 파일을 자동으로 제거할지 지정하는 부울이에요. TRUE로 설정하면 성공적으로 로드된 데이터 파일을 제거하려고 시도해요. 기본값: FALSE.

RETURN_FAILED_ONLY = TRUE | FALSE 문 결과에서 로드에 실패한 파일만 반환할지 지정하는 부울이에요. 기본값: FALSE.

SIZE_LIMIT = *num* 주어진 COPY 문에 대해 로드할 데이터의 최대 크기(바이트)를 지정하는 숫자(> 0)예요. 임계값을 초과하면 COPY 작업은 파일 로드를 중단해요. 기본값: null(크기 제한 없음).

TRUNCATECOLUMNS = TRUE | FALSE ENFORCE_LENGTH의 대체 구문으로 논리가 반대예요. 대상 열 길이를 초과하는 텍스트 문자열을 자를지 지정하는 부울이에요. TRUE이면 문자열이 대상 열 길이로 자동 잘려요. FALSE이면 로드된 문자열이 대상 열 길이를 초과하면 COPY 문이 오류를 생성해요. 기본값: FALSE.

사용 참고사항 (Usage notes)

일부 사용 사례는 완전히 지원되지 않아 일관되지 않거나 예기치 않은 ON_ERROR 동작이 발생할 수 있어요. 여기에는 SELECT 문에서 DISTINCT 키워드 지정, 클러스터된 테이블에서 COPY 사용이 포함돼요.
분할된 Iceberg 테이블의 경우: ON_ERROR = CONTINUE를 설정했어도 Snowflake가 파티션 변환에서 오류를 만나면 COPY 작업이 실패해요. LOAD_MODE = ADD_FILES_COPY는 지원되지 않아요.
CSV 데이터를 로드할 때 대상 테이블에 스트림이 있으면 ON_ERROR copy 옵션이 예상대로 작동하지 않을 수 있어요.
Google Cloud Storage에서만 로드: 외부 스테이지에 대해 반환된 객체 목록에는 하나 이상의 "디렉터리 blob"이 포함될 수 있어요. 본질적으로 슬래시 문자(/)로 끝나는 경로예요. COPY 문이 이 객체 목록에 디렉터리 blob이 있을 때 실패할 수 있어요. 오류를 피하려면 파일 목록에 디렉터리 blob이 포함될 때 파일 포함을 식별하기 위해 패턴 일치(즉 PATTERN 절)를 사용하는 것이 좋아요. 또는 COPY 문에서 ON_ERROR = SKIP_FILE을 설정하세요.
STORAGE_INTEGRATION, CREDENTIALS, ENCRYPTION은 프라이빗/보호 저장소 위치에서 직접 로드할 때만 적용돼요. 공용 버킷에서 로드하면 안전한 접근이 필요하지 않아요.
COPY 명령 실행 중 오류가 발생하면 명령 완료 후 VALIDATE 테이블 함수로 오류를 생성한 파일을 검증할 수 있어요. VALIDATE 함수는 표준 데이터 로드를 수행하는 COPY 명령에 대해서만 출력을 반환해요.
copy 옵션 중 하나로 FORCE = TRUE를 명시적으로 지정하지 않으면 명령은 이미 테이블에 로드된 스테이징 데이터 파일을 무시해요.
COPY 명령은 Parquet 파일의 데이터 유형 변환을 검증하지 않아요.
VALIDATION_MODE는 Iceberg 테이블에 지원되지 않아요.
LOAD_MODE = ADD_FILES_COPY 사용 시 전제 조건: 대상 테이블은 소스 Parquet 파일 데이터 유형과 호환되는 열 데이터 유형을 가진 Snowflake 관리 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%, 로드 전 데이터 변환/필터링.
ADD_FILES_COPY의 경우 더 큰 웨어하우스를 사용해도 COPY 쿼리 지속 시간이 크게 줄어들지 않아요. 대부분의 COPY 작업은 Cloud Services 컴퓨트 리소스에 의존해요.
Parquet 파일의 행 계보 메타데이터 열(_row_id와 _last_updated_sequence_number)을 로드하려면 FULL_INGEST 옵션을 사용해야 해요.
스토리지 통합을 사용하는 외부 스테이지로 이 명령을 실행하려면 스토리지 통합에 대한 USAGE 권한이 있거나 상속한 역할을 사용해야 해요.
아웃바운드 프라이빗 연결의 경우 외부 위치(외부 저장소 URI)에서 직접 로드하는 것은 지원되지 않아요. 대신 아웃바운드 프라이빗 연결용으로 구성된 스토리지 통합이 있는 외부 스테이지를 사용하세요.

출력 (Output)

이 명령은 다음 열을 반환해요:

열 이름	데이터 유형	설명
FILE	TEXT	원본 파일의 이름과 파일까지의 상대 경로
STATUS	TEXT	상태: loaded, load failed 또는 partially loaded
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	첫 번째 오류의 열 이름

예 (Examples)

내부 스테이지에서 파일 로드

이 예들은 파일이 이전에 PUT 명령으로 스테이지에 복사되었다고 가정해요.

이름 있는 내부 스테이지에서 테이블로 파일 로드:

COPY INTO mytable
FROM @my_int_stage;

테이블의 스테이지에서 테이블로 파일 로드:

COPY INTO mytable
FILE_FORMAT = (TYPE = CSV);

테이블 위치의 파일에서 데이터를 복사할 때 Snowflake는 테이블 위치에서 파일을 자동으로 확인하므로 FROM 절을 생략할 수 있어요.

사용자 개인 스테이지에서 테이블로 파일 로드:

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

이름 있는 외부 스테이지에서 파일 로드

CREATE STAGE 명령으로 만든 이름 있는 외부 스테이지에서 파일 로드. 이름 있는 외부 스테이지는 외부 위치를 참조하고 위치에 접근하는 데 필요한 모든 자격 증명과 기타 세부 정보를 포함해요:

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

열 일치를 사용해 파일 로드

MATCH_BY_COLUMN_NAME copy 옵션으로 파일의 열 이름을 대소문자 구분 없이 테이블에 정의된 열 이름과 일치시켜 이름 있는 외부 스테이지에서 테이블로 파일 로드:

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

외부 위치에서 직접 파일 로드

이 옵션은 아웃바운드 프라이빗 연결에서 지원되지 않아요. 대신 외부 스테이지를 사용하세요.

Amazon S3:

COPY INTO mytable
  FROM s3://mybucket/data/files
  STORAGE_INTEGRATION = myint
  ENCRYPTION=(MASTER_KEY = 'eSx...')
  FILE_FORMAT = (FORMAT_NAME = my_csv_format);

Google Cloud Storage:

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

Microsoft Azure:

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

패턴 일치를 사용해 로드

패턴 일치를 사용해 임의 경로의 압축된 CSV 파일에서만 데이터를 로드:

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

여기서 .*는 "임의 문자의 0회 이상 발생"으로 해석돼요. 대괄호는 파일 확장자 앞의 마침표 문자(.)를 이스케이프해요.

파일 이름에 sales 문자열을 포함한 압축되지 않은 CSV 파일만 로드:

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

JSON 데이터를 VARIANT 열에 로드

JSON 데이터를 VARIANT 유형의 단일 열 테이블에 로드:

/* 외부 배열을 제거하는 JSON 파일 형식 생성 */
CREATE OR REPLACE FILE FORMAT json_format
  TYPE = 'JSON'
  STRIP_OUTER_ARRAY = TRUE;

/* JSON 파일 형식을 참조하는 내부 스테이지 생성 */
CREATE OR REPLACE STAGE mystage
  FILE_FORMAT = json_format;

/* JSON 파일 스테이징 */
PUT file:///tmp/sales.json @mystage AUTO_COMPRESS=TRUE;

/* 대상 테이블 생성 */
CREATE OR REPLACE TABLE house_sales (src VARIANT);

/* JSON 데이터를 대상 테이블로 복사 */
COPY INTO house_sales
   FROM @mystage/sales.json.gz;

SELECT * FROM house_sales;

파일 다시 로드

FORCE = TRUE를 COPY 명령에 추가해 변경되지 않은(즉 처음 로드했을 때와 같은 체크섬을 가진) 스테이징 데이터 파일 세트에서 데이터를 다시 로드(중복)해요:

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

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

로드 후 파일 정리 (Purging)

ALTER TABLE mytable SET STAGE_COPY_OPTIONS = (PURGE = TRUE);

COPY INTO mytable;

또는 COPY 명령에서 직접 copy 옵션을 재정의할 수 있어요:

COPY INTO mytable PURGE = TRUE;

파일이 테이블에 로드된 후 파일은 저장된 버킷 또는 컨테이너에서 삭제돼요. 삭제 프로세스가 시작된 후에는 쿼리를 취소할 수 없어요.

스테이징된 파일 검증

로드하지 않고 스테이지의 파일을 검증해요. 검증 모드에서 COPY 명령을 실행해 모든 오류 확인:

COPY INTO mytable VALIDATION_MODE = 'RETURN_ERRORS';

지정된 수의 행에 대해 검증 모드로 COPY 명령 실행:

COPY INTO mytable VALIDATION_MODE = 'RETURN_2_ROWS';

Iceberg 테이블에 Iceberg 호환 Parquet 데이터 로드

Iceberg 테이블을 만들고 외부 스테이지의 Iceberg 호환 Parquet 데이터 파일에서 데이터를 로드하는 예시예요.

스테이징된 Parquet 파일을 설명하는 파일 형식 객체 생성:

CREATE OR REPLACE FILE FORMAT my_parquet_format
  TYPE = PARQUET
  USE_VECTORIZED_SCANNER = TRUE;

소스 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 INTO 문으로 데이터 로드:

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;

v3 Apache Iceberg™ 테이블에 파일 로드

COPY INTO my_v3_iceberg_table
  FROM @my_json_stage
  FILE_FORMAT = 'my_json_format'
  MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;

COPY INTO <table>

본문