카테고리:

DML 명령 - 데이터 언로딩

COPY INTO <위치>

테이블(또는 쿼리)에서 데이터를 다음 위치 중 하나에 있는 하나 이상의 파일로 언로딩합니다.

  • 명명된 내부 스테이지(또는 테이블/사용자 스테이지). 그런 다음, GET 명령을 사용하여 스테이지/위치에서 파일을 다운로드할 수 있습니다.

  • 외부 위치를 참조하는 명명된 외부 스테이지(Amazon S3, Google Cloud Storage 또는 Microsoft Azure).

  • 외부 위치(Amazon S3, Google Cloud Storage 또는 Microsoft Azure).

참고 항목:

COPY INTO <테이블>

이 항목의 내용:

구문

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

여기서:

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

필수 매개 변수

INTO ...

데이터 파일이 언로딩되는 내부 또는 외부 위치를 지정합니다.

@[namespace.]int_stage_name[/path]

파일은 지정된 명명된 내부 스테이지로 언로딩됩니다.

@[namespace.]ext_stage_name[/path]

파일은 지정된 명명된 외부 스테이지로 언로딩됩니다.

@[namespace.]%table_name[/path]

파일은 지정된 테이블의 스테이지로 언로딩됩니다.

@~[/path]

파일은 현재 사용자의 스테이지로 언로딩됩니다.

's3://bucket[/path]'

파일은 지정된 외부 위치(S3 버킷)로 언로딩됩니다. 추가 매개 변수가 필요할 수 있습니다. 자세한 내용은 이 항목에 있는 추가 클라우드 공급자 매개 변수 섹션을 참조하십시오.

'gcs://bucket[/path]'

파일은 지정된 외부 위치(Google Cloud Storage 버킷)로 언로딩됩니다. 추가 매개 변수가 필요할 수 있습니다. 자세한 내용은 이 항목에 있는 추가 클라우드 공급자 매개 변수 섹션을 참조하십시오.

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

파일은 지정된 외부 위치(Azure 컨테이너)로 언로딩됩니다. 추가 매개 변수가 필요할 수 있습니다. 자세한 내용은 이 항목에 있는 추가 클라우드 공급자 매개 변수 섹션을 참조하십시오.

여기서:

  • namespacedatabase_name.schema_name 또는 schema_name 형식의 내부 또는 외부 스테이지가 있는 데이터베이스 및/또는 스키마입니다. 데이터베이스와 스키마가 현재 사용자 세션 내에서 사용 중인 경우 이는 선택 사항 입니다. 사용 중이지 않으면 필수 사항입니다.

  • 선택적 path 매개 변수는 언로딩된 데이터가 있는 파일의 폴더 및 파일 이름 접두사를 지정합니다. 파일 이름 접두사가 path 에 포함되지 않거나 PARTITION BY 매개 변수가 지정된 경우, 생성된 데이터 파일의 파일 이름에는 data_ 가 접두사로 붙습니다.

    《경로》는 이름의 리터럴 접두사이므로, /.//../ 와 같은 상대 경로 한정자는 문자 그대로 해석됩니다. 예:

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

    이러한 COPY 문에서, Snowflake는 저장소 위치에 문자 그대로 ./../a.csv 로 명명된 파일을 만듭니다.

참고

  • 내부 또는 외부 스테이지나 경로 이름에 공백을 포함한 특수 문자가 포함된 경우, INTO ... 문자열을 작은따옴표로 묶습니다.

  • INTO ... 값은 리터럴 상수여야 합니다. 이 값이 SQL 변수 일 수는 없습니다.

FROM ...

테이블 또는 쿼리가 될 수 있는 언로딩할 데이터의 소스를 지정합니다.

[namespace.]table_name

데이터가 언로딩되는 원본 테이블의 이름을 지정합니다.

네임스페이스는 database_name.schema_name 또는 schema_name 형식으로 테이블이 있는 데이터베이스 및/또는 스키마를 선택적으로 지정합니다. 데이터베이스와 스키마가 현재 사용자 세션 내에서 사용 중인 경우 이는 선택 사항 입니다. 사용 중이지 않으면 필수 사항입니다.

( query )

파일로 언로딩할 데이터를 반환하는 SELECT 문입니다. 쿼리에 LIMIT / FETCH 절을 지정하여 반환되는 행 수를 제한할 수 있습니다.

참고

CAST , :: 함수를 사용하여 열 값을 데이터 타입으로 캐스팅할 때 데이터 타입이 모든 열 값을 지원하는지 확인합니다. 지정된 데이터 타입에 대해 너무 긴 값은 잘릴 수 있습니다.

추가 클라우드 공급자 매개 변수

STORAGE_INTEGRATION = integration_name 또는 . CREDENTIALS = ( cloud_specific_credentials )

COPY 문이 대상 클라우드 저장소 위치에 대한 외부 스테이지 이름이 아닌 외부 저장소 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' ] ) 또는 . CREDENTIALS = ( AWS_ROLE = 'string' )

