CREATE STAGE

CREATE STAGE

CREATE STAGE 명령은 Snowflake 테이블로 파일에서 데이터를 로드하고 테이블에서 파일로 데이터를 언로드하는 데 사용할 새 명명된 내부 또는 외부 스테이지(stage)를 만드는 명령이에요.

출처: CREATE STAGE

본문

Snowflake 테이블로 파일에서 데이터를 로드하고 테이블에서 파일로 데이터를 언로드하는 데 사용할 새 명명된 내부(internal) 또는 외부(external) 스테이지를 만드는 명령입니다.

• 내부 스테이지 — 데이터 파일을 Snowflake 내부에 저장해요. 자세한 내용은 Choosing an internal stage for local files 문서를 참고하세요.
• 외부 스테이지 — Snowflake 외부의 위치에 저장된 데이터 파일을 참조해요. 현재 다음 클라우드 스토리지 서비스가 지원됩니다: Amazon S3(S3 호환 포함), Google Cloud Storage, Microsoft Azure, Microsoft Fabric OneLake. 스토리지 위치는 프라이빗/보호 또는 공용일 수 있어요.

참고 검색(retrieval) 전에 복원이 필요한 아카이브 클라우드 스토리지 클래스에 보관된 데이터에는 접근할 수 없습니다. 이러한 아카이브 스토리지 클래스에는 예를 들어 Amazon S3 Glacier Flexible Retrieval 또는 Glacier Deep Archive 스토리지 클래스, Microsoft Azure Archive Storage가 포함됩니다.

내부 또는 외부 스테이지는 디렉터리 테이블(directory table)을 포함할 수 있어요. 디렉터리 테이블은 클라우드 스토리지의 스테이징된 파일 카탈로그를 저장합니다.

이 명령은 다음 변형도 지원합니다: DROP STAGE, ALTER STAGE, SHOW STAGES, DESCRIBE STAGE, PUT, COPY INTO <table>, COPY INTO <location>, GET

Syntax

내부 스테이지:

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

외부 스테이지:

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

여기서:

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

externalStageParams (for Amazon S3) ::=
  URL = '<protocol>://<bucket>[/<path>/]'
  [ AWS_ACCESS_POINT_ARN = '<string>' ]
  [ { 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' ) ]
  [ USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } ]

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

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' MASTER_KEY = '<string>'
                   | TYPE = 'NONE' ) ]
  [ USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } ]

externalStageParams (for Microsoft Fabric OneLake) ::=
  URL = 'azure://onelake.blob.fabric.microsoft.com/<workspace_id>/<item_id>/Files[/<path>/]'
  [ { STORAGE_INTEGRATION = <integration_name> } | { CREDENTIALS = ( [ AZURE_SAS_TOKEN = '<string>' ] ) } ]
  [ ENCRYPTION = (   TYPE = 'AZURE_CSE' MASTER_KEY = '<string>'
                   | TYPE = 'NONE' ) ]

externalStageParams (for Amazon S3-compatible Storage) ::=
  URL = 's3compat://{bucket}[/{path}/]'
  ENDPOINT = '<s3_api_compatible_endpoint>'
  [ { CREDENTIALS = ( AWS_KEY_ID = '<string>' AWS_SECRET_KEY = '<string>' ) } ]

