Snowflake 커넥터

Snowflake 커넥터 (Snowflake connector)

Snowflake 커넥터는 Trino 쿼리에서 외부 Snowflake 데이터베이스의 데이터를 읽고 쓸 수 있게 해줍니다. 이 커넥터 덕분에 Snowflake 데이터를 다른 데이터 소스와 한 번의 쿼리로 조합할 수 있어요.

출처: 문서

본문

요구 사항 (Requirements)

Snowflake에 연결하려면 다음이 필요합니다:

• Snowflake 서버.
• Trino 코디네이터와 워커에서 Snowflake로의 네트워크 접근.

설정 (Configuration)

Snowflake 커넥터를 example 카탈로그로 설정하려면 etc/catalog에 example.properties라는 파일을 만들고 다음 연결 속성을 넣어주세요:

connector.name=snowflake
connection-url=jdbc:snowflake://<account>.snowflakecomputing.com/?db=<database>&warehouse=<warehouse>&role=<role>&schema=<schema>
connection-user=<username>
connection-password=<password>

connection-url은 JDBC 드라이버에 전달할 연결 정보와 파라미터를 정의합니다. 커넥터는 Snowflake JDBC 드라이버를 사용하며, 연결 사용자 이름과 비밀번호가 필요합니다. 시크릿 (secrets)을 사용하면 카탈로그 속성 파일에 실제 값을 넣지 않고도 자격 증명을 관리할 수 있습니다.

데이터 소스 인증 (Data source authentication)

커넥터는 데이터 소스 연결용 자격 증명을 여러 방법으로 제공할 수 있습니다:

• 커넥터 설정 파일에 inline으로
• 별도의 properties 파일로
• 키 스토어 파일로
• Trino에 연결할 때 추가 자격 증명 (extra credentials)으로

시크릿 (secrets)을 활용하면 카탈로그 속성 파일에 민감한 값을 저장하지 않을 수 있어요.

일반 설정 속성 (General configuration properties)

다음 표는 커넥터의 일반적인 카탈로그 설정 속성을 설명합니다:

속성 이름	설명	기본값
case-insensitive-name-matching	대소문자 구분 없는 스키마/테이블 이름 지원 여부.	false
case-insensitive-name-matching.cache-ttl	대소문자 구분 없는 이름이 캐시되는 기간.	1m
case-insensitive-name-matching.config-file	이름 매핑 설정 파일(JSON) 경로.	null
case-insensitive-name-matching.config-file.refresh-period	이름 매핑 파일 변경 확인 주기.	0s
metadata.cache-ttl	테이블/컬럼 통계를 포함한 메타데이터 캐시 기간.	0s
metadata.cache-missing	메타데이터가 없음을 캐시할지 여부.	false
metadata.schemas.cache-ttl	스키마 메타데이터 캐시 기간.	metadata.cache-ttl 값
metadata.tables.cache-ttl	테이블 메타데이터 캐시 기간.	metadata.cache-ttl 값
metadata.statistics.cache-ttl	테이블 통계 캐시 기간.	metadata.cache-ttl 값
metadata.cache-maximum-size	메타데이터 캐시에 저장되는 최대 객체 수.	10000
write.batch-size	배치 실행에서의 최대 명령문 수. 기본값에서 바꾸지 마세요.	1000

데이터 유형 매핑 (Type mapping)

Trino와 Snowflake는 서로 지원하지 않는 유형이 있으므로, 이 커넥터는 데이터를 읽거나 쓸 때 일부 유형을 변환합니다. 각 방향의 매핑은 아래 표를 참고하세요.

Snowflake에서 Trino로의 유형 매핑:

Snowflake 유형	Trino 유형	비고
BOOLEAN	BOOLEAN
TINYINT	TINYINT
SMALLINT	SMALLINT
INTEGER	INTEGER
BIGINT	BIGINT
REAL	REAL
DOUBLE	DOUBLE
DECIMAL(p, s)	DECIMAL(p, s) — p ≤ 38이면 Trino DECIMAL, 아니면 NUMBER로 매핑.
VARCHAR	VARCHAR
CHAR	CHAR
VARBINARY	VARBINARY
DATE	DATE
TIME	TIME
TIMESTAMP_NTZ	TIMESTAMP
TIMESTAMP_TZ	TIMESTAMP WITH TIME ZONE

그 외 유형은 지원되지 않습니다.

Trino에서 Snowflake로의 유형 매핑:

Trino 유형	Snowflake 유형	비고
BOOLEAN	BOOLEAN
TINYINT	NUMBER(3, 0)
SMALLINT	NUMBER(5, 0)
INTEGER	NUMBER(10, 0)
BIGINT	NUMBER(19, 0)
REAL	DOUBLE
DOUBLE	DOUBLE
DECIMAL	NUMBER
VARCHAR	VARCHAR
CHAR	VARCHAR
VARBINARY	BINARY 또는 VARBINARY
DATE	DATE
TIME	TIME
TIMESTAMP	TIMESTAMP_NTZ
TIMESTAMP WITH TIME ZONE	TIMESTAMP_TZ

그 외 유형은 지원되지 않습니다.

유형 매핑 설정 속성 (Type mapping configuration properties)

속성 이름	설명	기본값
unsupported-type-handling	지원되지 않는 컬럼 유형 처리 방식: IGNORE(컬럼 접근 불가) 또는 CONVERT_TO_VARCHAR(무제한 VARCHAR로 변환). 해당 카탈로그 세션 속성은 unsupported_type_handling.	IGNORE
jdbc-types-mapped-to-varchar	무제한 VARCHAR로 변환할 유형의 쉼표 구분 목록을 강제 매핑.	—

SQL 지원 (SQL support)

