사용자 정의 함수 개요¶

UDF(사용자 정의 함수)를 작성하여 Snowflake에서 기본적으로 제공되는 시스템 정의 함수 를 통해 할 수 없는 작업을 수행하도록 시스템을 확장할 수 있습니다. UDF를 생성하면 여러 번 재사용할 수 있습니다. 함수는 항상 식을 지정하여 명시적으로 값을 반환하므로 값을 계산하고 반환하는 데 적합합니다.

UDFs를 사용하여 기본 제공 함수를 확장하거나 조직에 표준이 되는 계산을 캡슐화할 수 있습니다. UDF를 생성하면 기본 제공 함수와 유사한 방식으로 호출할 수 있습니다.

지원되는 언어 중 하나로 UDF의 논리(해당 처리기)를 작성합니다. 처리기가 있으면 Snowflake에 포함된 여러 도구를 사용하여 UDF 를 생성한 다음 UDF 를 실행할 수 있습니다.

UDF는 저장 프로시저와 비슷하지만 두 가지 중요한 면에서 다릅니다. 자세한 내용은 저장 프로시저를 작성할지 사용자 정의 함수를 작성할지 선택하기 섹션을 참조하십시오.

UDF는 Snowflake를 확장하는 한 가지 방법일 뿐입니다. 다른 방법은 다음 섹션을 참조하십시오.

사용자 정의 함수 변형¶

함수가 충족해야 하는 입력 및 출력 요구 사항에 따라 여러 가지 변형 중 하나로 UDF 를 작성할 수 있습니다.

변형	설명
사용자 정의 함수(UDF)	스칼라 함수 로 알려져 있으며, 각 입력 행에 대해 하나의 출력 행을 반환합니다. 반환된 행은 단일 열/값으로 구성됩니다.
사용자 정의 집계 함수(UDAF)	여러 행의 값을 연산하여 합계, 평균, 계산, 최소값 또는 최대값 찾기, 표준 편차, 추정과 같은 수학적 계산과 일부 비수학적 연산을 수행합니다.
사용자 정의 테이블 함수(UDTF)	각 입력 행에 대한 표 형식의 값을 반환합니다.
벡터화된 사용자 정의 함수(UDF)	입력 행 배치를 Pandas DataFrames 로 수신하고 결과 배치를 Pandas 배열 또는 Series 로 반환합니다.
벡터화된 사용자 정의 테이블 함수(UDTF)	입력 행의 배치를 Pandas DataFrames 로 수신하고 표 형식의 결과를 반환합니다.

지원 언어 및 도구¶

선호하는 작업 방식에 따라 여러 도구 중 하나를 사용하여 만들고 UDF 및 기타 Snowflake 엔터티를 관리할 수 있습니다.

언어	접근 방식	지원
SQL Java, JavaScript, Python, Scala 또는 SQL에서 처리기 사용	Snowflake에서 SQL 코드를 작성하여 Snowflake 엔터티를 만들고 관리합니다. 지원되는 처리기 언어 중 하나로 함수의 로직을 작성합니다.	Java: UDF, UDTF JavaScript: UDF, UDTF Python: UDF, UDAF, UDTF, 벡터화된 UDF, 벡터화된 UDTF Scala: UDF SQL: UDF, UDTF
Java, Python 또는 Scala Snowpark API	클라이언트에서 처리를 위해 Snowflake로 푸시되는 작업에 대한 코드를 작성합니다.	Java: UDF, UDTF Python: UDF, UDAF, UDTF, 벡터화된 UDF 또는 UDTF Scala: UDF, UDTF
명령줄 인터페이스 Snowflake CLI	명령줄을 사용하여 속성을 JSON 오브젝트의 속성으로 지정하여 Snowflake 엔터티를 만들고 관리할 수 있습니다.	Snowflake 오브젝트 관리하기
Python Snowflake Python API	클라이언트에서 지원되는 처리기 언어 중 하나로 함수의 핸들러를 작성하여 Python으로 함수를 생성하는 명령을 실행합니다.	사용자 정의 함수(UDFs) 관리하기
REST Snowflake REST API	RESTful 엔드포인트에 요청하여 Snowflake 엔터티를 생성하고 관리하십시오.	사용자 정의 함수 관리하기

언어를 선택할 때 다음 사항도 고려하십시오.

지원되는 처리기 위치. 일부 언어에서는 스테이지에서 처리기 참조를 지원하지 않습니다(대신 처리기 코드는 인라인이어야 함). 자세한 내용은 처리기 코드를 인라인 또는 스테이지에 유지하기 섹션을 참조하십시오.
처리기를 통해 공유 가능한 UDF를 얻을 수 있는지 여부. 공유 가능한 UDF는 Snowflake Secure Data Sharing 기능과 함께 사용할 수 있습니다.

