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>;
필수 매개 변수¶
name
:함수의 식별자를 지정합니다.
이 식별자에는 함수 이름뿐 아니라 스키마 이름과 데이터베이스 이름도 포함될 수 있습니다.
함수는 그 이름과 인자 유형으로 식별과 확인이 이루어지므로 함수가 생성되는 스키마에 대해 고유한 식별자일 필요는 없습니다. 하지만 스키마 내에서 서명(이름 및 인자 데이터 타입)은 고유해야 합니다.
name
은 Snowflake 식별자 에 대한 규칙을 따라야 합니다. 자세한 내용은 식별자 요구 사항 섹션을 참조하십시오.name
을 원격 서비스 이름과 똑같이 설정하면 관계를 더 명확하게 할 수 있습니다. 하지만 이것이 필수적인 것은 아닙니다.( [ arg_name arg_data_type ] [ , ... ] )
외부 함수의 인자/입력값을 지정합니다. 이는 원격 서비스가 예상하는 인자와 일치해야 합니다.
인자가 없으면 인자 이름과 데이터 타입 없이 괄호를 포함하십시오.
RETURNS result_data_type
함수가 반환하는 데이터 타입을 지정합니다.
API_INTEGRATION = api_integration_name
이것은 프록시 서비스 호출의 인증에 사용해야 하는 API 통합 오브젝트의 이름입니다.
AS 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' )
이로 인해 Snowflake는 모든 HTTPS 요청에 2개의 HTTP 헤더
sf-custom-volume-measure
와sf-custom-distance-measure
를 해당 값과 함께 추가합니다.헤더 이름에 대한 규칙은 Snowflake 데이터베이스 식별자에 대한 규칙과 다릅니다. 헤더 이름은 다음을 제외하고 가장 많이 볼 수 있는 표준 ASCII 문자(십진수 32 - 126)로 구성할 수 있습니다.
공백 문자
(
)
,
/
:
;
<
>
=
"
?
@
[
]
\
{
}
_
특히 헤더 이름에는 밑줄 문자를 쓸 수 없다는 점에 유의하십시오.
헤더 이름과 값은 작은따옴표로 구분되므로, 헤더 이름 또는 값 내의 작은따옴표는 모두 백슬래시 문자로 이스케이프해야 합니다.
백슬래시 문자가 헤더 값 내에서 리터럴 문자로 사용되는 경우 이 문자를 이스케이프해야 합니다.
헤더 값에는 공백과 탭이 모두 허용되지만, 헤더 값은 한 행에 공백 문자를 두 개 이상 포함하면 안 됩니다. 이 제한은 개별 공백 문자(예: 연속으로 두 개의 공백)뿐 아니라 공백 문자의 조합(예: 공백 다음의 탭)에도 적용됩니다.
함수 작성자가 (
CREATE SECURE EXTERNAL FUNCTION...
을 사용하여) 함수를 보안으로 표시하면 헤더, 컨텍스트 헤더, 이진 컨텍스트 헤더, URL은 함수 사용자에게 표시되지 않습니다.외부 함수에 대한 헤더 이름의 크기와 헤더 값의 합이 8KB보다 작거나 같아야 합니다.
CONTEXT_HEADERS = ( context_function_1 [ , context_function_2 ...] )
이는 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)
이 예에서, Snowflake는 헤더
sf-context-current-timestamp
를 HTTP 요청에 씁니다.컨텍스트 헤더 이름과 값에 허용되는 문자는 사용자 지정 헤더 이름과 값 에 허용되는 문자와 같습니다.
컨텍스트 함수는 다음을 포함하되 이에 국한되지 않는 HTTP 헤더 값에서 잘못된 문자를 생성할 수 있습니다.
줄 바꿈
Ä
Î
ß
ë
¬
±
©
®
Snowflake는 하나 이상의 잘못된 문자로 구성된 각 시퀀스를 하나의 공백 문자로 바꿉니다. (문자가 아니라 시퀀스 단위로 바뀝니다.)
예를 들어, 컨텍스트 함수 CURRENT_STATEMENT()가 다음을 반환한다고 가정해 보십시오.
select /*ÄÎß묱©®*/ my_external_function(1);
sf-context-current-statement
에서 보낸 값은 다음과 같습니다.select /* */ my_external_function(1);
잘못된 문자를 바꾼 경우에도 원격 서비스가 컨텍스트 함수의 원래 결과(잘못된 문자 포함)에 확실히 액세스할 수 있도록, Snowflake는 base64 로 인코딩된 컨텍스트 함수 결과를 포함한 이진 컨텍스트 헤더도 보냅니다.
위의 예에서, base64 헤더로 전송된 값은 다음을 호출한 결과입니다.
base64_encode('select\n/ÄÎß묱©®/\nmy_external_function(1)')
원격 서비스는 필요한 경우 base64 값의 디코딩을 담당합니다.
이러한 각 base64 헤더는 다음 규칙에 따라 명명됩니다.
sf-context-<context-function>-base64
위의 예에서 헤더의 이름은 다음이 됩니다.
sf-context-current-statement-base64
컨텍스트 헤더가 전송되지 않으면 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';
이 예에서:
local_echo
는 SQL 문에서 호출된 이름입니다(예:SELECT local_echo(varchar_column) ...;
을 실행할 수 있음).string_col VARCHAR
은 입력 매개 변수의 이름과 데이터 타입을 포함합니다. 외부 함수에는 0개 또는 그 이상의 입력 매개 변수가 있을 수 있습니다.variant
는 외부 함수에서 반환된 값의 데이터 타입입니다.이름
demonstration_external_api_integration_01
은 CREATE API INTEGRATION 문의 앞부분에서 생성된 API 통합의 이름입니다.URL
https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo
는 프록시 서비스와 리소스를 식별하는 문자열입니다. HTTP POST 명령은 이 URL로 전송됩니다.