AWS에 연결하고 언로딩된 파일이 스테이징되는 개인 S3 버킷에 액세스하기 위한 보안 자격 증명을 지정합니다. 자세한 내용은 Amazon S3에 대한 보안 액세스 구성하기 섹션을 참조하십시오.

지정하는 자격 증명은 버킷에 대한 Snowflake 액세스 허가를 AWS IAM(Identity & Access Management) 사용자 또는 역할과 연결했는지 여부에 따라 다릅니다.

  • IAM 사용자: 임시 IAM 자격 증명이 필요합니다. 임시(일명 《범위 지정》) 자격 증명은 AWS STS(Security Token Service)에 의해 생성되며 다음 세 가지 구성 요소로 이루어집니다.

    • AWS_KEY_ID

    • AWS_SECRET_KEY

    • AWS_TOKEN

    개인 버킷에 액세스하려면 세 가지가 모두 필요합니다. 지정된 기간이 지나면 임시 자격 증명이 만료되어 더 이상 사용할 수 없습니다. 그런 다음 유효한 임시 자격 증명으로 구성된 새 세트를 생성해야 합니다.

    중요

    COPY 명령에는 자격 증명과 같은 복잡한 구문과 중요한 정보가 포함됩니다. 또한, 이런 명령은 자주 실행되고 스크립트나 워크시트에 종종 저장되므로, 중요한 정보가 실수로 노출될 수 있습니다. COPY 명령을 사용하면 영구적인(일명 《장기》) 자격 증명을 사용할 수도 있지만, 보안상의 이유로 COPY 명령에 영구적인 자격 증명을 사용하지 마십시오. 대신에 임시 자격 증명을 사용하십시오.

    영구적인 자격 증명을 사용해야 하는 경우, 외부 스테이지 를 사용하여 자격 증명을 한 번 입력하고 안전하게 저장해 노출 가능성을 최소화하십시오.

  • IAM 역할: 보안 자격 증명과 액세스 키를 생략하고, 그 대신 AWS_ROLE 을 사용하여 역할을 식별하고 AWS 역할 ARN(Amazon Resource Name)을 지정합니다.

    중요

    AWS IAM을 사용하여 개인 S3 버킷에 액세스하여 데이터를 로딩하거나 언로딩하는 기능은 이제 사용되지 않습니다(즉, 향후 릴리스(TBD)에서는 지원을 제거할 예정임). 그래서 대신에 이 기능을 사용하여 저장소 통합 오브젝트를 참조하는 기존의 S3 스테이지를 모두 수정하는 것이 좋습니다. 자세한 지침은 옵션 1: Amazon S3에 액세스하기 위한 Snowflake 저장소 통합 구성하기 섹션을 참조하십시오.

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 값을 허용하는 서버 측 암호화입니다.

암호화 유형에 대한 자세한 내용은 클라이언트 측 암호화 또는 서버 측 암호화 에 대한 AWS 설명서를 참조하십시오.

  • NONE: 암호화가 없습니다.

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 = ...

사용되는 암호화 유형을 지정합니다. 가능한 값은 다음과 같습니다.

KMS_KEY_ID = 'string' (GCS_SSE_KMS 암호화에만 적용)

버킷으로 언로딩된 파일을 암호화하는 데 사용되는 Cloud 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비트 키여야 합니다.

선택적 매개 변수

PARTITION BY expr

언로딩된 테이블 행을 별개의 파일로 분할하는 데 사용되는 식을 지정합니다. 문자열로 계산되는 모든 SQL 식을 지원합니다.

언로딩 작업은 분할 식에 따라 테이블 행을 분할하고 웨어하우스의 컴퓨팅 리소스 사이에 분산된 데이터의 양과 병렬 작업의 수에 따라 만들 파일의 개수를 결정합니다.

파일 이름에는 data_ 가 접두사로 붙고 파티션 열 값이 포함됩니다. 각 파티션의 개별 파일 이름은 범용 고유 식별자(UUID)로 식별됩니다. UUID는 데이터 파일 언로딩에 사용되는 COPY 문의 쿼리 ID입니다.

조심

COPY INTO <위치> 문은 파티션 열 값을 언로딩된 파일 이름에 씁니다. 잠재적으로 중요한 문자열 또는 정수 값보다는 반드시 날짜나 타임스탬프와 같은 일반적인 데이터 타입으로 데이터를 분할하는 것이 좋습니다.

파일 URLs은 고객이 지원 사례를 생성할 때 문제를 디버깅하는 데 도움이 되도록 Snowflake가 유지 관리하는 내부 로그에 포함됩니다. 따라서 PARTITION BY 식에서 참조되는 열의 데이터도 내부 로그에 간접적으로 저장됩니다. 이러한 로그는 배포 리전 외부에서 처리될 수 있습니다. 따라서 가장 좋은 방법은 날짜, 타임스탬프, 부울 데이터 타입만 PARTITION BY 식에 포함하는 것입니다.