directoryTableParams (for internal stages) ::=
  [ DIRECTORY = ( ENABLE = { TRUE | FALSE }
                  [ AUTO_REFRESH = { 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 (파일 형식 유형 옵션):

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

(파일 형식 유형 옵션의 전체 목록은 다음 유형에도 적용됩니다: XML, PARQUET. 자세한 내용은 CREATE FILE FORMAT 문서를 참고하세요.)

Required parameters (필수 파라미터)

• <stage_name> — 스테이지의 식별자(이름)예요. 스테이지가 생성되는 스키마 내에서 고유해야 합니다. 이름은 정규화되어 데이터베이스와 스키마를 포함할 수 있어요(예: mydb.myschema.mystage). 식별자는 알파벳 문자로 시작해야 하고, 전체 식별자 문자열을 큰따옴표로 감싸지 않는 한 공백이나 특수 문자를 포함할 수 없어요. 자세한 내용은 Identifier requirements 문서를 참고하세요.
• URL = '<cloud>://<bucket>[/<path>/]' — 외부 스테이지의 경우, 스테이징된 데이터 파일이 저장된 클라우드 스토리지 위치(버킷과 경로)를 지정해요. 계정에서 스테이지를 만드는 역할은 지정된 URL에 접근할 수 있어야 합니다. 외부 스테이지에 URL은 필수예요.

Optional parameters (선택 파라미터)

• TEMP | TEMPORARY — 스테이지가 생성된 세션 동안만 지속되는 임시 스테이지임을 지정해요. 기본값: 영구 스테이지
• STORAGE_INTEGRATION = <integration_name> — 외부 스테이지의 경우, 클라우드 스토리지 위치에 대한 접근을 제공하는 기존 스토리지 통합의 이름을 지정해요. 자격 증명을 직접 제공하는 것보다 권장됩니다.
• CREDENTIALS = ( ... ) — 스토리지 통합 대신 클라우드 스토리지에 접근하는 데 사용할 자격 증명을 직접 지정해요. AWS의 경우 AWS_KEY_ID, AWS_SECRET_KEY, 선택적으로 AWS_TOKEN 또는 AWS_ROLE. Azure의 경우 AZURE_SAS_TOKEN. S3 호환 스토리지의 경우 AWS_KEY_ID, AWS_SECRET_KEY.
• ENCRYPTION = ( ... ) — 스테이지에서 데이터의 암호화 유형을 지정해요. 내부 스테이지: 'SNOWFLAKE_FULL'(기본) 또는 'SNOWFLAKE_SSE'. AWS: AWS_CSE, AWS_SSE_S3, AWS_SSE_KMS, NONE. GCS: GCS_SSE_KMS 또는 NONE. Azure: AZURE_CSE 또는 NONE. 서버 측 암호화(SSE)의 경우 Snowflake가 자격 증명을 추가로 요구하거나 클라이언트 측 암호화(CSE)의 경우 MASTER_KEY를 지정해야 해요.
• ENDPOINT = '<s3_api_compatible_endpoint>' — S3 호환 스토리지의 경우 S3 API 호환 엔드포인트를 지정해요.
• AWS_ACCESS_POINT_ARN = '<string>' — (AWS) 스테이지가 가리키는 S3 버킷에 대한 접근 권한을 부여하는 AWS 액세스 포인트의 ARN을 지정해요.
• USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE } — 보안 태세 강화를 위해 아웃바운드 프라이빗 연결을 사용할지 지정해요.
• DIRECTORY = ( ENABLE = { TRUE | FALSE } [ REFRESH_ON_CREATE = { TRUE | FALSE } ] [ AUTO_REFRESH = { TRUE | FALSE } ] [ NOTIFICATION_INTEGRATION = '<name>' ] ) — 스테이지의 디렉터리 테이블을 구성해요. ENABLE = TRUE는 스테이지의 디렉터리 테이블을 활성화합니다. AUTO_REFRESH는 스테이징된 파일이 변경될 때 디렉터리 테이블을 자동 새로 고침합니다(외부 스테이지의 경우 이벤트 알림 설정 필요). REFRESH_ON_CREATE는 스테이지 생성 시 디렉터리 테이블을 새로 고칠지 지정합니다. NOTIFICATION_INTEGRATION은 자동 새로 고침 알림에 사용할 알림 통합을 지정해요.
• FILE_FORMAT = ( ... ) — 스테이지에서 로드·언로드하는 파일에 사용할 파일 형식을 지정해요. FORMAT_NAME = '<file_format_name>'으로 기존 이름 형식을 참조하거나 TYPE = { CSV | JSON | AVRO | ORC | PARQUET | XML | CUSTOM }과 선택적 formatTypeOptions로 인라인 정의할 수 있어요.
• COMMENT = '<string_literal>' — 스테이지에 대한 주석을 지정해요. 기본값: 값 없음
• TAG ( ... ) — 태그 이름과 태그 문자열 값을 지정해요. 태그 값은 항상 문자열이며 최대 문자 수는 256이에요.

Access control requirements (접근 제어 요구 사항)

이 작업을 실행하는 데 사용되는 역할은 최소한 다음 권한을 보유해야 해요.

스키마의 객체를 조작하려면 상위 데이터베이스에 대한 권한과 상위 스키마에 대한 권한이 각각 최소 하나씩 필요합니다. 지정된 권한 집합으로 사용자 정의 역할을 만드는 방법은 Creating custom roles 문서를, 보안 객체에 대한 SQL 작업의 역할·권한 부여에 대한 일반적인 정보는 Overview of Access Control 문서를 참고하세요.

Usage notes (사용 참고 사항)

• 명명된 내부 스테이지 외에도 Snowflake는 각 사용자(@~)와 각 테이블(%@<table_name>)에 자동으로 스테이지를 제공해요. 명명된 스테이지는 여러 테이블 간에 공유하고 파일 형식 등을 유연하게 제어할 수 있습니다.
• COPY INTO <table> 또는 PUT 같은 후속 명령에서 스테이지를 참조할 수 있어요.

Examples (예제)

내부 스테이지를 만들어 봅시다.

CREATE STAGE my_int_stage;

Amazon S3를 가리키는 외부 스테이지를 만들어 봅시다.

CREATE STAGE my_s3_stage
  URL = 's3://mybucket/path/'
  STORAGE_INTEGRATION = my_storage_int
  FILE_FORMAT = ( TYPE = CSV FIELD_DELIMITER = ',' );

스테이지에 파일을 업로드해 봅시다.

PUT file:///data/employees.csv @my_int_stage;

스테이지에서 테이블로 데이터를 로드해 봅시다.

COPY INTO my_table
  FROM @my_int_stage/employees.csv;

더 알아보기 (Learn more)

• ALTER STAGE
• DROP STAGE
• SHOW STAGES
• DESCRIBE STAGE
• PUT
• COPY INTO
  COPY INTO
  CREATE FILE FORMAT