CREATE DATABASE

CREATE DATABASE (catalog-linked)

외부 Iceberg REST 카탈로그를 사용하는 Apache Iceberg™ 테이블용 새 카탈로그 연결(catalog-linked) 데이터베이스를 만드는 명령이에요.

출처: 문서

본문

외부 Iceberg REST 카탈로그를 사용하는 Apache Iceberg™ 테이블용 새 카탈로그 연결 데이터베이스를 만들어요.

구문 (Syntax)

CREATE DATABASE <name>
  LINKED_CATALOG = ( catalogParams ),
  [ EXTERNAL_VOLUME = '<external_vol>' ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ CATALOG_CASE_SENSITIVITY = { CASE_SENSITIVE | CASE_INSENSITIVE } ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

여기서:

catalogParams ::=
  CATALOG = '<catalog_int>',
  [ ALLOWED_NAMESPACES = ('<namespace1>', '<namespace2>', ... ) ]
  [ BLOCKED_NAMESPACES = ('<namespace1>', '<namespace2>', ... ) ]
  [ ALLOWED_WRITE_OPERATIONS = { NONE | ALL } ]
  [ NAMESPACE_MODE = { IGNORE_NESTED_NAMESPACE | FLATTEN_NESTED_NAMESPACE } ]
  [ NAMESPACE_FLATTEN_DELIMITER = '<string_literal>' ]
  [ SYNC_INTERVAL_SECONDS = <value> ]

필수 매개변수 (Required parameters)

name 카탈로그 연결 데이터베이스의 식별자를 지정하며, 계정 안에서 고유해야 해요.

또한 식별자는 반드시 알파벳 문자로 시작해야 하며, 전체 식별자 문자열이 큰따옴표로 묶이지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 묶인 식별자는 대소문자를 구분해요.

자세한 내용은 식별자 요구 사항(Identifier requirements)을 참고해요.

선택 매개변수 (Optional parameters)

EXTERNAL_VOLUME = my_external_vol 원격 Iceberg 테이블의 데이터와 메타데이터에 대한 접근을 제공하는 외부 볼륨(external volume)을 지정해요.

벤디드 자격 증명(vended credentials)을 사용하면 필요하지 않아요.

COMMENT = 'string_literal' 데이터베이스에 대한 설명(comment)을 지정해요.

• 기본값: 값 없음

CATALOG_CASE_SENSITIVITY = { CASE_SENSITIVE | CASE_INSENSITIVE } 외부 Iceberg 카탈로그가 식별자에 사용하는 대소문자 구분을 지정해요.

• CASE_SENSITIVE: 외부 Iceberg 카탈로그가 대소문자 구분 식별자를 사용해요. 예를 들어 Snowflake Open Catalog는 대소문자 구분 카탈로그예요.
  • Snowflake는 식별자를 표시된 그대로(대소문자 포함) 정확히 일치시켜요. Snowflake는 인용되지 않은 식별자를 자동으로 대문자로 변환하지만, 인용된 식별자는 외부 카탈로그의 정확한 대소문자와 일치해야 해요.
  • 다만 외부 Iceberg 카탈로그가 실제로 대소문자를 구분하지 않고 소문자로 정규화한다면, 식별자를 큰따옴표로 감싸야 해요.
  • 이 요구 사항은 기존 스키마·테이블·테이블 컬럼을 식별하는 데만 적용돼요.
• CASE_INSENSITIVE: 외부 Iceberg 카탈로그가 대소문자 비구분 식별자를 사용해요. 예를 들어 Unity Catalog와 AWS Glue는 대소문자 비구분 카탈로그예요.
  • Snowflake는 쿼리와 CREATE ICEBERG TABLE, CREATE SCHEMA, ALTER ICEBERG TABLE 같은 DDL 명령을 포함한 모든 SQL 문에서 인용되지 않은 식별자를 대소문자 비구분 방식으로 해석해요. 식별자를 큰따옴표로 묶을 필요가 없어요. DDL로 객체를 만들 때 Snowflake는 원격 카탈로그에서 객체 이름을 소문자로 정규화해요. 큰따옴표로 묶인 식별자와 QUOTED_IDENTIFIERS_IGNORE_CASE에 대해서는 카탈로그 연결 데이터베이스의 식별자 해석 요구 사항을 참고해요.
  • 다만 외부 Iceberg 카탈로그가 실제로 대소문자를 구분한다면, Snowflake는 인용되지 않은 식별자를 대소문자 비구분으로 취급하고 자동으로 대문자로 변환해요. 객체를 만들거나 쿼리할 때 Snowflake는 인용되지 않은 한 대소문자와 관계없이 식별자를 일치시켜요.
  • 이 패턴은 대소문자만 다른 두 식별자를 Snowflake가 해석할 수 없으므로 권장되지 않아요. 이 패턴은 대소문자만 다른 두 식별자가 없을 때만 작동해요.
• 기본값: CASE_INSENSITIVE

식별자 해석 요구 사항(예시 포함)에 대한 자세한 내용은 카탈로그 연결 데이터베이스의 식별자 해석 요구 사항을 참고해요.

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] ) 태그 이름과 태그 문자열 값을 지정해요.