계정에 대한 COPY INTO <위치> 문에서 PARTITION BY 매개 변수를 비활성화하려면 Snowflake 지원 에 문의하십시오.

Snowflake는 데이터 언로딩 작업을 추가로 제한하는 매개 변수 세트를 제공합니다.

  • PREVENT_UNLOAD_TO_INLINE_URL 은 외부 클라우드 저장소 위치에 대한 애드혹 데이터 언로딩 작업을 방지합니다(즉, 문에서 직접 클라우드 저장소 URL과 액세스 설정을 지정하는 COPY INTO <위치> 문).

  • PREVENT_UNLOAD_TO_INTERNAL_STAGES 는 사용자 스테이지, 테이블 스테이지 또는 명명된 내부 스테이지를 포함한 모든 내부 스테이지에 대한 데이터 언로딩 작업을 방지합니다.

예는 이 항목에 있는 언로딩된 행을 Parquet 파일로 분할 섹션을 참조하십시오.

참고

  • 다음 복사 옵션 값은 PARTITION BY와 함께 지원되지는 않습니다.

    • OVERWRITE = TRUE

    • SINGLE = TRUE

    • INCLUDE_QUERY_ID = FALSE

  • PARTITION BY와 함께 SQL 문에 ORDER BY 절을 포함한다고 해서, 언로딩된 파일에서 지정된 순서가 유지되는 것은 아닙니다.

  • PARTITION BY 식이 NULL로 계산되는 경우 출력 파일 이름의 파티션 경로는 _NULL_ 입니다(예: mystage/_NULL_/data_01234567-0123-1234-0000-000000001234_01_0_0.snappy.parquet).

  • PARQUET 형식의 파일로 언로딩할 때:

    • 병렬 실행 스레드로 언로딩된 작은 데이터 파일 은 MAX_FILE_SIZE 복사 옵션 값과 가능한 한 가깝게 일치하는 단일 파일로 자동으로 병합됩니다.

    • 모든 행 그룹의 크기는 128MB입니다. 행 그룹은 데이터를 행으로 논리적 가로 방향 분할한 것입니다. 행 그룹에 대해 보장되는 물리적 구조가 없습니다. 행 그룹은 데이터 세트의 각 열에 대한 열 청크로 구성됩니다.

    • 언로딩 작업은 MAX_FILE_SIZE 복사 옵션 설정에 가능한 한 가까운 크기의 파일을 생성하려고 시도합니다. 이 복사 옵션의 기본값은 16MB입니다. 이 동작은 데이터를 Parquet 파일로 언로딩할 때만 적용됩니다.

    • (TO_ARRAY 함수를 사용해) 열 값이 배열로 캐스팅되더라도 VARIANT 열은 LIST 값이 아니라 간단한 JSON 문자열로 변환됩니다.

  • 언로딩된 데이터 파일에서 파티션 식의 열을 생략하는 옵션은 없습니다.

FILE_FORMAT = ( FORMAT_NAME = 'file_format_name' ) 또는 . FILE_FORMAT = ( TYPE = CSV | JSON | PARQUET [ ... ] )

언로딩된 데이터가 포함된 데이터 파일의 형식을 지정합니다.

FORMAT_NAME = 'file_format_name'

테이블에서 데이터를 언로딩하는 데 사용할 기존의 명명된 파일 형식을 지정합니다. 명명된 파일 형식에 따라 데이터 파일의 형식 유형(CSV, JSON, PARQUET)뿐 아니라, 기타 형식 옵션도 모두 결정됩니다. 자세한 내용은 CREATE FILE FORMAT 섹션을 참조하십시오.

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

테이블에서 언로딩되는 파일의 형식을 지정합니다.

형식 유형을 지정하면 형식별 옵션을 추가로 지정할 수 있습니다. 자세한 내용은 이 항목에 있는 형식 유형 옵션 섹션을 참조하십시오.

참고

  • JSON은 VARIANT 형식의 열(즉, JSON 데이터가 포함된 열)에서 데이터를 언로딩하는 데만 사용할 수 있습니다.

  • 현재, VARIANT 열에서 중첩된 데이터를 Parquet 형식으로 성공적으로 언로딩할 수 없습니다.

copyOptions

언로딩된 데이터에 대해 하나 이상의 복사 옵션을 지정합니다. 자세한 내용은 이 항목에 있는 복사 옵션 섹션을 참조하십시오.

VALIDATION_MODE = RETURN_ROWS

지정된 클라우드 저장소 위치로 결과를 언로딩하는 대신 COPY 명령으로 SQL 문의 쿼리 결과를 반환하도록 지시하는 문자열(상수). 유일하게 지원되는 유효성 검사 옵션은 RETURN_ROWS 입니다. 이 옵션은 쿼리에서 생성된 모든 행을 반환합니다.

쿼리의 유효성을 검사했으면 VALIDATION_MODE 를 제거하여 언로딩 작업을 수행할 수 있습니다.

HEADER = TRUE | FALSE

출력 파일에 테이블 열 머리글을 포함할지 여부를 지정합니다.

  • 출력 파일에 테이블 열 머리글을 포함하려면 이 옵션을 TRUE 로 설정하십시오.

    COPY 작업이 데이터를 여러 파일로 언로딩하는 경우 열 머리글은 모든 파일에 포함됩니다.

    Parquet 형식의 데이터를 언로딩할 때 테이블 열 이름은 출력 파일에 보존됩니다.

  • 다음 동작을 지정하려면 이 옵션을 FALSE 로 설정하십시오.

    CSV

    출력 파일에 테이블 열 머리글을 포함하지 않습니다.

    Parquet

    출력 파일에 일반적인 열 머리글(예: col1, col2 등)을 포함합니다.

기본값: FALSE

형식 유형 옵션(formatTypeOptions)

지정된 파일 형식 유형(FILE_FORMAT = ( TYPE = ... ))에 따라 다음 형식별 옵션(공백, 쉼표 또는 줄 바꿈으로 구분) 중 하나 이상을 포함할 수 있습니다.

TYPE = CSV

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

지정된 압축 알고리즘을 사용하여 언로딩된 데이터 파일을 압축하도록 지정하는 문자열(상수)입니다.

지원되는 값

참고

AUTO

언로딩된 파일은 기본값인 gzip을 사용하여 자동으로 압축됩니다.

GZIP

BZ2

BROTLI

Brotli 압축 파일을 로딩할 때 지정해야 합니다.

ZSTD

Zstandard v0.8 이상이 지원됩니다.

DEFLATE

언로딩된 파일이 Deflate(zlib 헤더 RFC1950 포함)를 사용하여 압축됩니다.

RAW_DEFLATE

언로딩된 파일이 Raw Deflate(헤더 RFC1951 제외)를 사용하여 압축됩니다.

NONE

언로딩된 파일이 압축되지 않습니다.

기본값: AUTO

RECORD_DELIMITER = 'character' | NONE

언로딩된 파일에서 레코드를 구분하는 하나 이상의 싱글바이트 또는 멀티바이트 문자입니다. 일반적인 이스케이프 시퀀스 또는 다음 싱글바이트 또는 멀티바이트 문자를 허용합니다.

싱글바이트 문자

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 = 'character' | NONE

언로딩된 파일에서 필드를 구분하는 하나 이상의 싱글바이트 또는 멀티바이트 문자입니다. 일반적인 이스케이프 시퀀스 또는 다음 싱글바이트 또는 멀티바이트 문자를 허용합니다.

싱글바이트 문자

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 의 값도 허용합니다.

기본값: 쉼표(,)

FILE_EXTENSION = 'string' | NONE

스테이지로 언로딩된 파일의 확장명을 지정하는 문자열입니다. 모든 확장명을 허용합니다. 원하는 소프트웨어나 서비스에서 읽을 수 있는 유효한 파일 확장명은 사용자가 지정해야 합니다.

참고

SINGLE 복사 옵션이 TRUE 인 경우 COPY 명령을 실행하면 기본적으로 파일 확장명이 없는 파일이 언로딩됩니다. 파일 확장명을 지정하려면 internal_location 또는 external_location 경로에 파일 이름과 확장명을 입력하십시오. 예:

copy into @stage/data.csv ...

기본값: null, 즉 파일 확장명이 형식 유형(예: .csv[compression])으로 결정된다는 의미로, 여기서 compressionCOMPRESSION 이 설정된 경우 압축 방법에 따라 추가되는 확장명입니다.

DATE_FORMAT = 'string' | AUTO

언로딩된 데이터 파일의 날짜 값 형식을 정의하는 문자열입니다. 값이 지정되지 않거나 AUTO 로 설정된 경우 DATE_OUTPUT_FORMAT 매개 변수의 값이 사용됩니다.

기본값: AUTO

TIME_FORMAT = 'string' | AUTO

언로딩된 데이터 파일의 시간 값 형식을 정의하는 문자열입니다. 값이 지정되지 않거나 AUTO 로 설정된 경우 TIME_OUTPUT_FORMAT 매개 변수의 값이 사용됩니다.

기본값: AUTO

TIMESTAMP_FORMAT = 'string' | AUTO

언로딩된 데이터 파일의 타임스탬프 값 형식을 정의하는 문자열입니다. 값이 지정되지 않거나 AUTO 로 설정된 경우 TIMESTAMP_OUTPUT_FORMAT 매개 변수의 값이 사용됩니다.

기본값: AUTO

BINARY_FORMAT = HEX | BASE64 | UTF8

