CREATE FUNCTION

CREATE FUNCTION (Snowpark Container Services)

서비스 함수(service function)를 만드는 명령이에요. 서비스 함수는 Snowpark Container Services 서비스의 엔드포인트를 호출하는 사용자 정의 함수예요.

출처: 문서

본문

서비스 함수를 만들어요.

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

CREATE OR ALTER FUNCTION (Snowpark Container Services): 서비스 함수가 없으면 만들고, 있으면 기존 서비스 함수를 수정해요.

함께 보기: 서비스 함수(Service functions), CREATE EXTERNAL FUNCTION, DESC FUNCTION, DROP FUNCTION, ALTER FUNCTION

구문 (Syntax)

CREATE [ OR REPLACE ] 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 } ]
  SERVICE = <service_name>
  ENDPOINT = <endpoint_name>
  [ COMMENT = '<string_literal>' ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , <context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  [ MAX_BATCH_RETRIES = <integer> ]
  [ ON_BATCH_FAILURE = { ABORT | RETURN_NULL } ]
  [ BATCH_TIMEOUT_SECS = <integer> ]
  AS '<http_path_to_request_handler>'

변형 구문 (Variant syntax)

CREATE OR ALTER FUNCTION (Snowpark Container Services)

존재하지 않으면 새 서비스 함수를 만들고, 존재하면 기존 서비스 함수를 문에 정의된 서비스 함수로 변환해요. CREATE OR ALTER FUNCTION (Snowpark Container Services) 문은 CREATE FUNCTION (Snowpark Container Services) 문의 구문 규칙을 따르고, ALTER FUNCTION (Snowpark Container Services) 문과 동일한 제약을 가져요.

지원되는 함수 수정에는 다음 변경이 포함돼요.

CONTEXT_HEADERS
SERVICE
ENDPOINT
MAX_BATCH_ROWS
MAX_BATCH_RETRIES
ON_BATCH_FAILURE
BATCH_TIMEOUT_SECS

자세한 내용은 CREATE OR ALTER FUNCTION (Snowpark Container Services) 사용 메모와 CREATE OR ALTER <object>를 참고해요.

CREATE [ OR ALTER ] FUNCTION ...

필수 매개변수 (Required parameters)

name 함수의 식별자(name)와 입력 인자를 지정해요.

식별자는 함수가 이름과 인자 유형의 조합으로 식별·해석되므로 함수가 만들어지는 스키마 안에서 고유할 필요가 없어요.

식별자는 반드시 알파벳 문자로 시작해야 하며, 전체 식별자 문자열이 큰따옴표로 묶이지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 묶인 식별자는 대소문자를 구분해요. 식별자 요구 사항(Identifier requirements)을 참고해요.

( [ arg_name arg_data_type ] [ , ... ] ) 서비스 함수의 인자/입력을 지정해요. 이들은 서비스가 기대하는 인자에 대응해야 해요.

인자가 없으면 인자 이름과 데이터 유형 없이 괄호만 포함해요.

RETURNS result_data_type 함수가 반환하는 결과의 데이터 유형을 지정해요.

SERVICE = service_name Snowpark Container Services 서비스의 이름을 지정해요.

ENDPOINT = endpoint_name 서비스 사양에 정의된 대로 엔드포인트의 이름을 지정해요.

AS http_path_to_request_handler 함수가 호출될 때 실행되는 서비스 코드의 HTTP 경로를 지정해요.

선택 매개변수 (Optional parameters)

[ [ NOT ] 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 입력으로 함수를 항상 호출해요. 그러한 값을 적절히 처리하는 것은 함수의 몫이에요.
RETURNS NULL ON NULL INPUT(또는 동의어 STRICT)은 어떤 입력이든 null이면 함수를 호출하지 않아요. 대신 그 행에 대해 항상 null 값이 반환돼요. 함수가 비-null 입력에 대해 여전히 null을 반환할 수 있음에 주의해요.
기본값: CALLED ON NULL INPUT

{ VOLATILE | IMMUTABLE } 결과 반환 시 함수의 동작을 지정해요.

VOLATILE: 함수가 같은 입력이라도 행마다 다른 값을 반환할 수 있어요 (예: 비결정성(non-determinism)과 상태성(statefulness) 때문).
IMMUTABLE: 함수가 같은 입력으로 호출되면 항상 같은 결과를 반환한다고 가정해요. 이 보장은 검사되지 않아요. 같은 입력에 다른 값을 반환하는 함수에 IMMUTABLE을 지정하면 정의되지 않은 동작이 발생해요.
기본값: VOLATILE

MAX_BATCH_ROWS = integer 동시성을 높이기 위해 서비스에 데이터를 보낼 때의 배치 크기를 지정해요.

MAX_BATCH_RETRIES = integer 실패한 배치를 Snowflake가 재시도하고 싶은 횟수를 지정해요.

기본값: 3

ON_BATCH_FAILURE = { ABORT | RETURN_NULL } Snowflake가 배치 처리에서 최대 재시도 횟수에 도달한 후 함수의 동작을 지정해요.

ABORT: 서비스 함수가 실행을 중단해요. 나머지 행 배치는 처리되지 않아요.
RETURN_NULL: 서비스 함수가 실패한 배치의 각 행에 대해 NULL을 반환하고 나머지 배치를 계속 처리해요. 이 옵션을 선택하면 다음 주의 사항이 적용돼요.
- 이 배치들이 서로 의존하고 하나가 실패하면 예기치 않은 결과가 나올 수 있어요.
- 서비스가 유효한 응답으로 NULL을 반환할 수 있다면, 배치 실패로 Snowflake가 반환한 NULL과 서비스가 반환한 NULL을 구분할 수 없어요.
기본값: ABORT

BATCH_TIMEOUT_SECS = integer 행 배치 하나를 처리하는 최대 시간(재시도와 비동기 함수 요청 폴링 포함)을 지정하며, 이후 Snowflake는 배치 요청을 종료해야 해요.

허용 값: 0보다 크고 604800초(7일)보다 작거나 같음
기본값: 3600초 (1시간)

COMMENT = 'string_literal' 함수에 대한 설명(comment)을 지정하며, SHOW FUNCTIONS와 SHOW USER FUNCTIONS 출력의 DESCRIPTION 컬럼에 표시돼요.

기본값: user-defined function

CONTEXT_HEADERS = ( context_function_1 [ , context_function_2 ...] ) 이 매개변수는 Snowflake 컨텍스트 함수 결과를 HTTP 헤더에 바인딩해요. (Snowflake 컨텍스트 함수에 대한 자세한 내용은 컨텍스트 함수(Context functions)를 참고해요.)

컨텍스트 헤더에서 모든 컨텍스트 함수가 지원되지는 않아요. 다음이 지원돼요.

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는 HTTP 요청에 기록되기 전에 헤더 앞에 sf-context를 붙여요.

예시:

CONTEXT_HEADERS = (current_timestamp)

이 예시에서 Snowflake는 sf-context-current-timestamp 헤더를 HTTP 요청에 기록해요.

컨텍스트 함수는 HTTP 헤더 값에서 불법인 문자를 생성할 수 있어요. 여기에는 다음이 포함되지만 이에 국한되지는 않아요.

newline (줄 바꿈)
Ä
Î
ß
ë
¬
±
©
®

Snowflake는 하나 이상의 불법 문자로 이루어진 각 연속 시퀀스를 공백 문자 하나로 대체해요. (대체는 문자당이 아니라 시퀀스당이에요.)

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

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

sf-context-current-statement로 전송되는 값은 다음과 같아요.

select /* */ my_service_function(1);

서비스 코드가 불법 문자가 대체되어도 컨텍스트 함수의 원래 결과(불법 문자 포함)에 접근할 수 있도록, Snowflake는 컨텍스트 함수 결과를 base64로 인코딩해 담은 이진 컨텍스트 헤더도 보내요.

위 예시에서 base64 인코딩된 헤더로 전송되는 값은 다음 호출의 결과예요.

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

원격 서비스는 필요에 따라 base64 값을 디코딩할 책임이 있어요.

이러한 각 base64 헤더는 다음 규칙에 따라 이름이 지정돼요.

sf-context-<context-function>-base64

위 예시에서 헤더 이름은 다음과 같아요.

sf-context-current-statement-base64

컨텍스트 헤더가 전송되지 않으면 base64 컨텍스트 헤더도 전송되지 않아요.

서비스 함수로 보내지는 행이 여러 배치로 분할되면 모든 배치에 같은 컨텍스트 헤더와 같은 이진 컨텍스트 헤더가 포함돼요.

접근 제어 요구 사항 (Access control requirements)

이 작업을 실행하는 데 사용하는 역할(role)은 최소한 다음 권한을 가져야 해요.

권한 (Privilege)	객체 (Object)	비고
CREATE FUNCTION	Schema
USAGE	Service Endpoint	서비스 엔드포인트에 대한 사용 권한은 서비스 사양에 정의된 서비스 역할에 부여돼요. 그런 다음 서비스 역할을 서비스 함수를 만드는 역할에게 부여해요.

스키마 안의 객체를 작업하려면 상위 데이터베이스에 대한 권한이 최소 하나, 상위 스키마에 대한 권한이 최소 하나 필요해요.

지정된 권한 집합으로 사용자 지정 역할을 만드는 방법은 사용자 지정 역할 만들기(Creating custom roles)를 참고해요. 보호 가능한 객체에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여의 일반적인 내용은 접근 제어 개요(Overview of Access Control)를 참고해요.

일반 사용 메모 (General usage notes)

CREATE OR REPLACE <object> 문은 원자적(atomic)으로 동작해요. 즉, 객체를 교체할 때 기존 객체는 삭제되고 새 객체는 단일 트랜잭션 안에서 생성돼요.

메타데이터에 관해서는 다음 사항에 주의해요.

⚠️ 주의: 고객은 Snowflake 서비스를 사용할 때 (User 객체를 제외하고) 개인 데이터·민감 데이터·수출 통제 데이터·기타 규제 데이터를 메타데이터로 입력하지 않도록 해야 해요. 자세한 내용은 Snowflake의 메타데이터 필드를 참고해요.

CREATE OR ALTER FUNCTION (Snowpark Container Services) 사용 메모

다음 수정은 지원되지 않아요.

RETURNS
휘발성(VOLATILE/IMMUTABLE)
null 처리(CALLED ON NULL INPUT / RETURNS NULL ON NULL)

예시 (Examples)

간단한 서비스 함수 만들기

Tutorial-1에서 다음 서비스 함수를 만들어요.

CREATE FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE=echo_service
  ENDPOINT=echoendpoint
  AS '/echo';

이 함수는 지정된 SERVICE의 특정 ENDPOINT와 연결돼요. 이 함수를 호출하면 Snowflake가 서비스 컨테이너 안의 /echo 경로에 요청을 보내요.

다음 사항에 주의해요.

my_echo_udf 함수는 문자열을 입력으로 받아 문자열을 반환해요.
SERVICE 속성은 서비스(echo_service)를 식별하고, ENDPOINT 속성은 사용자 친화적인 엔드포인트 이름(echoendpoint)을 식별해요.
AS '/echo'는 서비스의 경로를 지정해요. echo_service.py(서비스 코드 참고)에서 @app.post 데코레이터가 이 경로를 echo 함수와 연결해요.

CREATE OR ALTER FUNCTION (Snowpark Container Services) 명령으로 서비스 함수 수정

my_echo_udf 함수를 수정해 최대 배치 행 수를 100으로 설정하고 컨텍스트 헤더와 엔드포인트를 추가해요.

CREATE OR ALTER FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE = echo_service
  ENDPOINT = reverse_echoendpoint
  CONTEXT_HEADERS = (current_account)
  MAX_BATCH_ROWS = 100
  AS '/echo';

더 알아보기 (Learn more)

서비스 함수 — 서비스 함수 개요
CREATE EXTERNAL FUNCTION — 외부 함수 생성
ALTER FUNCTION — 함수 수정
DROP FUNCTION — 함수 삭제