커넥터는 Snowflake 데이터베이스의 데이터와 메타데이터에 대해 읽기/쓰기 접근을 제공합니다. 전역 사용 가능 명령문과 읽기 연산 명령문에 더해 다음 기능을 지원합니다:

• INSERT — 비트랜잭션 INSERT 참고
• DELETE
• TRUNCATE
• CREATE TABLE
• CREATE TABLE AS
• DROP TABLE
• ALTER TABLE
• CREATE SCHEMA
• DROP SCHEMA
• 프로시저
• 테이블 함수

비트랜잭션 INSERT (Non-transactional INSERT)

커넥터는 INSERT 문으로 행 추가를 지원합니다. 기본적으로 데이터는 임시 테이블에 먼저 기록됩니다. insert.non-transactional-insert.enabled 카탈로그 속성 또는 해당 non_transactional_insert 카탈로그 세션 속성을 true로 설정하면 이 단계를 건너뛰고 대상 테이블에 직접 기록해 성능을 높일 수 있습니다.

이 속성을 켜면 드물게 insert 작업 중 예외가 발생할 때 데이터가 손상될 수 있습니다. 트랜잭션이 비활성화되므로 롤백이 불가능합니다.

프로시저 (Procedures)

system.flush_metadata_cache()

JDBC 메타데이터 캐시를 비웁니다. 예를 들어 다음 시스템 호출은 example 카탈로그의 모든 스키마에 대한 메타데이터 캐시를 비웁니다:

USE example.example_schema;
CALL system.flush_metadata_cache();

system.execute('query')

execute 프로시저는 연결된 데이터 소스에서 쿼리를 직접 실행하게 해줍니다. 쿼리는 연결된 데이터 소스의 지원 문법을 사용해야 합니다. Trino에 없는 기능에 접근하거나, 결과 집합을 반환하지 않아 query나 raw_query 패스스루 테이블 함수로 사용할 수 없는 쿼리를 실행할 때 유용합니다. 대표적인 사례는 객체를 생성/수정하는 명령문으로, 제약 조건, 기본값, 자동 식별자 생성, 인덱스 같은 네이티브 기능이 필요할 때입니다. 데이터를 삽입/갱신/삭제하면서 결과를 반환하지 않는 명령문도 호출할 수 있습니다.

쿼리 텍스트는 Trino가 파싱하지 않고 그대로 전달하므로, 연결된 데이터 소스의 보안/접근 제어만 적용됩니다.

다음 예제는 example 카탈로그의 example_schema를 현재 데이터베이스로 설정한 뒤, 그 스키마에서 프로시저를 호출해 your_table 테이블의 your_column에서 기본값을 제거합니다:

USE example.example_schema;
CALL system.execute(query => 'ALTER TABLE your_table ALTER COLUMN your_column DROP DEFAULT');

특정 데이터베이스가 이 문법을 지원하는지 확인하고, 연결된 데이터베이스 및 버전 문서에 맞게 조정하세요.

테이블 함수 (Table functions)

커넥터는 Snowflake에 접근하기 위한 특정 테이블 함수를 제공합니다.

query(varchar) -> table

query 함수는 연결된 데이터베이스를 직접 조회하게 해줍니다. 전체 쿼리가 푸시다운되어 Snowflake에서 처리되므로 Snowflake 고유 문법이 필요합니다. Trino에 없는 네이티브 기능에 접근하거나, 네이티브 실행이 더 빠른 상황에서 쿼리 성능을 높일 때 유용합니다.

쿼리에서 사용할 수 있는 Snowflake SQL 지원에 대한 자세한 내용은 Snowflake SQL Command Reference에서 확인하세요. 여기에는 PIVOT, lateral joins 등이 포함됩니다.

연결된 데이터 소스에 전달되는 네이티브 쿼리는 결과 집합으로 테이블을 반환해야 합니다. 검증과 보안 검사는 오직 데이터 소스가 자체 설정으로 수행합니다. Trino는 이를 수행하지 않습니다. 패스스루 쿼리는 데이터 읽기에만 사용하세요.

간단한 예로, example 카탈로그를 조회해 전체 테이블을 선택합니다:

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        *
      FROM
        tpch.nation'
    )
  );

실용적인 예로, Snowflake가 지원하는 동적 PIVOT를 사용해 모든 고유 컬럼 값에 대해 자동으로 피벗할 수 있습니다:

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => '
        SELECT *
        FROM quarterly_sales
          PIVOT(SUM(amount) FOR quarter IN (ANY ORDER BY quarter))
        ORDER BY empid;
      '
    )
  );

쿼리 엔진은 이 함수의 결과 순서를 보존하지 않습니다. 전달한 쿼리에 ORDER BY 절이 있으면 함수 결과 순서가 예상과 다를 수 있습니다.

성능 (Performance)

커넥터는 다음 섹션에 설명된 여러 성능 개선을 포함합니다.

푸시다운 (Pushdown)

커넥터는 다음 연산에 대해 푸시다운을 지원합니다:

• LIMIT 푸시다운
• Top-N 푸시다운
• 다음 함수에 대한 집계 푸시다운: avg(), count(), max(), min(), sum(), stddev(), stddev_pop(), stddev_samp(), variance(), var_pop(), var_samp(), covar_pop(), covar_samp(), corr(), regr_intercept(), regr_slope()

커넥터는 성능이 향상될 수 있는 곳에서 푸시다운을 수행하지만, 정확성을 지키기 위해 일부 연산은 푸시다운되지 않을 수 있습니다. 푸시다운이 성능은 좋지만 정확성을 위험하게 한다면 커넥터는 정확성을 우선합니다.

더 알아보기 (Learn more)

Snowflake 커넥터로 다른 데이터 소스와 데이터를 조합해보세요. 커넥터의 일반적인 개념은 커넥터 개요 문서에서 확인할 수 있어요.