이진 출력의 인코딩 형식을 정의하는 문자열(상수)입니다. 이 옵션은 테이블의 이진 열에서 데이터를 언로딩할 때 사용할 수 있습니다.

기본값: HEX

ESCAPE = 'character' | NONE
용도

데이터 로딩 및 언로딩

정의

괄호로 묶이거나 묶이지 않은 필드 값에 대한 이스케이프 문자로 사용되는 싱글바이트 문자열입니다. 이스케이프 문자는 문자 시퀀스의 후속 문자에 대한 대체 해석을 호출합니다. ESCAPE 문자를 사용하여 데이터에 있는 FIELD_OPTIONALLY_ENCLOSED_BY 문자의 인스턴스를 리터럴로 해석할 수 있습니다. 이스케이프 문자는 데이터에서 자신의 인스턴스를 이스케이프하는 데 사용할 수도 있습니다.

일반적인 이스케이프 시퀀스, 8진수 값 또는 16진수 값을 허용합니다.

FIELD_OPTIONALLY_ENCLOSED_BY 를 설정하여 필드를 묶는 데 사용되는 문자를 지정합니다.

이 옵션이 설정되면 ESCAPE_UNENCLOSED_FIELD 에 대해 설정된 이스케이프 문자를 재정의합니다.

기본값

NONE

ESCAPE_UNENCLOSED_FIELD = 'character' | NONE
용도

데이터 로딩 및 언로딩

정의

괄호로 묶이지 않은 필드 값에 대해서만 이스케이프 문자로 사용되는 싱글바이트 문자열입니다. 이스케이프 문자는 문자 시퀀스의 후속 문자에 대한 대체 해석을 호출합니다. ESCAPE 문자를 사용하여 데이터에 있는 FIELD_DELIMITER 또는 RECORD_DELIMITER 문자의 인스턴스를 리터럴로 해석할 수 있습니다. 이스케이프 문자는 데이터에서 자신의 인스턴스를 이스케이프하는 데 사용할 수도 있습니다.

일반적인 이스케이프 시퀀스, 8진수 값 또는 16진수 값을 허용합니다.

ESCAPE 가 설정된 경우 해당 파일 형식 옵션에 대해 설정된 이스케이프 문자가 이 옵션을 재정의합니다.

기본값

백슬래시(\\)

FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE

문자열을 묶는 데 사용되는 문자입니다. 값은 NONE, 작은따옴표 문자(') 또는 큰따옴표 문자(")일 수 있습니다. 작은따옴표 문자를 사용하려면 8진수 또는 16진수 표현(0x27) 또는 이중 작은따옴표로 묶인 이스케이프('')를 사용하십시오.

필드에 이 문자가 포함된 경우 같은 문자를 사용하여 이스케이프합니다. 예를 들어 값이 큰따옴표 문자이고 필드에 문자열 A "B" C 가 포함된 경우 다음과 같이 큰따옴표를 이스케이프합니다.

A ""B"" C

기본값: NONE

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

SQL NULL에서 변환하는 데 사용되는 문자열입니다. Snowflake는 SQL NULL 값을 목록의 첫 번째 값으로 변환합니다.

기본값: \\N (즉, NULL로서 ESCAPE_UNENCLOSED_FIELD=\\ 가정)

EMPTY_FIELD_AS_NULL = TRUE | FALSE

FIELD_OPTIONALLY_ENCLOSED_BY 와 함께 사용됩니다. FIELD_OPTIONALLY_ENCLOSED_BY = NONE 일 때, EMPTY_FIELD_AS_NULL = FALSE 를 설정하면 필드 값을 묶는 따옴표 없이 빈 문자열 값으로 테이블의 빈 문자열을 언로딩하도록 지정됩니다.

TRUE 로 설정하면 FIELD_OPTIONALLY_ENCLOSED_BY 가 문자열을 묶을 문자를 지정해야 합니다.

기본값: TRUE

TYPE = JSON

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

문자열(상수)입니다. 지정된 압축 알고리즘을 사용하여 데이터 파일을 압축합니다.

지원되는 값

참고

AUTO

언로딩된 파일은 기본값인 gzip을 사용하여 자동으로 압축됩니다.

GZIP

BZ2

BROTLI

ZSTD

DEFLATE

언로딩된 파일이 Deflate(zlib 헤더 RFC1950 포함)를 사용하여 압축됩니다.

RAW_DEFLATE

언로딩된 파일이 Raw Deflate(헤더 RFC1951 제외)를 사용하여 압축됩니다.

NONE

언로딩된 파일이 압축되지 않습니다.

기본값: AUTO

FILE_EXTENSION = 'string' | NONE

스테이지로 언로딩된 파일의 확장명을 지정하는 문자열입니다. 모든 확장명을 허용합니다. 원하는 소프트웨어나 서비스에서 읽을 수 있는 유효한 파일 확장명은 사용자가 지정해야 합니다.

기본값: null, 즉 파일 확장명이 형식 유형(예: .csv[compression])으로 결정된다는 의미로, 여기서 compressionCOMPRESSION 이 설정된 경우 압축 방법에 따라 추가되는 확장명입니다.

TYPE = PARQUET

COMPRESSION = AUTO | LZO | SNAPPY | NONE

문자열(상수)입니다. 지정된 압축 알고리즘을 사용하여 데이터 파일을 압축합니다.

지원되는 값

참고

AUTO

파일은 기본 압축 알고리즘인 Snappy를 사용하여 압축됩니다.

LZO

파일은 기본적으로 Snappy 알고리즘을 사용하여 압축됩니다. 대신 Lempel-Ziv-Oberhumer(LZO) 압축을 적용하는 경우 이 값을 지정합니다.

SNAPPY

파일은 기본적으로 Snappy 알고리즘을 사용하여 압축됩니다. 이 값을 선택적으로 지정할 수 있습니다.

NONE

언로딩된 파일이 압축되지 않도록 지정합니다.

기본값: AUTO

SNAPPY_COMPRESSION = TRUE | FALSE

언로딩된 파일이 SNAPPY 알고리즘을 사용하여 압축되는지 여부를 지정하는 부울입니다.

참고

사용되지 않음. COMPRESSION = SNAPPY 를 대신 사용하십시오.

기본값: TRUE

복사 옵션(copyOptions)

다음 복사 옵션(공백, 쉼표 또는 줄 바꿈으로 구분) 중 하나 이상을 지정할 수 있습니다.

OVERWRITE = TRUE | FALSE
정의

COPY 명령 실행 시 파일이 저장된 위치에서 일치하는 이름(있는 경우)으로 기존 파일을 덮어쓸지 여부를 지정하는 부울입니다. 이 옵션은 COPY 명령이 언로딩하는 파일의 이름과 일치하지 않는 기존 파일을 제거하지 않습니다.

많은 경우, 이 옵션을 활성화하면 똑같은 COPY INTO <위치> 문이 여러 번 실행될 때 대상 스테이지에서 데이터 중복을 방지하는 데 도움이 됩니다. 하지만 언로딩 작업으로 여러 파일을 스테이지에 쓸 때, Snowflake는 각 파일 이름이 병렬 실행 스레드(예: data_0_1_0) 전체에서 고유하도록 보장하는 접미사를 추가합니다. 병렬 실행 스레드의 수는 언로딩 작업마다 다를 수 있습니다. 언로딩 작업으로 작성한 파일의 파일 이름이 이전 작업으로 작성한 파일과 같지 않은 경우 이 복사 옵션이 포함된 SQL 문이 기존 파일을 대체할 수 없으므로 파일이 중복됩니다.

또한, 드물긴 하지만 시스템 또는 네트워크 오류가 발생하는 경우 언로딩 작업이 다시 시도됩니다. 그런 상황에서는 언로딩 작업이 첫 번째 시도에서 이전에 작성한 파일부터 먼저 제거하지 않고 스테이지에 추가 파일을 작성합니다.

대상 스테이지에서 데이터 중복을 방지하려면 OVERWRITE = TRUE 대신 INCLUDE_QUERY_ID = TRUE 복사 옵션을 설정하고 각 언로딩 작업 사이에 대상 스테이지 및 경로(또는 각 언로딩 작업에 대해 다른 경로 사용)의 모든 데이터 파일을 제거하는 것이 좋습니다.

기본값

FALSE

SINGLE = TRUE | FALSE
정의

단일 파일 또는 여러 파일을 생성할지 여부를 지정하는 부울입니다. FALSE 인 경우 파일 이름 접두사를 path 에 포함해야 합니다.

중요

SINGLE = TRUE 인 경우 COPY 는 FILE_EXTENSION 파일 형식 옵션을 무시하고 단순히 data 로 명명된 파일을 출력합니다. 파일 확장명을 지정하려면 내부 또는 외부 위치 path 에 파일 이름과 확장명을 입력하십시오. 예:

COPY INTO @mystage/data.csv ...

또한, COMPRESSION 파일 형식 옵션이 지원되는 압축 알고리즘(예: GZIP) 중 하나로 명시적으로 설정된 경우에는 알맞은 도구를 사용하여 파일의 압축을 풀 수 있도록 지정된 내부 또는 외부 위치 path 는 해당 파일 확장명을 가진 파일 이름으로 끝나야 합니다(예: gz). 예:

COPY INTO @mystage/data.gz ...

COPY INTO @mystage/data.csv.gz ...
기본값

FALSE

MAX_FILE_SIZE = num
정의

스레드마다 병렬로 생성할 각 파일의 크기 상한(바이트)을 지정하는 숫자(> 0)입니다. 실제 파일 크기와 언로딩된 파일 수는 병렬 처리에 사용할 수 있는 총 데이터양과 노드 수에 따라 결정됩니다.

Snowflake는 병렬 실행을 활용하여 성능을 최적화합니다. 스레드 수는 수정할 수 없습니다.

최대 5GB(Amazon S3, Google Cloud Storage 또는 Microsoft Azure 스테이지)

참고

COPY 명령은 한 번에 한 개의 테이블 행 세트를 언로딩합니다. 매우 작은 MAX_FILE_SIZE 값을 설정하면 행 세트의 데이터양이 지정된 크기를 초과할 수 있습니다.

기본값

16777216 (16MB)

INCLUDE_QUERY_ID = TRUE | FALSE
정의

언로딩된 데이터 파일의 파일 이름에 범용 고유 식별자(UUID)를 포함하여 언로딩된 파일을 고유하게 식별할지 여부를 지정하는 부울입니다. 이 옵션은 동시 COPY 문이 언로딩된 파일을 실수로 덮어쓰지 않도록 하는 데 도움이 됩니다.

TRUE 인 경우 언로딩된 파일의 이름에 UUID가 추가됩니다. UUID는 데이터 파일 언로딩에 사용되는 COPY 문의 쿼리 ID입니다. UUID는 파일 이름 <경로>/data_<uuid>_<이름>.<확장명> 의 세그먼트입니다.

FALSE 인 경우에는 UUID가 언로딩된 데이터 파일에 추가되지 않습니다.

참고

  • INCLUDE_QUERY_ID = TRUE 는 (COPY INTO <위치> 문에서 PARTITION BY expr 를 설정하여) 언로드된 테이블 행을 별도의 파일로 분할할 때의 기본 복사 옵션 값입니다. 이 값은 FALSE로 변경할 수 없습니다.

  • 다음 복사 옵션 중 어느 하나가 설정되어 있으면 INCLUDE_QUERY_ID = TRUE 가 지원되지 않습니다.

    • SINGLE = TRUE

    • OVERWRITE = TRUE

  • 드물긴 하지만 시스템 또는 네트워크 오류가 발생하는 경우 언로딩 작업이 다시 시도됩니다. 그런 상황에서, 언로딩 작업은 현재 쿼리 ID의 UUID로 스테이지에 작성된 모든 파일을 제거한 다음, 데이터를 다시 언로딩하려고 시도합니다. 스테이지에 작성된 모든 새 파일에는 다시 시도한 쿼리 ID가 UUID로 있습니다.

기본값

FALSE

DETAILED_OUTPUT = TRUE | FALSE
정의

명령 출력이 언로딩 작업을 설명해야 하는지, 또는 작업의 결과로 언로딩된 개별 파일을 설명해야 하는지 여부를 지정하는 부울입니다.

  • TRUE 인 경우 명령 출력에는 지정된 스테이지로 언로딩된 각 파일에 대한 행이 포함됩니다. 열에는 각 파일의 경로와 이름, 파일 크기, 파일로 언로딩된 행 수가 표시됩니다.

  • FALSE 인 경우 명령 출력은 전체 언로딩 작업을 설명하는 단일 행으로 구성됩니다. 열은 압축 전후에(해당되는 경우) 테이블에서 언로딩된 총데이터양과 언로딩된 행 총수를 표시합니다.

기본값

FALSE

사용법 노트

  • STORAGE_INTEGRATION 또는 CREDENTIALS 는 개인 저장소 위치(Amazon S3, Google Cloud Storage 또는 Microsoft Azure)로 직접 언로딩하는 경우에만 적용됩니다. 공용 버킷으로 언로딩하는 경우 보안 액세스가 필요하지 않으며, 명명된 외부 스테이지로 언로딩하는 경우 스테이지에서 버킷에 액세스하는 데 필요한 모든 자격 증명 정보를 제공합니다.

  • 현재 네임스페이스의 파일 형식을 참조하는 경우 형식 식별자를 둘러싸는 작은따옴표를 생략할 수 있습니다.

  • 테이블의 VARIANT 열에서 데이터를 언로딩할 때만 TYPE 에 대해 JSON 을 지정할 수 있습니다.

  • CSV, JSON 또는 PARQUET 형식의 파일로 언로딩할 때:

    기본적으로, VARIANT 열은 출력 파일에서 간단한 JSON 문자열로 변환됩니다.

    • 데이터를 Parquet LIST 값으로 언로드하려면 명시적으로 열 값을 배열로 캐스팅하십시오(TO_ARRAY 함수 사용).

    • VARIANT 열에 XML이 포함된 경우 FROM ... 쿼리에서 열 값을 XML로 명시적으로 캐스팅하는 것이 좋습니다. TO_XML 함수를 사용하여 값을 캐스팅하면 JSON 문자열 대신 XML 형식 문자열이 언로딩됩니다.

  • PARQUET 형식의 파일로 언로딩할 때:

    TIMESTAMP_TZ 또는 TIMESTAMP_LTZ 데이터를 언로딩하면 오류가 발생합니다.

  • 원본 테이블의 행 수가 0개인 경우에는 COPY 작업이 데이터 파일을 언로딩하지 않습니다.

  • 이 SQL 명령은 비어 있지 않은 저장소 위치로 언로딩할 때 경고를 반환하지 않습니다. 데이터 파이프라인에서 저장소 위치의 파일을 사용할 때 예기치 않은 동작을 방지하려면 빈 저장소 위치에만 쓰는 것이 좋습니다.

  • 실패한 언로딩 작업으로 인해 데이터 파일이 계속 언로딩될 수 있습니다(예: 문이 시간 제한을 초과하여 취소된 경우). 또한, 다른 리전의 클라우드 저장소에 대한 언로딩 작업에 실패하면 데이터 전송 비용이 발생합니다.

  • 열에 열 수준 보안 마스킹 정책이 설정된 경우 마스킹 정책이 데이터에 적용되어 열에서 마스킹된 데이터가 권한 없는 사용자에게 보이게 됩니다.

테이블에서 테이블 스테이지의 파일로 데이터 언로딩

폴더/파일 이름 접두사(result/data_), 명명된 파일 형식(myformat), gzip 압축을 사용하여 orderstiny 테이블에서 테이블의 스테이지로 데이터를 언로딩:

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

쿼리에서 명명된 내부 스테이지의 파일로 데이터 언로딩

폴더/파일 이름 접두사(result/data_), 명명된 파일 형식(myformat), gzip 압축을 사용하여 명명된 내부 스테이지(my_stage)로 쿼리 결과 언로딩:

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

위의 예는 언로딩된 데이터가 있는 파일이 orderstiny 에 대한 테이블 위치가 아니라 my_stage 에 대한 스테이지 위치에 저장된다는 점을 제외하면, 첫 번째 예와 기능적으로 똑같습니다.

테이블에서 외부 위치의 파일로 직접 데이터 언로딩

명명된 my_csv_format 파일 형식을 사용하여 테이블의 모든 데이터를 저장소 위치로 언로딩:

Amazon S3

이름이 myint 인 참조된 저장소 통합을 사용하여 참조된 S3 버킷에 액세스:

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

제공된 자격 증명을 사용하여 참조된 S3 버킷에 액세스:

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

Google Cloud Storage

이름이 myint 인 참조된 저장소 통합을 사용하여 참조된 GCS 버킷에 액세스:

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

Microsoft Azure

이름이 myint 인 참조된 저장소 통합을 사용하여 참조된 컨테이너에 액세스:

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

제공된 자격 증명을 사용하여 참조된 컨테이너에 액세스:

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

언로딩된 행을 Parquet 파일로 분할

다음은 언로딩된 행을 날짜 열과 시간 열의 두 열에 있는 값을 기준으로 Parquet 파일로 분할하는 예입니다. 이 예에서는 다음과 같이 언로딩된 각 파일의 최대 크기를 지정합니다.

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

SELECT * FROM t1;

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

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

LIST @%t1;

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

언로딩된 파일에 NULL/빈 필드 데이터 보존

언로딩된 파일에 SQL NULL 필드와 빈 필드 보존:

-- View the table column values
SELECT * FROM HOME_SALES;

+------------+-------+-------+-------------+--------+------------+
| CITY       | STATE | ZIP   | TYPE        | PRICE  | SALE_DATE  |
|------------+-------+-------+-------------+--------+------------|
| Lexington  | MA    | 95815 | Residential | 268880 | 2017-03-28 |
| Belmont    | MA    | 95815 | Residential |        | 2017-02-21 |
| Winchester | MA    | NULL  | Residential |        | 2017-01-31 |
+------------+-------+-------+-------------+--------+------------+

-- Unload the table data into the current user's personal stage. The file format options retain both the NULL value and the empty values in the output file
COPY INTO @~ FROM HOME_SALES
  FILE_FORMAT = (TYPE = csv NULL_IF = ('NULL', 'null') EMPTY_FIELD_AS_NULL = false);

-- Contents of the output file
Lexington,MA,95815,Residential,268880,2017-03-28
Belmont,MA,95815,Residential,,2017-02-21
Winchester,MA,NULL,Residential,,2017-01-31

단일 파일로 데이터 언로딩

SINGLE 복사 옵션을 사용하여 모든 행을 단일 데이터 파일로 언로딩:

copy into @~ from HOME_SALES
single = true;

언로딩된 파일 이름에 UUID 포함

INCLUDE_QUERY_ID 복사 옵션을 TRUE로 설정하여 언로딩된 파일의 이름에 UUID 포함:

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

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

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

(쿼리에서) 언로딩할 데이터 유효성 검사

유효성 검사 모드에서 COPY를 실행하여 쿼리 결과를 반환하고 COPY가 일반 모드에서 실행되는 경우 orderstiny 테이블에서 언로딩될 데이터 보기:

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

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