SYSTEM$EXECUTE_CATALOG_OPERATION

SYSTEM$EXECUTE_CATALOG_OPERATION

카탈로그 통합(catalog integration)에 대해 카탈로그 작업을 실행해서 통합이 연결하는 원격 카탈로그를 검사하고 검증할 수 있게 해줘요.

이 함수를 사용해 연결 상태를 확인하고, 네임스페이스나 테이블을 나열하고, 최신 테이블 메타데이터 파일 위치를 가져오고, 범위 지정 자격 증명을 검색할 수 있는지 확인해요. 지원되는 작업은 카탈로그 유형과 카탈로그 통합의 기능(예: Iceberg REST, Glue, Polaris, SAP BDC)에 따라 달라져요.

help 작업과 함께 함수를 호출하면 계정에서 사용할 수 있는 작업과 각 작업이 받는 위치 인자(positional argument) 목록을 볼 수 있어요.

출처: Snowflake SYSTEM$EXECUTE_CATALOG_OPERATION 함수 문서

본문

참고 항목: SYSTEM$VERIFY_CATALOG_INTEGRATION, SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG, SYSTEM$LIST_NAMESPACES_FROM_CATALOG, CREATE CATALOG INTEGRATION (Apache Iceberg™ REST), Apache Iceberg™ REST 카탈로그용 카탈로그 통합 구성

구문 (Syntax)

SYSTEM$EXECUTE_CATALOG_OPERATION( '<catalog_integration_name>' , '<operation_name>'
  [ , '<arg1>' [ , '<arg2>' [ , '<arg3>' ] ] ] )

인자 (Arguments)

필수 (Required):

  • catalog_integration_name — 작업을 수행할 카탈로그 통합의 이름이에요. 이름은 현재 계정에서 확인돼요. 카탈로그 통합 이름은 대소문자를 구분해요.
  • operation_name — 실행할 작업의 이름이에요. 작업 이름은 대소문자를 구분하지 않아요. 작업과 해당 인자 목록은 지원되는 작업을 참고하거나 'help'와 함께 함수를 호출해요.

선택 (Optional):

  • arg1, arg2, arg3 — 작업의 위치 인자예요. 각 인자의 의미는 작업에 따라 달라져요. 사용하지 않는 후행 인자는 생략해요. 작업이 네임스페이스나 카탈로그 이름 인자를 받고 이를 생략하면, 사용 가능할 때 Snowflake는 카탈로그 통합에 구성된 기본 네임스페이스나 카탈로그 이름을 사용해요.

반환 값 (Returns)

작업에 대한 문자열 결과를 반환해요.

  • 대부분의 작업은 JSON 형식의 문자열이에요.
  • help는 사용 가능한 작업과 해당 인자를 나열하는 형식화된 테이블이에요.
  • verify는 검증 메시지 문자열이에요(카탈로그 유형에서 검증이 지원되지 않으면 JSON 상태 객체).

지원되는 작업 (Supported Operations)

다음 작업을 사용할 수 있어요. 모든 카탈로그 통합이 모든 작업을 지원하는 것은 아니에요. 지원되지 않는 작업을 호출하면 함수는 카탈로그 통합과 클라이언트 유형을 명명하는 오류를 반환해요.

작업 arg1 arg2 arg3 설명
listTables namespace (선택) catalogName (선택) 해당 없음 네임스페이스의 테이블을 나열해요.
listNamespaces namespace (선택) catalogName (선택) 해당 없음 상위 네임스페이스 아래의 네임스페이스를 나열해요.
loadTable catalogTableNamespace (선택) catalogTableName (필수) catalogName (선택) 테이블의 최신 메타데이터 파일 위치를 반환해요.
getVendedCredentials catalogTableNamespace (선택) catalogTableName (필수) catalogName (선택) 테이블에 대해 범위 지정 액세스 자격 증명을 검색할 수 있는지 확인해요. 상태 메시지를 반환하며 자격 증명 값은 반환하지 않아요.
loadCredentials catalogTableNamespace (선택) catalogTableName (필수) catalogName (선택) Iceberg REST loadCredentials API를 사용해 범위 지정 액세스 자격 증명을 검색할 수 있는지 확인해요. 특정 카탈로그 공급업체(현재 Microsoft OneLake)에서 지원돼요. 상태 메시지를 반환하며 자격 증명 값은 반환하지 않아요.
listShares catalogName (선택) 해당 없음 해당 없음 해당 기능을 노출하는 카탈로그 유형에 대해 사용 가능한 카탈로그(공유)를 나열해요.
listCatalogs catalogName (선택) 해당 없음 해당 없음 사용 가능한 카탈로그를 나열해요. catalogName을 지정하면 결과가 해당 카탈로그 이름으로 필터링돼요(대소문자 무시).
verify 해당 없음 해당 없음 해당 없음 카탈로그 통합 구성과 연결 상태를 검증해요.
help 해당 없음 해당 없음 해당 없음 작업과 인자의 도움말 목록을 반환해요.