태그 값은 항상 문자열이며, 태그 값의 최대 문자 수는 256이에요.

문에서 태그를 지정하는 방법에 대한 정보는 태그 할당량(Tag quotas)을 참고해요.

WITH CONTACT ( purpose = contact [ , purpose = contact ...] ) 새 객체를 하나 이상의 연락처(contact)와 연결해요. 이 명령이 지원한다면 AS 절을 제외한 다른 모든 절 뒤에 WITH CONTACT 절을 지정해요.

카탈로그 매개변수 (catalogParams)

CATALOG = catalog_int 카탈로그 인티그레이션의 이름을 지정해요.

ALLOWED_NAMESPACES = ('namespace1', 'namespace2', ... ) 선택 사항. 자동 테이블 검색의 범위를 제한하기 위해 원격 카탈로그에서 하나 이상의 네임스페이스를 지정해요. Snowflake는 지정된 네임스페이스와 그 아래에 중첩된 모든 네임스페이스·테이블을 동기화해요. 중첩된 네임스페이스가 ALLOWED_NAMESPACES 목록에 있지만 NAMESPACE_MODE를 IGNORE_NESTED_NAMESPACE로 설정했다면, Snowflake는 그 중첩 네임스페이스와 그 아래의 스키마·테이블을 동기화하지 않아요.

BLOCKED_NAMESPACES = ('namespace1', 'namespace2', ... ) 선택 사항. 자동 테이블 검색에서 차단할 원격 카탈로그의 하나 이상의 네임스페이스를 지정해요.

Snowflake는 지정된 네임스페이스와 그 아래에 중첩된 모든 네임스페이스·테이블을 차단해요.

ALLOWED_NAMESPACES와 BLOCKED_NAMESPACES를 둘 다 지정하면 BLOCKED_NAMESPACES 목록이 우선해요. 예를 들어 ns1.ns2가 허용되지만 ns1이 차단되면, Snowflake는 ns1.ns2를 동기화하지 않아요.

ALLOWED_WRITE_OPERATIONS = { NONE | ALL } 카탈로그 연결 데이터베이스가 읽기 전용인지 쓰기 가능한지 지정해요.

• NONE: 카탈로그 연결 데이터베이스가 읽기 전용이에요. 읽기 전용일 때 카탈로그 커밋이 필요한 작업(예: DROP ICEBERG TABLE)은 실패해요.
• ALL: 카탈로그 연결 데이터베이스가 쓰기 가능해요.

  • ⚠️ 경고: 카탈로그 연결 데이터베이스에 쓰기 권한이 활성화되면, Snowflake가 테이블 드롭을 원격 카탈로그에 전파해 두 시스템 모두에서 테이블과 데이터가 제거돼요.

• 기본값: ALL

NAMESPACE_MODE = { IGNORE_NESTED_NAMESPACE | FLATTEN_NESTED_NAMESPACE } 카탈로그 연결 데이터베이스의 Iceberg 테이블에 대해 Snowflake가 네임스페이스를 처리하는 방법을 지정해요.

