CREATE EXTERNAL FUNCTION

CREATE EXTERNAL FUNCTION

원격 서비스를 호출하는 외부 함수(external function)를 만들거나, 원격 서비스에 대해 하나 이상의 외부 함수를 일괄 생성/교체하는 명령이에요. 외부 함수는 Snowflake 외부에서 실행되는 코드를 SQL에서 호출할 수 있게 해줘요.

출처: 문서

본문

외부 함수를 만든 다음에는 함수를 사용하기 위해 해당 함수에 대한 USAGE 권한을 부여해야 해요. 외부 함수를 만드는 방법과 원격 서비스를 호출하는 방법에 대한 자세한 내용은 외부 함수 관련 문서를 참조하세요.

이 명령은 다음 변형(variant)을 지원해요:

  • CREATE EXTERNAL FUNCTION: 원격 서비스에 대한 새 외부 함수를 만듭니다.
  • CREATE OR ALTER EXTERNAL FUNCTION: 외부 함수가 없으면 만들고, 있으면 수정합니다.
  • CREATE EXTERNAL FUNCTION ... AS (api_integration => ...): 단일 API 인티그레이션으로 구성된 원격 서비스를 참조하는 여러 외부 함수를 만듭니다.

구문 (Syntax)

CREATE [ OR REPLACE ] EXTERNAL FUNCTION <name> ( [ <arg_name> <arg_type> [ , ... ] ] )
  RETURNS <result_type>
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ]
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { CALLER | OWNER } ]
  AS '<url>'
  [ API_INTEGRATION = '<api_integration_name>' ]
  [ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]
  [ MAX_BATCH_SIZE = <integer> ]
  [ COMPRESSION = { AUTO | GZIP | NONE } ]
  [ REQUEST_TRANSLATOR = <request_translator_udf_name> ]
  [ RESPONSE_TRANSLATOR = <response_translator_udf_name> ]
  [ CONTEXT_HEADERS = ( '<header_1>' [ , '<header_2>' ... ] ) ]

CREATE OR ALTER EXTERNAL FUNCTION

CREATE OR ALTER EXTERNAL FUNCTION <name> ( [ <arg_name> <arg_type> [ , ... ] ] )
  RETURNS <result_type>
  ...
  AS '<url>'
  ...

일괄 생성 (Batch create)

CREATE EXTERNAL FUNCTION ... AS (api_integration => <api_integration_name>)

필수 매개변수

  • <name>: 외부 함수의 식별자예요.
  • <arg_name> <arg_type>: 함수에 입력되는 인자와 데이터 타입을 지정해요.
  • RETURNS <result_type>: 함수가 반환하는 데이터 타입을 지정해요.
  • AS '<url>': 외부 함수가 호출하는 원격 서비스의 HTTPS URL을 지정해요.
  • API_INTEGRATION = '<api_integration_name>': 원격 서비스를 호출할 때 Snowflake가 인증에 사용하는 API 인티그레이션을 지정해요.

선택 매개변수

  • CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT: null 입력 처리 방식을 지정해요.
  • VOLATILE | IMMUTABLE: 함수의 결정적(deterministic) 여부를 지정해요.
  • COMMENT = 'string': 함수에 대한 주석을 추가해요.
  • EXECUTE AS { CALLER | OWNER }: 함수 실행 권한 기준을 지정해요.
  • HEADERS: 원격 서비스로 전달할 추가 헤더를 지정해요.
  • MAX_BATCH_SIZE: 원격 서비스로 보낼 행 배치의 최대 크기를 지정해요.
  • COMPRESSION: 요청 데이터의 압축 방식을 지정해요.
  • REQUEST_TRANSLATOR: 요청 payload를 변환하는 UDF를 지정해요.
  • RESPONSE_TRANSLATOR: 응답 payload를 변환하는 UDF를 지정해요.
  • CONTEXT_HEADERS: 원격 서비스로 전달할 Snowflake 컨텍스트 헤더를 지정해요.

접근 제어 요구 사항

외부 함수를 만들려면 CREATE EXTERNAL FUNCTION 이상 권한과, 외부 함수가 호출하는 API 인티그레이션에 대한 USAGE 권한이 필요해요. 또한 무료로 사용 가능한 외부 함수의 OWNERSHIP 권한이 필요해요.

사용법 참고 사항

  • 외부 함수 이름은 대/소문자를 구분하지 않지만, 데이터 타입과 인자 수에 따라 오버로드(중복 정의)가 가능해요.
  • 외부 함수가 일괄 처리되는 경우 Snowflake는 여러 행을 모아 원격 서비스에 전송해요.
  • 외부 함수는 원격 서비스의 응답 형식(JSON 등)에 따라 변환기가 필요할 수 있어요.
  • 원격 서비스는 인증을 위해 API 인티그레이션과 필수 헤더를 요구할 수 있어요.

예제 (Examples)

원격 서비스를 호출하는 기본 외부 함수를 만들어요:

CREATE OR REPLACE EXTERNAL FUNCTION my_external_function (x NUMBER)
  RETURNS NUMBER
  API_INTEGRATION = my_api_integration
  AS 'https://my-api.example.com/function';

더 알아보기 (Learn more)