반환 세부 정보 (Return Details)

listTables — 지정된 네임스페이스의 테이블 식별자 JSON 배열을 반환해요.

listNamespaces — 지정된 상위 네임스페이스 아래의 네임스페이스 식별자 JSON 배열을 반환해요.

loadTable — 다음 속성을 가진 JSON 객체를 반환해요.

속성 설명
metadataFile 테이블의 최신 메타데이터 파일 위치예요. 
{
  "metadataFile": "s3://my_bucket/path/to/table/metadata/00001-abc.metadata.json"
}

getVendedCredentials 및 loadCredentials — status 속성을 가진 JSON 객체를 반환해요. 이 함수는 자격 증명을 검색할 수 있음을 확인하며 자격 증명 값은 반환하지 않아요.

{
  "status": "Credentials retrieved successfully"
}

listShares 및 listCatalogs — 카탈로그 이름의 JSON 배열을 반환해요.

verify — 카탈로그 통합 구성이 유효한지 여부를 설명하는 검증 메시지를 반환해요. 검증을 지원하지 않는 카탈로그 유형의 경우 다음을 반환해요.

{
  "status": "Verification not supported for this catalog type"
}

접근 제어 요구 사항 (Access Control Requirements)

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

권한 객체 참고
USAGE 카탈로그 통합 함수 호출에서 이름이 지정된 카탈로그 통합에 필요해요.

지정된 권한 집합을 가진 사용자 지정 역할을 만드는 방법은 사용자 지정 역할 만들기를 참고하세요. 보호 객체에 대한 SQL 작업으로 역할과 권한 부여에 대한 일반 정보는 액세스 제어 개요를 참고하세요.

사용 참고 (Usage Notes)

  • 작업 이름은 대소문자를 구분하지 않아요. 카탈로그 통합 이름은 대소문자를 구분해요.
  • 네임스페이스 인자는 단일 네임스페이스 수준으로 처리돼요. 더 깊은 계층의 경우 카탈로그 유형에 맞을 때 전용 SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG 및 SYSTEM$LIST_NAMESPACES_FROM_CATALOG 함수를 사용하세요.
  • 클라이언트 수준 실패(예: 네트워크 오류 또는 카탈로그 인증 실패)는 JSON 오류 페이로드가 아니라 SQL 오류로 표시돼요.
  • getVendedCredentials와 loadCredentials는 성공 또는 실패 상태만 반환해요. 쿼리 결과에 임시 자격 증명 값을 노출하지 않아요.
  • loadCredentials는 Iceberg REST loadCredentials API를 지원하는 카탈로그 공급업체에서만 사용할 수 있어요. 지원되지 않는 공급업체에 대한 호출은 오류를 반환해요.

예제 (Examples)

카탈로그 통합에서 사용할 수 있는 작업을 나열해요:

SELECT SYSTEM$EXECUTE_CATALOG_OPERATION('my_catalog_integration', 'help');

카탈로그 통합의 연결 상태를 확인해요:

SELECT SYSTEM$EXECUTE_CATALOG_OPERATION('my_catalog_integration', 'verify');

기본 카탈로그 네임스페이스의 테이블을 나열해요:

SELECT SYSTEM$EXECUTE_CATALOG_OPERATION('my_catalog_integration', 'listTables');

db1 네임스페이스 아래의 테이블을 나열해요:

SELECT SYSTEM$EXECUTE_CATALOG_OPERATION('my_catalog_integration', 'listTables', 'db1');

db1 아래의 하위 네임스페이스를 나열해요:

SELECT SYSTEM$EXECUTE_CATALOG_OPERATION('my_catalog_integration', 'listNamespaces', 'db1');

네임스페이스 db1의 테이블 t1에 대한 최신 메타데이터 파일 위치를 가져와요:

SELECT SYSTEM$EXECUTE_CATALOG_OPERATION(
  'my_catalog_integration',
  'loadTable',
  'db1',
  't1'
);

테이블에 대해 범위 지정 자격 증명을 검색할 수 있는지 확인해요:

SELECT SYSTEM$EXECUTE_CATALOG_OPERATION(
  'my_catalog_integration',
  'getVendedCredentials',
  'db1',
  't1'
);

더 알아보기