• IGNORE_NESTED_NAMESPACE: Snowflake는 카탈로그의 첫 번째 네임스페이스 수준에 있는 테이블만 연결해요.
• FLATTEN_NESTED_NAMESPACE: Snowflake는 카탈로그의 모든 네임스페이스 수준에 있는 테이블을 연결해요. 중첩 네임스페이스의 테이블에 대해 Snowflake는 NAMESPACE_FLATTEN_DELIMITER 매개변수로 펼쳐진(flattened) 네임스페이스를 구성해요. 이 옵션을 사용하면 NAMESPACE_FLATTEN_DELIMITER 매개변수를 설정해야 해요.

예를 들어 namespace3aa 네임스페이스에 iceberg_table_5라는 테이블이 있다고 가정해요.

my_catalog_linked_db
|-- namespace3
|   |-- namespace3a
|       |-- namespace3aa
|           |-- iceberg_table_5

NAMESPACE_FLATTEN_DELIMITER = "/"로 설정하면 "my_catalog_linked_db"."namespace3/namespace3a/namespace3aa"."iceberg_table_5"로 테이블을 지정할 수 있어요.

• 기본값: IGNORE_NESTED_NAMESPACE

FLATTEN_NESTED_NAMESPACE는 카탈로그 인티그레이션이 중첩 네임스페이스를 지원하는 카탈로그를 사용할 때만 지원돼요. 다른 REST 카탈로그에서는 이 옵션을 설정하면 오류가 반환돼요.

NAMESPACE_FLATTEN_DELIMITER = 'string_literal' NAMESPACE_MODE = FLATTEN_NESTED_NAMESPACE로 설정하면 필수예요. 카탈로그의 테이블에 대해 펼쳐진 네임스페이스를 구성하는 데 Snowflake가 사용하는 구분자를 지정해요.

⚠️ 중요: 구분자로 선택한 문자는 원격 네임스페이스에 나타날 수 없어요. 자동 검색 프로세스 동안 Snowflake는 구분자를 포함하는 모든 네임스페이스를 건너뛰고 해당하는 스키마를 카탈로그 연결 데이터베이스에 만들지 않아요.

유효한 문자: 구두점 문자·기호·숫자 하나 이상. 문자와 공백은 허용되지 않아요.

SYNC_INTERVAL_SECONDS = value Snowflake가 원격 카탈로그의 스키마와 테이블을 자동으로 검색하는 데 사용할 시간 간격(초)을 지정해요.

• 값: 30~86400 (1일) (포함)
• 기본값: 30초

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

이 작업을 실행하는 데 사용하는 역할(role)은 최소한 다음 권한을 가져야 해요.

권한 (Privilege)	객체 (Object)	비고
CREATE DATABASE	Account	새 데이터베이스를 만드는 데 필요해요. 기본적으로 SYSADMIN 역할 또는 그보다 높은 역할만 이 권한을 가져요. 필요에 따라 추가 역할에 부여될 수 있어요.
USAGE	External Volume	기존 외부 볼륨을 참조하는 데 필요해요.
USAGE	Catalog integration	기존 카탈로그 인티그레이션을 참조하는 데 필요해요.

지정된 권한 집합으로 사용자 지정 역할을 만드는 방법은 사용자 지정 역할 만들기(Creating custom roles)를 참고해요. 보호 가능한 객체에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여의 일반적인 내용은 접근 제어 개요(Overview of Access Control)를 참고해요.

사용 메모 (Usage notes)

Iceberg REST용 카탈로그 인티그레이션(예: Snowflake Open Catalog)을 사용할 때만 지원돼요.

자동 테이블 검색을 특정 네임스페이스 집합으로 제한하려면 ALLOWED_NAMESPACES 매개변수를 사용해요. 네임스페이스 집합을 차단하려면 BLOCKED_NAMESPACES 매개변수를 사용할 수도 있어요.

Snowflake는 사용자나 역할에 대한 원격 카탈로그 접근 제어를 동기화하지 않아요.

카탈로그 연결 데이터베이스에 스키마, 외부 관리 Iceberg 테이블, 데이터베이스 역할을 만들 수 있어요. 다른 Snowflake 객체를 만드는 것은 현재 지원되지 않아요.

카탈로그 연결 데이터베이스를 만들 때 Iceberg 테이블에 사용할 기본 Iceberg 버전이나 merge-on-read 동작을 지정할 수 없어요.

