SQL Server용 Openflow Connector: Iceberg 테이블 대상

이 페이지에서는 SQL Server용 Openflow 다중 데이터베이스 커넥터가 선택(opt-in) 대상 형식으로 Snowflake 관리형 Apache Iceberg™ 테이블에 쓰도록 설정하는 방법을 설명해요. Iceberg v2와 v3를 모두 지원하며, 외부 볼륨·카탈로그·직렬화 정책은 대상 데이터베이스 기본값에서 상속받습니다.

출처: Snowflake 문서

본문

SQL Server용 Openflow 다중 데이터베이스 커넥터는 선택(opt-in) 대상 형식으로 Snowflake 관리형 Apache Iceberg™ 테이블에 쓰는 것을 지원합니다. Iceberg v2와 v3를 모두 지원합니다. Table Storage Format = ICEBERG 설정과 Iceberg Version 선택만 커넥터 수준에서 변경하면 됩니다. 외부 볼륨, 카탈로그, 직렬화 정책은 Snowflake 대상 데이터베이스 기본값에서 상속됩니다. Iceberg 사양 버전은 기본값이 3인 Iceberg Version 커넥터 파라미터로 설정됩니다.

스토리지는 Apache Iceberg™ 테이블용 Snowflake 스토리지(EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED') 또는 클라우드 스토리지의 외부 볼륨 중 하나가 될 수 있습니다. Snowflake 스토리지를 사용하면 외부 클라우드 스토리지나 IAM 부여가 필요 없습니다.

표준 테이블을 사용하는 기존 커넥터는 영향을 받지 않습니다.

사전 준비 사항

Openflow 런타임: 커넥터를 호스팅할 기존 런타임.
CDC 또는 Change Tracking용으로 구성된 SQL Server 소스:
- CDC의 경우: 데이터베이스와 각 복제 테이블에서 CDC를 활성화하세요.
- Change Tracking의 경우: 데이터베이스와 기본 키가 있는 각 복제 테이블에서 변경 추적을 활성화하세요.
- 자세한 내용은 Set up the Openflow Connector for SQL Server 또는 Set up the SQL Server CDC connector를 참고하세요.
클라우드 스토리지의 외부 볼륨: Iceberg 스토리지용으로 구성된 외부 볼륨으로, 커넥터의 Snowflake 역할에 USAGE가 부여되어 있어야 합니다. CREATE EXTERNAL VOLUME 참고. Snowflake 스토리지(EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED')를 사용할 때는 필요하지 않습니다.
Snowflake 대상 데이터베이스: Iceberg 파라미터(다음 섹션)로 구성된 기존 데이터베이스.

1단계: Snowflake 대상 데이터베이스 구성

대상 데이터베이스에 Iceberg 기본값을 설정합니다. 커넥터는 런타임에 외부 볼륨과 직렬화 정책에 대해 이 기본값을 읽습니다. Iceberg 사양 버전은 데이터베이스 수준 ICEBERG_VERSION_DEFAULT뿐 아니라 커넥터별 Iceberg Version 파라미터(3단계 참고)로 구성됩니다.

옵션 A: Snowflake 스토리지

Snowflake 스토리지를 사용하면 Snowflake가 Iceberg 테이블 파일을 저장·관리합니다. 외부 클라우드 스토리지나 IAM 부여가 필요 없습니다.

CREATE DATABASE <db>
  EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED'
  STORAGE_SERIALIZATION_POLICY = <COMPATIBLE|OPTIMIZED>;

기존 데이터베이스를 구성하려면:

ALTER DATABASE <db> SET
  EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED'
  STORAGE_SERIALIZATION_POLICY = <COMPATIBLE|OPTIMIZED>;

옵션 B: 클라우드 스토리지의 외부 볼륨

테이블 파일을 자체 클라우드 스토리지에 유지해야 한다면 데이터베이스를 외부 볼륨으로 구성하세요:

CREATE DATABASE <db>
  EXTERNAL_VOLUME = '<volume>'
  STORAGE_SERIALIZATION_POLICY = <COMPATIBLE|OPTIMIZED>;

기존 데이터베이스를 구성하려면:

ALTER DATABASE <db> SET
  EXTERNAL_VOLUME = '<volume>'
  STORAGE_SERIALIZATION_POLICY = <COMPATIBLE|OPTIMIZED>;

Parameter	Required	Notes
EXTERNAL_VOLUME	Yes	Iceberg 파일 스토리지용 외부 볼륨.
ICEBERG_VERSION_DEFAULT	No	2 또는 3. Iceberg Version 파라미터가 설정되지 않은 이전 커넥터 흐름을 위한 레거시 폴백. 새 커넥터는 커넥터 파라미터(3단계)로 버전을 설정하며 이 데이터베이스 설정이 필요 없습니다.
STORAGE_SERIALIZATION_POLICY	Yes	COMPATIBLE은 외부 엔진이 읽을 수 있는 Parquet 파일을 생성합니다. OPTIMIZED는 Snowflake 특유의 쿼리 최적화를 활성화합니다. 데이터 쿼리 요구 사항에 따라 선택하세요. 자세한 내용은 STORAGE_SERIALIZATION_POLICY 참고.

Note

CATALOG = 'SNOWFLAKE'는 각 CREATE ICEBERG TABLE 문에서 커넥터가 자동으로 설정합니다. 데이터베이스 수준에서는 설정하지 마세요.

각 테이블의 기본 위치는 flat layout을 사용해 자동으로 도출됩니다: STORAGE_BASE_URL/database/schema/table_name.randomId/[data | metadata]/. 사용자 구성이 필요 없습니다.

클라우드 스토리지의 외부 볼륨(옵션 B)을 사용한다면 커넥터의 Snowflake 역할에 외부 볼륨에 대한 USAGE를 부여하세요:

GRANT USAGE ON EXTERNAL VOLUME <volume> TO ROLE OPENFLOW_<RUNTIME_NAME>_EXECUTE_AS_RL;

Snowflake 스토리지에서는 이 단계가 필요하지 않습니다.

2단계: 커넥터 파라미터 컨텍스트에서 Table Storage Format 설정

커넥터의 대상 파라미터 컨텍스트에서 Table Storage Format 파라미터를 ICEBERG로 설정합니다. 기본값은 STANDARD입니다.

전체 커넥터 생성·구성 워크플로는 Set up the Openflow Connector for SQL Server 또는 Set up the SQL Server CDC connector를 참고하세요.

3단계: Iceberg 버전 설정

Iceberg Version 커넥터 파라미터를 2 또는 3으로 설정합니다. 이것은 타입 매핑에 사용되는 Iceberg 사양 버전(예: v3에서 JSON은 variant로, v2에서는 string으로 매핑)과 CREATE ICEBERG TABLE DDL의 ICEBERG_VERSION=<n> 절을 제어합니다.

Iceberg Version 파라미터는 기본값이 3입니다. 커넥터를 시작하기 전에 필요하면 2로 검토·변경하세요. 수집이 시작된 후에는 이 값을 변경하지 마세요.

4단계: 시작 및 확인

평소처럼 커넥터를 시작합니다. 초기 스냅샷이 완료된 뒤 대상 테이블이 Iceberg인지 확인하세요:

-- Confirm the table is Iceberg
SELECT GET_DDL('TABLE', '<db>.<schema>.<table>');

-- Confirm the Iceberg version on the database
SHOW PARAMETERS LIKE 'ICEBERG_VERSION_DEFAULT' IN DATABASE <db>;

알려진 제한 사항

Tri-Secret Secure 계정과 Snowflake 스토리지: Tri-Secret Secure(TSS)가 활성화된 계정은 Apache Iceberg™ 테이블용 Snowflake 스토리지를 사용하는 새 Snowflake 관리형 Iceberg 테이블을 만들지 못할 수 있습니다. 자세한 내용은 Encryption을 참고하세요.
호환되지 않는 타입 변경. 소스 열 타입이 다른 Iceberg 타입으로 매핑되는 타입으로 변경되면 테이블은 실패로 표시되고 재스냅샷이 필요합니다. 전체 소스-대-Iceberg 타입 매핑은 Type mapping reference를 참고하세요.
같은 Iceberg 타입 내 파라미터 변경. 커넥터는 같은 Iceberg 타입 내의 파라미터 변경(예: decimal(10,2)를 decimal(20,2)로)을 인식하지 못합니다. 열은 현재 Iceberg 타입을 유지합니다.
v3의 나노초 타임스탬프 범위 제한: v3에서 DATETIME2(7) 또는 DATETIMEOFFSET(7)이 timestamp_ns 또는 timestamptz_ns로 매핑되면 표현 가능한 날짜 범위가 1677-09-21부터 2262-04-11로 좁아집니다. 이 범위를 벗어나는 값은 삽입 시 거부됩니다.
DATETIMEOFFSET 오프셋이 UTC로 축소됨: Iceberg에는 오프셋을 보존하는 타임스탬프 타입이 없습니다. 원래 시간대 오프셋은 손실되며 UTC 순간만 저장됩니다.
v3에서 소스 타임스탬프 정밀도 확장 미지원: 소스 열의 정밀도가 증가하면(예: DATETIME2(6)를 DATETIME2(7)로 변경) Iceberg 열 타입을 timestamp에서 timestamp_ns로 승격할 수 없습니다. 커넥터는 원래 정밀도를 기준으로 생성되었습니다.
커넥터 시작 후 Table Storage Format이나 Iceberg Version을 변경하지 마세요: 수집 시작 후 커넥터의 Table Storage Format과 Iceberg Version 파라미터를 수정하지 말아야 합니다. 대상 테이블 간 설정 혼합은 지원되지 않습니다. 전환하려면 Switching table storage format or Iceberg version의 단계를 따르세요.

타입 매핑 참조

다음 표는 SQL Server 타입이 Snowflake 표준 및 Iceberg 대상 타입으로 매핑되는 방식을 보여줍니다:

SQL Server type	Snowflake (Standard)	Iceberg v3	Iceberg v2
TINYINT / SMALLINT / INT	INT	long	long
BIGINT	INT	long	long
BIT	BOOLEAN	boolean	boolean
DECIMAL(P,S) / NUMERIC(P,S)	NUMBER(P,S)	decimal(P,S)	decimal(P,S)
MONEY	NUMBER(19,4)	decimal(19,4)	decimal(19,4)
SMALLMONEY	NUMBER(10,4)	decimal(10,4)	decimal(10,4)
FLOAT / FLOAT(53)	FLOAT	double	double
REAL / FLOAT(n) (n ≤ 24)	FLOAT	double	double
DATE	DATE	date	date
TIME(0..6)	TIME	time	time
TIME(7)	TIME	time (100ns truncated)	time (100ns truncated)
SMALLDATETIME	TIMESTAMP_NTZ	timestamp	timestamp
DATETIME	TIMESTAMP_NTZ	timestamp	timestamp
DATETIME2(0..6)	TIMESTAMP_NTZ	timestamp	timestamp
DATETIME2(7)	TIMESTAMP_NTZ	timestamp_ns	timestamp (100ns truncated)
DATETIMEOFFSET(0..6)	TIMESTAMP_TZ	timestamptz	timestamptz
DATETIMEOFFSET(7)	TIMESTAMP_TZ	timestamptz_ns	timestamptz (100ns truncated)
CHAR / VARCHAR / NCHAR / NVARCHAR / TEXT / NTEXT	TEXT	string	string
BINARY / VARBINARY / IMAGE	BINARY	binary	binary
XML	TEXT	string	string
JSON (SQL Server 2025)	VARIANT	variant	string
UNIQUEIDENTIFIER	TEXT	string	string
ROWVERSION	TEXT	string	string
SQL_VARIANT	TEXT	string	string
GEOMETRY / GEOGRAPHY	TEXT	string	string

표에 나열되지 않은 소스 타입은 표준 테이블에서 TEXT로, Iceberg 테이블에서 string으로 매핑됩니다.

테이블 스토리지 형식 또는 Iceberg 버전 전환

Standard와 Iceberg 사이, 또는 Iceberg v2와 v3 사이를 전환하려면 커넥터를 다시 만들어야 합니다. 다음 단계를 따르세요:

커넥터를 중지합니다.
Openflow에서 프로세스 그룹을 삭제합니다.
대상 데이터베이스를 수동으로 정리합니다(복제된 스키마/테이블을 드롭하거나 새 데이터베이스 사용).
새 Table Storage Format으로 커넥터를 다시 가져오고, 커넥터 구성 시 대상 Iceberg Version을 선택합니다.

이렇게 하면 Openflow 내에서 모든 커넥터 상태가 올바르게 정리됩니다. 새 커넥터가 대상에 새 스냅샷을 수행합니다.

기존 커넥터를 Iceberg 버전 고정용으로 업그레이드

커넥터 버전 0.45.0(다중 데이터베이스) / 0.44.0(CDC)은 Iceberg Version 파라미터를 도입합니다. 이전 커넥터 버전에서 업그레이드한다면 기존 대상 테이블과 일치하도록 구성해야 하는 새 Iceberg Version 필드가 나타납니다.

커넥터를 중지합니다.
런타임 업그레이드를 버전 2026.7.21 이상으로 합니다.
커넥터를 제자리에서 업그레이드합니다(위에 나열한 버전 이상으로).
플로우 업그레이드 후 Iceberg Version 파라미터는 기본값 3이 됩니다. 기존 대상 테이블이 Iceberg v2라면 커넥터를 시작하기 전에 2로 검토·변경하세요.
커넥터를 시작합니다.

Caution

기존 대상 테이블과 일치하지 않는 Iceberg Version을 선택하면 타입 매핑 오류나 DDL 실패가 발생할 수 있습니다. 값을 선택하기 전에 항상 기존 테이블의 버전을 확인하세요.

SQL Server용 Openflow Connector: Iceberg 테이블 대상