CREATE EXTERNAL FUNCTION¶
새 외부 함수 를 만듭니다.
이 명령은 다음 변형을 지원합니다.
CREATE OR ALTER EXTERNAL FUNCTION: 외부 함수가 없는 경우 외부 함수를 생성하거나 기존 외부 함수를 변경합니다.
- 참고 항목:
ALTER FUNCTION , SHOW EXTERNAL FUNCTIONS , DROP FUNCTION , DESCRIBE FUNCTION , CREATE API INTEGRATION, CREATE OR ALTER <오브젝트>
구문¶
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>';
베리언트 구문¶
CREATE OR ALTER EXTERNAL FUNCTION¶
아직 존재하지 않는 외부 함수를 새로 만들거나 기존 외부 함수를 문에 정의된 함수로 변환합니다. CREATE OR ALTER EXTERNAL FUNCTION 문은 CREATE EXTERNAL FUNCTION 문의 구문 규칙을 따르며 ALTER FUNCTION 문과 제한 사항이 동일합니다.
지원되는 함수 변경에는 다음과 같은 변경 사항이 포함됩니다.
API_INTEGRATION
COMMENTS
COMPRESSION
CONTEXT_HEADERS
HEADERS
MAX_BATCH_ROWS
RESPONSE_TRANSLATOR
REQUEST_TRANSLATOR
SECURE
자세한 내용은 CREATE OR ALTER EXTERNAL FUNCTION 사용법 노트 섹션을 참조하십시오.
CREATE [ OR ALTER ] EXTERNAL FUNCTION ...
필수 매개 변수¶
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
이는 응답 변환기 함수의 이름을 지정합니다. 자세한 내용은 원격 서비스에 대한 데이터와 함께 요청 및 응답 변환기 사용하기 섹션을 참조하십시오.
액세스 제어 요구 사항¶
이 작업을 실행하는 데 사용되는 역할 에는 최소한 다음 권한 이 있어야 합니다.
권한 |
오브젝트 |
참고 |
---|---|---|
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 <오브젝트> 문은 원자성입니다. 즉, 오브젝트가 바뀔 때 단일 트랜잭션으로 이전 오브젝트가 삭제되고 새 오브젝트가 생성됩니다.
CREATE OR ALTER EXTERNAL FUNCTION 사용법 노트¶
함수 정의 및 반환 유형에 대한 변경은 지원되지 않습니다.
예¶
Amazon API 게이트웨이 프록시 서비스를 통해 외부 함수 만들기¶
다음 예에서는 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로 전송됩니다.
CREATE OR ALTER EXTERNAL FUNCTION 명령을 사용하여 외부 함수 변경하기¶
위에서 생성한 외부 함수 local_echo
를 변경하여 배치 행의 최대 수를 100으로, 압축을 GZIP 으로 설정하고 헤더와 컨텍스트 헤더를 추가합니다.
CREATE OR ALTER SECURE EXTERNAL FUNCTION local_echo(string_col VARCHAR)
RETURNS VARIANT
API_INTEGRATION = demonstration_external_api_integration_01
HEADERS = ('header_variable1'='header_value', 'header_variable2'='header_value2')
CONTEXT_HEADERS = (current_account)
MAX_BATCH_ROWS = 100
COMPRESSION = "GZIP"
AS 'https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo';