CREATE FILE FORMAT

CREATE FILE FORMAT

Snowflake 테이블로 접근하거나 로드할 일련의 스테이징된 데이터를 설명하는 명명된 파일 포맷(file format)을 만드는 명령이에요.

출처: 문서

본문

이 명령은 다음 변형(variant)을 지원해요:

  • CREATE OR ALTER FILE FORMAT: 파일 포맷이 없으면 만들고, 있으면 수정합니다.

구문 (Syntax)

CREATE [ OR REPLACE ] [ { TEMP | TEMPORARY | VOLATILE } ] FILE FORMAT [ IF NOT EXISTS ] <name>
  [ TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] ]
  [ COMMENT = '<string_literal>' ]

여기서:

formatTypeOptions ::=
-- If TYPE = CSV
     COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     RECORD_DELIMITER = '<string>' | NONE
     FIELD_DELIMITER = '<string>' | NONE
     MULTI_LINE = TRUE | FALSE
     FILE_EXTENSION = '<string>'
     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 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>' ... ] )
     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 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If TYPE = ORC
     TRIM_SPACE = TRUE | FALSE
     REPLACE_INVALID_CHARACTERS = TRUE | FALSE
     NULL_IF = ( '<string>' [ , '<string>' ... ] )
-- If TYPE = PARQUET
     COMPRESSION = AUTO | LZO | SNAPPY | NONE
     SNAPPY_COMPRESSION = TRUE | FALSE
     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 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

CREATE OR ALTER FILE FORMAT 구문

CREATE OR ALTER [ { TEMP | TEMPORARY | VOLATILE } ] FILE FORMAT <name>
  [ TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML } [ formatTypeOptions ] ]
  [ COMMENT = '<string_literal>' ]

지원되는 수정에는 formatTypeOptions와 COMMENT 속성에 대한 변경이 포함돼요. TYPE 속성은 변경할 수 없어요.

필수 매개변수

  • <name>: 파일 포맷의 식별자예요. 생성되는 스키마 내에서 고유해야 해요. 기본 문자로 시작해야 하며, 큰따옴표로 감싸지 않는 한 공백이나 특수 문자를 포함할 수 없어요.

선택 매개변수

  • { TEMP | TEMPORARY | VOLATILE }: 파일 포맷이 만든 세션 기간 동안만 유지되도록 지정해요. 세션이 끝나면 드롭돼요. 기본값: 값 없음 (영구).

  • TYPE = CSV | JSON | AVRO | ORC | PARQUET | XML [ ... ]: 입력 파일(로드) 또는 출력 파일(언로드)의 형식을 지정해요. 형식 유형에 따라 추가 형식별 옵션을 지정할 수 있어요.

    • CSV(로드/언로드): 특정 문자를 사용하는 평문 텍스트 파일. 이름은 CSV지만 필드 구분자로 유효한 어떤 문자든 사용할 수 있어요.
    • JSON(로드/언로드): 하나 이상의 JSON 문서를 포함하는 평문 텍스트 파일. 반정형(semi-structured) 파일 형식. 로드 시 NDJSON 또는 쉼표로 구분된 JSON 지원, 언로드 시 NDJSON만 출력.
    • AVRO(로드 전용): AVRO 형식의 바이너리 파일.
    • ORC(로드 전용): ORC 형식의 바이너리 파일.
    • PARQUET(로드/언로드): PARQUET 형식의 바이너리 파일.
    • XML(로드 전용): XML 요소를 포함하는 평문 텍스트 파일.

    기본값: CSV.

  • COMMENT = 'string_literal': 파일 포맷에 대한 주석을 지정해요.

형식 유형 옵션 (formatTypeOptions)