언어	처리기 위치	공유 가능
Java	인라인 또는 스테이징됨	아니요 [1]
JavaScript	인라인	예
Python	인라인 또는 스테이징됨	아니요 [2]
Scala	인라인 또는 스테이징됨	아니요 [3]
SQL	인라인	예

고려 사항¶

쿼리가 스테이징된 파일에 액세스하는 UDF를 호출하는 경우 뷰의 함수가 스테이징된 파일에 액세스하는지 여부에 관계없이 SQL 문이 모든 UDF 또는 UDTF를 호출하는 뷰도 쿼리하면 사용자 오류가 발생하며 작업이 실패합니다.
UDTF는 여러 파일을 병렬로 처리할 수 있지만, UDF는 현재 파일을 직렬로 처리합니다. 해결 방법으로는, GROUP BY 절을 사용하여 하위 쿼리에 행을 그룹화하십시오. 예제는 UDTF로 CSV 처리하기 섹션을 참조하십시오.
현재, 쿼리 실행 중에 쿼리에서 참조되는 스테이징된 파일이 수정되거나 삭제될 경우에는 오류가 발생하며 함수 호출이 실패합니다.
UDF의 핸들러 코드에 CURRENT_DATABASE 또는 CURRENT_SCHEMA 함수를 지정하면 함수는 세션에 사용 중인 데이터베이스 또는 스키마가 아니라 UDF가 포함된 데이터베이스 또는 스키마를 반환합니다.

UDF 예제¶

다음 예제의 코드는 Python으로 작성된 처리기를 사용하여 addone 이라는 UDF를 생성합니다. 처리기 함수는 addone_py 입니다. 이 UDF는 int 를 반환합니다.

CREATE OR REPLACE FUNCTION addone(i int)
RETURNS INT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.9'
HANDLER = 'addone_py'
as
$$
def addone_py(i):
 return i+1
$$;

Copy

다음 예제의 코드는 addone UDF를 실행합니다.

SELECT addone(3);

Copy

지침 및 제약 조건¶

Snowflake 제약 조건:: Snowflake 제약 조건 내에서 개발하여 Snowflake 환경 내에서 안정성을 보장할 수 있습니다. 자세한 내용은 Snowflake에서 적용한 제약 조건 내에서 유지되는 처리기 설계하기 섹션을 참조하십시오.
명명:: 다른 함수와 충돌하지 않도록 함수 이름을 지정해야 합니다. 자세한 내용은 프로시저와 UDF의 명명 및 오버로딩 섹션을 참조하십시오.
인자:: 인자를 지정하고 선택적인 표시합니다. 자세한 내용은 UDF 및 저장 프로시저에 대한 인자 정의하기 섹션을 참조하십시오.
데이터 타입 매핑:: 각 처리기 언어에 대해 언어의 데이터 타입과 인자 및 반환 값에 사용되는 SQL 유형 간에 별도의 매핑 세트가 있습니다. 각 언어의 매핑에 대한 자세한 내용은 SQL 및 처리기 언어 간의 데이터 타입 매핑 섹션을 참조하십시오.

처리기 작성¶

처리기 언어:: 처리기 작성에 대한 언어별 콘텐츠는 지원 언어 및 도구 섹션을 참조하십시오.
외부 네트워크 액세스:: 외부 네트워크 액세스 로 외부 네트워크 위치에 액세스할 수 있습니다. Snowflake 외부의 특정 네트워크 위치에 대한 보안 액세스를 생성한 다음, 처리기 코드 내에서 해당 액세스를 사용할 수 있습니다.
로깅, 추적 및 메트릭:: 로그 메시지, 추적 이벤트, 메트릭 데이터를 캡처하고 나중에 쿼리할 수 있는 데이터베이스에 데이터를 저장하여 코드 활동을 기록할 수 있습니다.

보안¶

UDF 또는 UDTF로 특정 SQL 작업을 수행하는 데 필요한 오브젝트에 대한 권한을 부여할 수 있습니다. 자세한 내용은 사용자 정의 함수에 대한 권한 부여 섹션을 참조하십시오.

함수는 저장 프로시저와 특정 보안 문제를 공유합니다. 자세한 내용은 다음을 참조하십시오.

UDF 및 프로시저의 보안 모범 사례 에 설명된 모범 사례에 따라 프로시저의 처리기 코드가 안전하게 실행되도록 도울 수 있습니다.
민감한 정보에 액세스하면 안 되는 사용자가 민감한 정보를 볼 수 없도록 되어 있는지 확인합니다. 자세한 내용은 Secure UDF와 저장 프로시저로 민감한 정보 보호하기 섹션을 참조하십시오.

처리기 코드 배포¶

함수를 만들 때 함수의 로직을 구현하는 처리기를 함수 정의에 따라 인라인 코드로 지정하거나, 패키지화하여 외부 스테이지에 복사한 코드와 같이 정의 외부의 코드로 지정할 수 있습니다.

자세한 내용은 처리기 코드를 인라인 또는 스테이지에 유지하기 섹션을 참조하십시오.