CREATE CATALOG INTEGRATION(Apache Iceberg™ REST)¶
계정에 새로운 카탈로그 통합 을 만들거나 오픈 소스 Apache Iceberg™ REST OpenAPI 사양 을 준수하는 원격 카탈로그에서 관리되는 Apache Iceberg™ 테이블 에 대한 기존 카탈로그 통합을 대체합니다.
참고
Snowflake Open Catalog 에 대한 통합을 생성하려면 대신 CREATE CATALOG INTEGRATION(Snowflake Open Catalog) 섹션을 참조하십시오.
- 참고 항목:
ALTER CATALOG INTEGRATION , DROP CATALOG INTEGRATION , SHOW CATALOG INTEGRATIONS, DESCRIBE CATALOG INTEGRATION
구문¶
CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ] <name>
CATALOG_SOURCE = ICEBERG_REST
TABLE_FORMAT = ICEBERG
CATALOG_NAMESPACE = '<namespace>'
REST_CONFIG = (
restConfigParams
)
REST_AUTHENTICATION = (
restAuthenticationParams
)
ENABLED = { TRUE | FALSE }
[ REFRESH_INTERVAL_SECONDS = <value> ]
[ COMMENT = '<string_literal>' ]
여기서
restConfigParams ::=
CATALOG_URI = '<rest_api_endpoint_url>'
[ PREFIX = '<prefix>' ]
[ WAREHOUSE = '<warehouse_name>' ]
[ CATALOG_API_TYPE = { PUBLIC | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY | AWS_GLUE } ]
restAuthenticationParams
는 인증 방법에 따라 다음과 같습니다.
OAuth
restAuthenticationParams (for OAuth) ::=
TYPE = OAUTH
[ OAUTH_TOKEN_URI = 'https://<token_server_uri>' ]
OAUTH_CLIENT_ID = '<oauth_client_id>'
OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
OAUTH_ALLOWED_SCOPES = ('<scope_1>', '<scope_2>')
전달자 토큰
restAuthenticationParams (for Bearer token) ::=
TYPE = BEARER
BEARER_TOKEN = '<bearer_token>'
SigV4
restAuthenticationParams (for SigV4) ::=
TYPE = SIGV4
SIGV4_IAM_ROLE = '<iam_role_arn>'
[ SIGV4_SIGNING_REGION = '<region>' ]
[ SIGV4_EXTERNAL_ID = '<external_id>' ]
매개 변수¶
name
카탈로그 통합에 대한 식별자(이름)를 지정하는 문자열로, 계정에서 고유해야 합니다.
또한, 식별자는 알파벳 문자로 시작해야 하며 전체 식별자 문자열을 큰따옴표(예:
"My object"
)로 묶지 않는 한 공백이나 특수 문자를 포함할 수 없습니다. 큰따옴표로 묶인 식별자도 대/소문자를 구분합니다.자세한 내용은 식별자 요구 사항 섹션을 참조하십시오.
CATALOG_SOURCE = ICEBERG_REST
카탈로그 원본이 Apache Iceberg REST 사양을 준수하는 REST 카탈로그임을 지정합니다.
TABLE_FORMAT = ICEBERG
ICEBERG를 카탈로그에서 제공하는 테이블 형식으로 지정합니다.
CATALOG_NAMESPACE = 'namespace'
외부 카탈로그의 네임스페이스를 지정합니다. Snowflake는 이 카탈로그 통합과 연관된 모든 Iceberg 테이블에 이 네임스페이스를 사용합니다.
CREATE ICEBERG TABLE(Iceberg REST 카탈로그) 에 대한 CATALOG_NAMESPACE 매개 변수를 사용하여 테이블 수준에서 네임스페이스를 지정하여 이 값을 재정의할 수 있습니다.
ENABLED = { TRUE | FALSE }
Iceberg 테이블에 카탈로그 통합을 사용할 수 있는지 여부를 지정합니다.
TRUE
로 지정하면 사용자가 이 통합을 참조하는 새 Iceberg 테이블을 만들 수 있습니다.FALSE
로 지정하면 사용자가 이 통합을 참조하는 새 Iceberg 테이블을 만들지 못하게 됩니다.
REFRESH_INTERVAL_SECONDS = value
Snowflake가 자동 새로 고침 의 메타데이터 업데이트를 위해 외부 Iceberg 카탈로그를 폴링하는 시도 사이에 대기하는 시간(초)을 지정합니다.
값: 30~86400(포함)
기본값: 30초
COMMENT = 'string_literal'
통합에 대한 설명을 지정하는 문자열(리터럴)입니다.
기본값: 값 없음
REST 구성 매개 변수(restConfigParams)¶
CATALOG_URI = 'rest_api_endpoint_url'
카탈로그 REST API의 엔드포인트 URL입니다. AWS Glue REST 의 경우 AWS Glue Iceberg REST 카탈로그에 대한 서비스 엔드포인트 를 지정합니다.
PREFIX
선택적으로 모든 API 경로에 추가할 접두사를 지정합니다.
CATALOG_API_TYPE = { PUBLIC | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY | AWS_GLUE }
카탈로그 API 에 대한 연결 유형을 지정합니다. SigV4 인증에 필수이며, 그렇지 않으면 이 매개 변수는 선택 사항입니다.
PUBLIC
은 공개적으로 액세스할 수 있고 Amazon API 게이트웨이를 사용하여 관리되지 않는 API 를 지정하며, SigV4 APIs 가 아닌 경우 사용됩니다.AWS_API_GATEWAY
Amazon API 게이트웨이를 사용하여 관리되는 공개 API 를 지정합니다.AWS_PRIVATE_API_GATEWAY
Amazon API 게이트웨이를 사용하여 관리되는 비공개 API 를 지정합니다.AWS_GLUE
AWS Glue REST 카탈로그를 지정합니다. 이 선택 사항을 사용하면WAREHOUSE
에 대한 값도 지정해야 합니다.
기본값:
PUBLIC
WAREHOUSE
원격 카탈로그 서비스에서 요청할 웨어하우스 위치(카탈로그) 또는 식별자를 지정합니다.
CATALOG_API_TYPE = AWS_GLUE
를 사용하는 경우 이 매개 변수에 AWS 계정의 ID 를 지정합니다.이 매개 변수는 일부 서드 파티 카탈로그 서비스에 필수입니다. 웨어하우스를 지정해야 하는지 여부는 카탈로그 공급업체에 문의하십시오.
REST 인증 매개 변수(restAuthenticationParams)¶
OAuth
TYPE = OAUTH
Snowflake가 Iceberg REST 카탈로그에 연결하는 데 사용할 인증 유형으로 OAuth를 지정합니다.
OAUTH_TOKEN_URI = token_server_uri
서드 파티 ID 공급자를 위한 선택적 URL입니다. 지정하지 않을 경우 Snowflake는 원격 카탈로그 공급자가 OAuth ID 공급자인 것으로 가정합니다.
OAUTH_CLIENT_ID = oauth_client_id
OAuth2 클라이언트 ID입니다.
OAUTH_CLIENT_SECRET = oauth_client_secret
OAuth2 클라이언트 시크릿입니다.
OAUTH_ALLOWED_SCOPES = ( 'scope_1', 'scope_2' )
OAuth 토큰의 범위입니다. Iceberg REST API 사양은 범위를 하나만 포함하지만, 카탈로그는 구현 시 두 개 이상의 범위를 지원할 수 있습니다.
전달자 토큰
TYPE = BEARER
Snowflake가 Iceberg REST 카탈로그에 연결하는 데 사용할 인증 유형으로 전달자 토큰을 지정합니다.
BEARER_TOKEN = bearer_token
ID 공급자를 위한 전달자 토큰입니다. 또는 개인 액세스 토큰(PAT)을 지정할 수 있습니다.
SigV4
TYPE = SIGV4
Snowflake가 Iceberg REST 카탈로그에 연결하는 데 사용할 인증 유형으로 Signature Version 4를 지정합니다.
SIGV4_IAM_ROLE = 'iam_role_arn'
API Gateway에서 REST API에 액세스할 권한이 있는 IAM 역할에 대한 ARN(Amazon Resource Name)을 지정합니다.
SIGV4_SIGNING_REGION = 'region'
선택적으로 API Gateway의 API와 연결된 AWS Region을 지정합니다. 이 매개 변수를 지정하지 않을 경우 Snowflake는 Snowflake 계정이 배포된 리전을 사용합니다.
SIGV4_EXTERNAL_ID = 'external_id'
선택적으로, Snowflake가 AWS와의 신뢰 관계를 설정하는 데 사용하는 외부 ID를 지정합니다. 이 카탈로그 통합을 위해 구성한 IAM 역할의 신뢰 정책에 동일한 외부 ID 를 지정해야 합니다.
이 매개 변수의 값을 지정하지 않으면 카탈로그 통합을 생성(또는 교체)할 때 Snowflake가 고유한 외부 ID 를 자동으로 생성합니다.
외부 IDs 에 대한 자세한 내용은 서드 파티에 AWS 리소스에 대한 액세스 권한을 부여하는 경우 외부 ID 를 사용하는 방법 을 참조하십시오.
액세스 제어 요구 사항¶
이 작업을 실행하는 데 사용되는 역할 에는 최소한 다음 권한 이 있어야 합니다.
권한 |
오브젝트 |
참고 |
---|---|---|
CREATE INTEGRATION |
계정 |
Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed. |
지정된 권한 세트로 사용자 지정 역할을 만드는 방법에 대한 지침은 사용자 지정 역할 만들기 섹션을 참조하십시오.
보안 오브젝트 에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여에 대한 일반적인 정보는 액세스 제어의 개요 섹션을 참조하십시오.
사용법 노트¶
카탈로그 통합은 외부 Iceberg 카탈로그에 대한 읽기 전용 액세스 권한을 제공합니다.
기존 카탈로그 통합은 수정할 수 없으며, 대신 CREATE OR REPLACE CATALOG INTEGRATION 문을 사용하십시오.
하나 이상의 Apache Iceberg™ 테이블이 카탈로그 통합에 연결되어 있는 경우 카탈로그 통합을 삭제하거나 교체할 수 없습니다.
카탈로그 통합에 종속된 테이블을 보려면 SHOW ICEBERG TABLES 명령과
catalog_name
열을 필터링하는 RESULT_SCAN 을 사용한 쿼리를 사용할 수 있습니다.참고
열 식별자(
catalog_name
)는 대/소문자를 구분합니다. SHOW ICEBERG TABLES 출력에 표시되는 열 식별자를 정확하게 지정합니다.예:
SHOW ICEBERG TABLES; SELECT * FROM TABLE( RESULT_SCAN( LAST_QUERY_ID() ) ) WHERE "catalog_name" = 'my_catalog_integration_1';
메타데이터 관련:
주의
고객은 Snowflake 서비스를 사용할 때 개인 데이터(사용자 오브젝트 제외), 민감한 데이터, 수출 통제 대상 데이터 또는 기타 규제 데이터가 메타데이터로 입력되지 않도록 해야 합니다. 자세한 내용은 Snowflake의 메타데이터 필드 섹션을 참조하십시오.
CREATE OR REPLACE <오브젝트> 문은 원자성입니다. 즉, 오브젝트가 바뀔 때 단일 트랜잭션으로 이전 오브젝트가 삭제되고 새 오브젝트가 생성됩니다.
예¶
다음 예에서는 OAuth를 사용하여 Tabular에 연결하는 REST 카탈로그 통합을 만듭니다. CATALOG_NAMESPACE
매개 변수를 사용하여 기본 네임스페이스를 설정합니다.
테이블 수준에서 기본 네임스페이스를 재정의하려면 CREATE ICEBERG TABLE 에 CATALOG_NAMESPACE 매개 변수를 사용합니다.
CREATE OR REPLACE CATALOG INTEGRATION tabular_catalog_int
CATALOG_SOURCE = ICEBERG_REST
TABLE_FORMAT = ICEBERG
CATALOG_NAMESPACE = 'default'
REST_CONFIG = (
CATALOG_URI = 'https://api.tabular.io/ws'
WAREHOUSE = '<tabular_warehouse_name>'
)
REST_AUTHENTICATION = (
TYPE = OAUTH
OAUTH_TOKEN_URI = 'https://api.tabular.io/ws/v1/oauth/tokens'
OAUTH_CLIENT_ID = '<oauth_client_id>'
OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
OAUTH_ALLOWED_SCOPES = ('catalog')
)
ENABLED = TRUE;
SigV4 인증을 사용하여 AWS Glue REST 에 대한 카탈로그 통합을 생성합니다.
CREATE CATALOG INTEGRATION glue_rest_catalog_int
CATALOG_SOURCE = ICEBERG_REST
TABLE_FORMAT = ICEBERG
CATALOG_NAMESPACE = 'rest_catalog_integration'
REST_CONFIG = (
CATALOG_URI = 'https://glue.us-west-2.amazonaws.com/iceberg'
CATALOG_API_TYPE = AWS_GLUE
WAREHOUSE = '123456789012'
)
REST_AUTHENTICATION = (
TYPE = SIGV4
SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my-role'
SIGV4_SIGNING_REGION = 'us-west-2'
)
ENABLED = TRUE;
다른 인증 옵션에 대한 예제는 Apache Iceberg™ REST 카탈로그에 대한 카탈로그 통합 구성 섹션을 참조하십시오.