다만 기존 데이터베이스에 대해 ALTER DATABASE (catalog-linked) 명령으로 다음 매개변수를 설정해 이러한 속성을 수정할 수 있어요.

• ICEBERG_VERSION_DEFAULT
• ICEBERG_MERGE_ON_READ_BEHAVIOR

카탈로그 연결 데이터베이스의 Iceberg 테이블의 경우:

• Snowflake는 원격 카탈로그와 Snowflake 사이에 테이블·컬럼 설명을 양방향으로 동기화해요. 동기화는 설명을 새 값으로 업데이트할 수 있지만, 비어 있지 않은 설명을 빈 설명으로 바꾸지는 않아요. 보존 정책이나 버퍼 같은 다른 원격 카탈로그 테이블 속성은 복사되지 않으며, 테이블 속성 변경은 현재 지원되지 않아요.
• 자동 새로 고침은 기본적으로 활성화돼요. 외부 테이블의 table-uuid와 카탈로그 연결 데이터베이스 테이블의 table-uuid가 일치하지 않으면 새로 고침이 실패하고 Snowflake가 카탈로그 연결 데이터베이스에서 테이블을 삭제해요. 원격 테이블은 변경되지 않아요.
• 원격 카탈로그에서 테이블을 삭제하면 Snowflake가 카탈로그 연결 데이터베이스에서 그 테이블을 삭제해요. 이 작업은 비동기이므로 원격 카탈로그에서 변경을 바로 보지 못할 수 있어요.
• 원격 카탈로그에서 테이블 이름을 바꾸면 Snowflake가 카탈로그 연결 데이터베이스에서 기존 테이블을 삭제하고 새 이름의 테이블을 만들어요.
• 마스킹 정책과 태그가 지원돼요. 복제·클론을 포함한 다른 Snowflake 특정 기능은 지원되지 않아요.

NAMESPACE_FLATTEN_DELIMITER 매개변수로 선택한 문자는 원격 네임스페이스에 나타날 수 없어요. 자동 검색 프로세스 동안 Snowflake는 구분자를 포함하는 모든 네임스페이스를 건너뛰고 해당하는 스키마를 카탈로그 연결 데이터베이스에 만들지 않아요.

NAMESPACE_FLATTEN_DELIMITER 매개변수에 _, $, 숫자 외의 것을 지정하면 테이블을 쿼리할 때 스키마 이름을 따옴표로 묶어야 해요.

네임스페이스가 다른 네임스페이스 아래에 중첩되어 있는지 확인하려면 SHOW SCHEMAS 명령을 사용하고 출력의 is_nested 컬럼을 확인해요.

AWS Glue에 연결된 데이터베이스의 경우 소문자를 사용하고 스키마·테이블·컬럼 이름을 큰따옴표로 감싸야 해요. 소문자 식별자만 지원하는 다른 Iceberg REST 카탈로그에도 이 요구 사항이 적용돼요.

다음 예시는 유효한 쿼리를 보여줘요.

CREATE SCHEMA "s1";

다음 문은 대문자를 사용하거나 큰따옴표를 생략하므로 유효하지 않아요.

CREATE SCHEMA s1;
CREATE SCHEMA "Schema1";

UNDROP ICEBERG TABLE 사용은 지원되지 않아요.

공유(Sharing):

• 리스팅을 통한 공유는 현재 지원되지 않아요.
• 직접 공유(direct sharing)는 지원돼요.

카탈로그 연결 데이터베이스의 테이블 쓰기의 경우:

• 중첩 네임스페이스의 테이블 생성·쓰기는 카탈로그 인티그레이션이 중첩 네임스페이스를 지원하는 카탈로그를 사용할 때만 지원돼요. 다른 REST 카탈로그에서는 중첩 네임스페이스의 테이블 생성·쓰기가 지원되지 않아요.
• 네임스페이스 이름에 마침표(.)를 사용하지 마세요. 단, NAMESPACE_FLATTEN_DELIMITER 값이 마침표이고 NAMESPACE_MODE가 FLATTEN_NESTED_NAMESPACE로 설정된 경우는 예외예요. 그렇지 않으면 네임스페이스가 만들어지지 않아요.