TYPE = CSV

  • COMPRESSION = AUTO | GZIP | BZ2 | BROTLI | ZSTD | DEFLATE | RAW_DEFLATE | NONE: 로드 시 데이터 파일의 현재 압축 알고리즘을 지정해요. 언로드 시 지정된 알고리즘으로 압축해요. AUTO는 자동 감지(언로드 시 기본 gzip). BROTLI는 Brotli 압축 파일에 필수. ZSTD는 Zstandard v0.8 이상 지원. DEFLATE는 zlib 헤더(RFC1950), RAW_DEFLATE는 헤더 없는 원시 Deflate(RFC1951). 기본값: AUTO.
  • RECORD_DELIMITER = 'string' | NONE: 입력/출력 파일에서 레코드를 구분하는 문자를 지정해요. 8진수(\\) 또는 16진수(0x/\x) 값을 허용해요. 구분자는 다른 옵션의 구분자의 부분 문자열일 수 없고, 최대 20자, 유효한 UTF-8 문자여야 해요. 기본값: 개행 문자.
  • FIELD_DELIMITER = 'string' | NONE: 필드를 구분하는 문자를 지정해요. 기본값: 쉼표(,).
  • MULTI_LINE = TRUE | FALSE: 여러 줄 허용 여부를 지정해요. FALSE이면 CSV 필드 안에 레코드 구분자가 있으면 오류로 처리돼요. 기본값: TRUE.
  • FILE_EXTENSION = 'string' | NONE: (언로드 전용) 언로드 파일의 확장자를 지정해요. 기본값: null (.csv[compression]).
  • PARSE_HEADER = TRUE | FALSE: (로드 전용) 첫 번째 행 헤더를 사용해 컬럼 이름을 결정할지 지정해요. INFER_SCHEMA 함수 등에 적용돼요. TRUE이면 첫 행 헤더 사용, FALSE이면 c* 형식. PARSE_HEADER = TRUE일 때 SKIP_HEADER는 지원되지 않아요. 기본값: FALSE.
  • SKIP_HEADER = integer: (로드/외부 테이블) 파일 시작 부분에서 건너뛸 라인 수를 지정해요. 기본값: 0.
  • SKIP_BLANK_LINES = TRUE | FALSE: 빈 줄을 건너뛸지 지정해요. 기본값: FALSE.
  • DATE_FORMAT = 'string' | AUTO: 날짜 값의 형식을 정의해요. 기본값: AUTO.
  • TIME_FORMAT = 'string' | AUTO: 시간 값의 형식을 정의해요. 기본값: AUTO.
  • TIMESTAMP_FORMAT = 'string' | AUTO: 타임스탬프 값의 형식을 정의해요. 기본값: AUTO.
  • BINARY_FORMAT = HEX | BASE64 | UTF8: 이진 입력/출력의 인코딩 형식을 정의해요. 기본값: HEX.
  • ESCAPE = 'character' | NONE: 인클로즈된/인클로즈되지 않은 필드 값의 이스케이프 문자를 지정해요. 기본값: NONE.
  • ESCAPE_UNENCLOSED_FIELD = 'character' | NONE: 인클로즈되지 않은 필드 값 전용 이스케이프 문자를 지정해요. 기본값: 백슬래시(\\).
  • TRIM_SPACE = TRUE | FALSE: 필드에서 공백을 제거할지 지정해요. 기본값: FALSE.
  • FIELD_OPTIONALLY_ENCLOSED_BY = 'character' | NONE: 문자열을 감싸는 문자를 지정해요. NONE, 작은따옴표('), 큰따옴표(")일 수 있어요. 기본값: NONE.
  • NULL_IF = ( 'string1' [ , 'string2' , ... ] ): SQL NULL로 변환할 문자열을 지정해요. 로드 시 이 값들을 NULL로, 언로드 시 NULL을 목록의 첫 번째 값으로 변환해요. 기본값: \N.
  • ERROR_ON_COLUMN_COUNT_MISMATCH = TRUE | FALSE: (로드 전용) 입력 파일의 구분된 컬럼 수가 테이블의 컬럼 수와 일치하지 않을 때 파싱 오류를 생성할지 지정해요. 기본값: TRUE.
  • REPLACE_INVALID_CHARACTERS = TRUE | FALSE: 잘못된 UTF-8 문자를 유니코드 대체 문자(�)로 바꿀지 지정해요. 기본값: FALSE.
  • EMPTY_FIELD_AS_NULL = TRUE | FALSE: 빈 필드에 SQL NULL을 넣을지 지정해요. 기본값: TRUE.
  • SKIP_BYTE_ORDER_MARK = TRUE | FALSE: 데이터 파일에 BOM(byte order mark)이 있으면 건너뛸지 지정해요. 기본값: TRUE.
  • ENCODING = 'string': 소스 데이터의 문자 셋을 지정해요. UTF-8이 기본이며, 다양한 문자 셋(예: EUCKR 한국어, SHIFTJIS 일본어, BIG5 중국어 등)을 지원해요. 기본값: UTF8.

TYPE = JSON

  • COMPRESSION / DATE_FORMAT / TIME_FORMAT / TIMESTAMP_FORMAT / BINARY_FORMAT / TRIM_SPACE / MULTI_LINE / NULL_IF / FILE_EXTENSION: CSV와 유사한 의미로 적용돼요.
  • ENABLE_OCTAL = TRUE | FALSE: 8진수 파싱을 활성화할지 지정해요. 기본값: FALSE.
  • ALLOW_DUPLICATE = TRUE | FALSE: 중복 객체 필드 이름을 허용할지(마지막 것만 보존) 지정해요. 기본값: FALSE.
  • STRIP_OUTER_ARRAY = TRUE | FALSE: JSON 파서가 바깥쪽 대괄호([ ])를 제거하도록 지시해요. 기본값: FALSE.
  • STRIP_NULL_VALUES = TRUE | FALSE: null 값을 포함하는 객체 필드/배열 요소를 제거하도록 지시해요. 기본값: FALSE.
  • REPLACE_INVALID_CHARACTERS = TRUE | FALSE: 잘못된 UTF-8 문자를 대체 문자로 바꿀지 지정해요. 기본값: FALSE.
  • IGNORE_UTF8_ERRORS = TRUE | FALSE: UTF-8 인코딩 오류가 오류 조건을 만드는지 지정해요. REPLACE_INVALID_CHARACTERS의 대체 구문이에요. 기본값: FALSE.
  • SKIP_BYTE_ORDER_MARK = TRUE | FALSE: 기본값 TRUE.

TYPE = AVRO / ORC

  • COMPRESSION(AVRO), TRIM_SPACE, REPLACE_INVALID_CHARACTERS, NULL_IF 옵션을 지원해요. 이 옵션들은 MATCH_BY_COLUMN_NAME 복사 옵션으로 별도 컬럼에 로드할 때 적용돼요.

TYPE = PARQUET

  • COMPRESSION = AUTO | LZO | SNAPPY | NONE: Parquet 파일 컬럼의 압축 알고리즘을 지정해요. 기본값: AUTO.
  • SNAPPY_COMPRESSION = TRUE | FALSE: (언로드 전용, 사용 중단) COMPRESSION = SNAPPY를 사용하세요. 기본값: TRUE.
  • BINARY_AS_TEXT = TRUE | FALSE: 정의된 논리 데이터 타입이 없는 컬럼을 UTF-8 텍스트로 해석할지 지정해요. FALSE는 바이너리 데이터로 해석. 기본값: TRUE.
  • TRIM_SPACE = TRUE | FALSE: 기본값 FALSE.
  • USE_LOGICAL_TYPE = TRUE | FALSE: Parquet 논리 타입을 사용할지 지정해요. TRUE로 설정하면 Parquet 논리 타입을 해석할 수 있어요. 언로드에는 지원되지 않아요.
  • USE_VECTORIZED_SCANNER = TRUE | FALSE: Parquet 로드를 위해 벡터화 스캐너를 사용할지 지정해요. 기본값: FALSE (향후 BCR에서 TRUE로 변경).
    • TRUE이면 BINARY_AS_TEXT는 항상 FALSE, USE_LOGICAL_TYPE은 항상 TRUE로 처리돼요. 벡터화 스캐너는 Parquet 맵 타입, NULL 값, Time/Timestamp 처리를 지원해요.
    • FALSE이면 Parquet 맵을 지원하지 않고 출력에 NULL을 명시적으로 표시하지 않아요.
  • REPLACE_INVALID_CHARACTERS: 기본값 FALSE.
  • NULL_IF: 기본값 \N.

TYPE = XML

  • COMPRESSION, IGNORE_UTF8_ERRORS(기본 FALSE), PRESERVE_SPACE(요소 내용의 앞/뒤 공백 보존 여부, 기본 FALSE), STRIP_OUTER_ELEMENT(바깥 XML 요소 제거, 기본 FALSE), DISABLE_AUTO_CONVERT(숫자/Boolean 자동 변환 비활성화, 기본 FALSE), REPLACE_INVALID_CHARACTERS(기본 FALSE), SKIP_BYTE_ORDER_MARK(기본 TRUE).

접근 제어 요구 사항

권한 객체 참고
CREATE FILE FORMAT 스키마
OWNERSHIP 파일 포맷 기존 파일 포맷에 대해 CREATE OR ALTER FILE FORMAT 문 실행에 필요.

CREATE OR ALTER FILE FORMAT 사용법 참고 사항

ALTER FILE FORMAT 명령의 모든 제한이 적용돼요.

  • TEMP FILE FORMAT을 일반 FILE FORMAT으로 바꾸거나 그 반대로는 변경할 수 없어요.
  • TYPE 속성은 변경할 수 없어요.

사용법 참고 사항

주의: 파일 포맷을 다시 만들면(CREATE OR REPLACE FILE FORMAT) 그 파일 포맷을 참조하는 외부 테이블과의 연결이 끊어져요. 외부 테이블은 이름이 아니라 숨겨진 ID로 파일 포맷에 연결되기 때문이에요. 파일 포맷을 여러 외부 테이블과 연결한 뒤 다시 만들어야 한다면 각 외부 테이블을 다시 만들어야 해요.

  • SQL 문에서 충돌하는 파일 포맷 값은 오류를 만들어요. 같은 옵션을 다른 값으로 여러 번 지정하면 충돌이 발생해요.
  • OR REPLACE와 IF NOT EXISTS 절은 상호 배타적이에요.
  • CREATE OR REPLACE <object> 문은 원자적이에요.

예제 (Examples)

모든 기본 CSV 형식 옵션을 사용하는 my_csv_format이라는 CSV 파일 포맷을 만들어요:

CREATE OR REPLACE FILE FORMAT my_csv_format
  TYPE = CSV
  COMMENT = 'my_file_format';

my_csv_format을 수정해 다음 규칙을 정의하고 주석을 해제해요: 필드는 파이프(|)로 구분, 파일은 건너뛸 단일 헤더 라인 포함, NULL/null 문자열을 NULL로 대체, 빈 문자열을 NULL로 해석, GZIP 압축으로 압축/해제.

CREATE OR ALTER FILE FORMAT my_csv_format
  TYPE = CSV
  FIELD_DELIMITER = '|'
  SKIP_HEADER = 1
  NULL_IF = ('NULL', 'null')
  EMPTY_FIELD_AS_NULL = true
  COMPRESSION = gzip;

모든 기본 JSON 형식 옵션을 사용하는 my_json_format이라는 JSON 파일 포맷을 만들어요:

CREATE OR REPLACE FILE FORMAT my_json_format
  TYPE = JSON;

Parquet 논리 타입을 사용하는 my_parquet_format이라는 PARQUET 파일 포맷을 만들어요:

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

더 알아보기 (Learn more)