CREATE EXTERNAL FUNCTION¶

새 외부 함수 를 만듭니다.

참고 항목:: ALTER FUNCTION , SHOW EXTERNAL FUNCTIONS , DROP FUNCTION , DESCRIBE FUNCTION , CREATE API INTEGRATION

구문¶

CREATE [ OR REPLACE ] [ SECURE ] EXTERNAL FUNCTION <name> ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ VOLATILE | IMMUTABLE ]
  [ COMMENT = '<string_literal>' ]
  API_INTEGRATION = <api_integration_name>
  [ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  [ COMPRESSION = <compression_type> ]
  [ REQUEST_TRANSLATOR = <request_translator_udf_name> ]
  [ RESPONSE_TRANSLATOR = <response_translator_udf_name> ]
  AS <url_of_proxy_and_resource>;

Copy

필수 매개 변수¶

name:

함수의 식별자를 지정합니다.

이 식별자에는 함수 이름뿐 아니라 스키마 이름과 데이터베이스 이름도 포함될 수 있습니다.

함수는 그 이름과 인자 유형으로 식별과 확인이 이루어지므로 함수가 생성되는 스키마에 대해 고유한 식별자일 필요는 없습니다. 하지만 스키마 내에서 서명(이름 및 인자 데이터 타입)은 고유해야 합니다.

name 은 Snowflake 식별자 에 대한 규칙을 따라야 합니다. 자세한 내용은 식별자 요구 사항 섹션을 참조하십시오.

name 을 원격 서비스 이름과 똑같이 설정하면 관계를 더 명확하게 할 수 있습니다. 하지만 이것이 필수적인 것은 아닙니다.

( [ arg_name arg_data_type ] [ , ... ] )

외부 함수의 인자/입력값을 지정합니다. 이는 원격 서비스가 예상하는 인자와 일치해야 합니다.

인자가 없으면 인자 이름과 데이터 타입 없이 괄호를 포함하십시오.

RETURNS ...

함수가 반환하는 데이터 타입을 지정합니다.

api_integration_name

이것은 프록시 서비스 호출의 인증에 사용해야 하는 API 통합 오브젝트의 이름입니다.

url_of_proxy_and_resource

이것은 Snowflake가 원격 서비스(예: API Gateway 또는 API Management 서비스)를 호출하는 수단이 되는 프록시 서비스와 리소스의 호출 URL입니다.

선택적 매개 변수¶

SECURE

함수가 안전한 것으로 지정합니다. 함수가 안전한 경우 URL, HTTP 헤더 및 컨텍스트 헤더는 함수의 소유자가 아닌 모든 사용자로부터 숨겨집니다.

[ [ NOT ] NULL ]

이 절은 함수가 NULL 값을 반환할 수 있거나 NON-NULL 값만 반환해야 할지 여부를 나타냅니다. NOT NULL 을 지정한 경우 이 함수는 NULL이 아닌 값만 반환해야 합니다. NULL 을 지정한 경우 이 함수는 NULL 값을 반환할 수 있습니다.

기본값: 기본값은 NULL입니다(즉, 이 함수는 NULL 값을 반환할 수 있음).

CALLED ON NULL INPUT 또는 . RETURNS NULL ON NULL INPUT | STRICT

null 입력으로 호출 시 함수의 동작을 지정합니다. 입력값이 null일 때 항상 null을 반환하는 시스템 정의 함수와는 반대로, 외부 함수는 null 입력을 처리하여 입력값이 null일 때도 null이 아닌 값을 반환할 수 있습니다.

CALLED ON NULL INPUT 은 항상 null 입력으로 함수를 호출합니다. 그와 같은 값을 적절히 처리하는 것은 이 함수에 달려 있습니다.

입력값이 null인 경우 RETURNS NULL ON NULL INPUT (또는 그 동의어인 STRICT)은 함수를 호출하지 않습니다. 대신, 해당 행에 대해 항상 null 값이 반환됩니다. 이 함수는 null이 아닌 입력값에 대해 여전히 null을 반환할 수도 있습니다.

기본값: CALLED ON NULL INPUT

VOLATILE | IMMUTABLE

결과를 반환할 때 함수의 동작을 지정합니다.

VOLATILE: (예: 비결정성 및 상태 저장으로 인해) 이 함수는 똑같은 입력에 대해서도 다른 행에 대해 다른 값을 반환할 수 있습니다.

IMMUTABLE: 이 함수는 똑같은 입력으로 호출 시 항상 같은 결과를 반환합니다. Snowflake는 이를 확인하거나 보증하지 않으며, 원격 서비스는 이러한 방식으로 동작하도록 설계해야 합니다. 같은 입력에 대해 실제로 다른 값을 반환하는 함수에 대해 IMMUTABLE 을 지정하면 정의되지 않은 동작이 이루어집니다.

기본값: VOLATILE

Snowflake에서는 기본값을 수락하는 대신 이 값을 명시적으로 설정할 것을 권장합니다. 이 값을 명시적으로 설정하면 오류 가능성이 줄어들고 사용자에게 함수의 동작 방식을 알려줄 수 있습니다. (SHOW EXTERNAL FUNCTIONS 명령은 함수가 휘발성인지 변경할 수 없는지 여부를 보여줍니다.)

VOLATILE 및 IMMUTABLE 외부 함수에 대한 중요한 추가 정보는 함수를 휘발성 또는 변경 불가능으로 분류하기 섹션을 참조하십시오.

COMMENT = 'string_literal'

SHOW FUNCTIONS 및 SHOW EXTERNAL FUNCTIONS 출력의 DESCRIPTION 열에 표시되는 함수에 대한 설명을 지정합니다.

기본값: user-defined function

[ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]

사용자는 이 절을 통해 모든 요청과 함께 전송되는 키-값 메타데이터를 지정할 수 있습니다. 외부 함수 작성자는 헤더에 들어갈 내용을 결정하며 호출자는 이에 대한 제어 권한이 없습니다. Snowflake는 지정된 모든 헤더 이름 앞에 접두사 《sf-custom-《를 추가하여 HTTP 헤더로 보냅니다.

이 값은 식이 아닌 상수 문자열이어야 합니다.

한 예를 들면 다음과 같습니다.

headers = (
    'volume-measure' = 'liters',
    'distance-measure' = 'kilometers'
)

Copy

이로 인해 Snowflake는 모든 HTTPS 요청에 2개의 HTTP 헤더 sf-custom-volume-measure 와 sf-custom-distance-measure 를 해당 값과 함께 추가합니다.

헤더 이름에 대한 규칙은 Snowflake 데이터베이스 식별자에 대한 규칙과 다릅니다. 헤더 이름은 다음을 제외하고 가장 많이 볼 수 있는 표준 ASCII 문자(십진수 32 - 126)로 구성할 수 있습니다.

공백 문자
(
)
,
/
:
;
<
>
=
"
?
@
[
]
\
{
}
_

특히 헤더 이름에는 밑줄 문자를 쓸 수 없다는 점에 유의하십시오.

헤더 이름과 값은 작은따옴표로 구분되므로, 헤더 이름 또는 값 내의 작은따옴표는 모두 백슬래시 문자로 이스케이프해야 합니다.

백슬래시 문자가 헤더 값 내에서 리터럴 문자로 사용되는 경우 이 문자를 이스케이프해야 합니다.

헤더 값에는 공백과 탭이 모두 허용되지만, 헤더 값은 한 행에 공백 문자를 두 개 이상 포함하면 안 됩니다. 이 제한은 개별 공백 문자(예: 연속으로 두 개의 공백)뿐 아니라 공백 문자의 조합(예: 공백 다음의 탭)에도 적용됩니다.

함수 작성자가 (CREATE SECURE EXTERNAL FUNCTION... 을 사용하여) 함수를 보안으로 표시하면 헤더, 컨텍스트 헤더, 이진 컨텍스트 헤더, URL은 함수 사용자에게 표시되지 않습니다.

외부 함수에 대한 헤더 이름의 크기와 헤더 값의 합이 8KB보다 작거나 같아야 합니다.

CONTEXT_HEADERS ...

이는 headers 와 유사하지만, 상수 문자열을 사용하는 대신 Snowflake 컨텍스트 함수 결과를 HTTP 헤더에 바인딩합니다. (Snowflake 컨텍스트 함수에 대한 자세한 내용은 컨텍스트 함수 를 참조하십시오.)

모든 컨텍스트 함수가 컨텍스트 헤더에서 지원되는 것은 아닙니다. 다음 함수가 지원됩니다.

CURRENT_ACCOUNT()
CURRENT_CLIENT()
CURRENT_DATABASE()
CURRENT_DATE()
CURRENT_IP_ADDRESS()
CURRENT_REGION()
CURRENT_ROLE()
CURRENT_SCHEMA()
CURRENT_SCHEMAS()
CURRENT_SESSION()
CURRENT_STATEMENT()
CURRENT_TIME()
CURRENT_TIMESTAMP()
CURRENT_TRANSACTION()
CURRENT_USER()
CURRENT_VERSION()
CURRENT_WAREHOUSE()
LAST_QUERY_ID()
LAST_TRANSACTION()
LOCALTIME()
LOCALTIMESTAMP()

함수 이름이 CONTEXT_HEADERS ... 절에 나열되어 있을 때는 함수 이름을 따옴표로 묶으면 안 됩니다.

Snowflake는 헤더 앞에 《sf-context》를 추가한 후 HTTP 요청에 이를 씁니다.

예:

context_headers = (current_timestamp)

Copy

이 예에서, Snowflake는 헤더 sf-context-current-timestamp 를 HTTP 요청에 씁니다.

컨텍스트 헤더 이름과 값에 허용되는 문자는 사용자 지정 헤더 이름과 값 에 허용되는 문자와 같습니다.

컨텍스트 함수는 다음을 포함하되 이에 국한되지 않는 HTTP 헤더 값에서 잘못된 문자를 생성할 수 있습니다.

줄 바꿈
Ä
Î
ß
ë
¬
±
©
®

Snowflake는 하나 이상의 잘못된 문자로 구성된 각 시퀀스를 하나의 공백 문자로 바꿉니다. (문자가 아니라 시퀀스 단위로 바뀝니다.)

예를 들어, 컨텍스트 함수 CURRENT_STATEMENT()가 다음을 반환한다고 가정해 보십시오.

select
  /*ÄÎßë¬±©®*/
  my_external_function(1);

Copy

sf-context-current-statement 에서 보낸 값은 다음과 같습니다.

select /* */ my_external_function(1);

Copy

잘못된 문자를 바꾼 경우에도 원격 서비스가 컨텍스트 함수의 원래 결과(잘못된 문자 포함)에 확실히 액세스할 수 있도록, Snowflake는 base64 로 인코딩된 컨텍스트 함수 결과를 포함한 이진 컨텍스트 헤더도 보냅니다.

위의 예에서, base64 헤더로 전송된 값은 다음을 호출한 결과입니다.

base64_encode('select\n/ÄÎßë¬±©®/\nmy_external_function(1)')

Copy

원격 서비스는 필요한 경우 base64 값의 디코딩을 담당합니다.

이러한 각 base64 헤더는 다음 규칙에 따라 명명됩니다.

sf-context-<context-function>-base64

Copy

위의 예에서 헤더의 이름은 다음이 됩니다.

sf-context-current-statement-base64

Copy

컨텍스트 헤더가 전송되지 않으면 base64 컨텍스트 헤더도 전송되지 않습니다.

외부 함수로 보낸 행이 여러 배치로 분할되면 모든 일괄 작업에 똑같은 컨텍스트 헤더와 똑같은 이진 컨텍스트 헤더가 포함됩니다.

MAX_BATCH_ROWS = <integer>

이 매개 변수는 프록시 서비스로 전송되는 각 일괄 작업의 최대 행 수를 지정합니다.

이 매개 변수의 목적은 메모리 제약 또는 기타 제한이 있는 원격 서비스의 일괄 작업 크기를 제한하는 것입니다. 이 매개 변수는 성능 조정 매개 변수가 아닙니다. 이 매개 변수는 권장 크기가 아닌 최대 크기를 지정합니다.

MAX_BATCH_ROWS 를 지정하지 않을 경우 Snowflake는 최적의 일괄 작업 크기를 추정하고 그 크기를 사용합니다.

원격 서비스에 제한이 필요하지 않으면 이 매개 변수를 설정하지 않은 상태로 두는 것이 좋습니다.

COMPRESSION = <compression_type>

이 절을 지정하면 Snowflake에서 프록시 서비스로 보낼 때와 프록시 서비스에서 Snowflake로 다시 보낼 때 JSON 페이로드가 압축됩니다.

유효한 값은 다음과 같습니다.

NONE.
GZIP.
DEFLATE.
AUTO.
- AWS에서는 AUTO 가 GZIP 과 같습니다.
- Azure에서는 AUTO 가 NONE 과 같습니다.
- GCP에서는 AUTO 가 NONE 과 같습니다.

Amazon API Gateway는 요청을 자동으로 압축/압축 해제합니다. Amazon API Gateway 압축 및 압축 해제에 대한 자세한 내용은 https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gzip-compression-decompression.html을 참조하십시오.

다른 클라우드 플랫폼 프록시 서비스의 압축 및 압축 해제에 대한 자세한 내용은 해당 클라우드 플랫폼에 대한 설명서를 참조하십시오.

기본값: 기본값은 AUTO 입니다.

REQUEST_TRANSLATOR = <request_translator_udf_name>

이는 요청 변환기 함수의 이름을 지정합니다. 자세한 내용은 원격 서비스에 대한 데이터와 함께 요청 및 응답 변환기 사용하기 섹션을 참조하십시오.

RESPONSE_TRANSLATOR = <response_translator_udf_name>

이는 응답 변환기 함수의 이름을 지정합니다. 자세한 내용은 원격 서비스에 대한 데이터와 함께 요청 및 응답 변환기 사용하기 섹션을 참조하십시오.

액세스 제어 요구 사항¶

이 SQL 명령을 실행하는 데 사용되는 역할 에는 최소한 다음 권한 이 있어야 합니다.

권한	오브젝트	참고
CREATE EXTERNAL FUNCTION	스키마	Operating on functions also requires the USAGE privilege on the parent database and schema.
:emph:`` OWNERSHIP 또는 USAGE	API 통합	API 통합을 참조하는 외부 함수를 만드는 데 필요합니다.

지정된 권한 세트로 사용자 지정 역할을 만드는 방법에 대한 지침은 사용자 지정 역할 만들기 섹션을 참조하십시오.

보안 오브젝트 에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여에 대한 일반적인 정보는 액세스 제어의 개요 섹션을 참조하십시오.

사용법 노트¶

압축 사용 시, Snowflake는 HTTP 헤더 《Content-Encoding》과 《Accept-Encoding》을 설정합니다.
인자 유형과 반환 유형은 GEOGRAPHY일 수 없습니다.
메타데이터 관련:

주의

고객은 Snowflake 서비스를 사용할 때 개인 데이터(사용자 오브젝트 제외), 민감한 데이터, 수출 통제 대상 데이터 또는 기타 규제 데이터가 메타데이터로 입력되지 않도록 해야 합니다. 자세한 내용은 Snowflake의 메타데이터 필드 섹션을 참조하십시오.
CREATE OR REPLACE <오브젝트> 문은 원자성입니다. 즉, 오브젝트가 바뀔 때 이전 오브젝트 삭제와 새 오브젝트 생성이 단일 트랜잭션으로 처리됩니다.

예¶

다음 예에서는 Amazon API Gateway 프록시 서비스를 통해 호출되는 CREATE EXTERNAL FUNCTION 문을 보여줍니다.

create or replace external function local_echo(string_col VARCHAR)
    returns variant
    api_integration = demonstration_external_api_integration_01
    as 'https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo';
Copy
이 예에서:

local_echo 는 SQL 문에서 호출된 이름입니다. (예: SELECT local_echo(varchar_column) ...; 을 실행할 수 있습니다.)

string_col VARCHAR 은 입력 매개 변수의 이름과 데이터 타입을 포함합니다. 외부 함수에는 0개, 1개 또는 여러 개의 입력 매개 변수가 있을 수 있습니다.

variant 는 외부 함수에서 반환된 값의 데이터 타입입니다.

이름 demonstration_external_api_integration_01 은 CREATE API INTEGRATION 문의 앞부분에서 생성된 API Integration의 이름입니다.

URL 〈https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo’는 프록시 서비스와 리소스를 식별하는 문자열입니다. HTTP POST 명령은 이 URL로 전송됩니다.