Position row-level deletes는 Amazon S3, Azure, Google Cloud에 저장된 테이블에서 지원돼요. Equality delete 파일이 있는 row-level deletes는 지원되지 않아요. row-level deletes에 대한 자세한 내용은 row-level deletes 사용(Use row-level deletes)을 참고해요. copy-on-write 모드에서 DML(Data Manipulation Language) 작업 실행을 활성화하는 position deletes를 끄려면 테이블·스키마·데이터베이스 수준에서 ICEBERG_MERGE_ON_READ_BEHAVIOR 매개변수를 'DISABLED'로 설정해요.

ALLOWED_NAMESPACES와 BLOCKED_NAMESPACES의 경우, 집합에 상위 네임스페이스가 이미 있으면 Snowflake는 중첩 네임스페이스를 저장하지 않아요. 예를 들어 ALLOWED_NAMESPACES = ('ns1', 'ns1.ns2', 'ns1.ns3')로 데이터베이스를 만들면, 다른 두 개는 자동으로 포함되므로 Snowflake는 ns1만 저장해요. 예시 데이터베이스에 GET_DDL을 사용하면 ALLOWED_NAMESPACES = ('ns1')이 반환돼요. BLOCKED_NAMESPACES도 동일해요.

카탈로그 연결 데이터베이스의 객체에 대한 접근 제어를 관리하기 위해 카탈로그 연결 데이터베이스에 데이터베이스 역할을 만들 수 있어요. 예를 들어 카탈로그 연결 데이터베이스의 스키마와 테이블에 대한 권한을 데이터베이스 역할에 부여하고, 그 데이터베이스 역할을 계정 역할에 부여할 수 있어요.

카탈로그 연결 데이터베이스의 테이블 쿼리의 경우:

• Snowflake는 인용되지 않은 식별자(테이블·컬럼 이름)를 자동으로 대문자로 변환해요. 외부 Iceberg 카탈로그가 대소문자 구분 식별자를 사용한다면 테이블·컬럼 이름을 큰따옴표로 감싸야 해요.
• 객체 식별자에 대한 자세한 내용은 식별자 요구 사항(Identifier requirements)을 참고해요.

메타데이터에 관해서는 다음 사항에 주의해요.

⚠️ 주의: 고객은 Snowflake 서비스를 사용할 때 (User 객체를 제외하고) 개인 데이터·민감 데이터·수출 통제 데이터·기타 규제 데이터를 메타데이터로 입력하지 않도록 해야 해요. 자세한 내용은 Snowflake의 메타데이터 필드를 참고해요.

예시 (Examples)

외부 볼륨을 사용하는, 펼쳐진 중첩 네임스페이스가 있는 카탈로그 연결 데이터베이스를 만들어요.

CREATE DATABASE my_linked_db
  LINKED_CATALOG = (
    CATALOG = 'my_catalog_int',
    NAMESPACE_MODE = FLATTEN_NESTED_NAMESPACE,
    NAMESPACE_FLATTEN_DELIMITER = '-'
  )
  EXTERNAL_VOLUME = 'my_external_vol';

벤디드 자격 증명을 사용하고 허용된 네임스페이스 하나를 지정하는 카탈로그 연결 데이터베이스를 만들어요.

CREATE DATABASE my_linked_db
  LINKED_CATALOG = (
    CATALOG = 'my_catalog_int_vended_creds',
    ALLOWED_NAMESPACES = ('my_namespace')
  );

카탈로그 연결 데이터베이스에 데이터베이스 역할을 만들고 권한을 부여해요.

CREATE DATABASE ROLE my_linked_db.analyst;

GRANT USAGE ON SCHEMA my_linked_db.my_namespace TO DATABASE ROLE my_linked_db.analyst;

GRANT SELECT ON ALL ICEBERG TABLES IN SCHEMA my_linked_db.my_namespace TO DATABASE ROLE my_linked_db.analyst;

GRANT DATABASE ROLE my_linked_db.analyst TO ROLE data_consumer;

더 알아보기 (Learn more)

• CREATE DATABASE — 데이터베이스 생성
• ALTER DATABASE (catalog-linked) — 카탈로그 연결 데이터베이스 수정
• 카탈로그 연결 데이터베이스의 식별자 해석 요구 사항 — 식별자 규칙