Python UDF 만들기

이 항목에서는 Python UDF(사용자 정의 함수)를 만들고 설치하는 방법을 보여줍니다.

이 항목의 내용:

Python 코드 쓰기

Python 모듈 및 함수 쓰기

아래 사양을 따르는 모듈을 쓰십시오.

  • 모듈을 정의합니다. 모듈은 Python 정의 및 문을 포함하는 파일입니다.

  • 모듈 내부에 함수를 정의합니다.

  • 함수가 인자를 허용하는 경우, 각 인자는 SQL-Python 형식 매핑 테이블Python Data Type 열에 지정된 데이터 타입 중 하나여야 합니다.

    함수 인자는 이름이 아닌 위치로 바인딩됩니다. UDF에 전달된 첫 번째 인자는 Python 함수에서 수신한 첫 번째 인자입니다.

  • 적절한 반환 값을 지정하십시오. Python UDF는 스칼라 함수여야 하므로 호출될 때마다 하나의 값을 반환해야 합니다. 반환 값의 형식은 SQL-Python 형식 매핑 테이블Python Data Type 열에 지정된 데이터 타입 중 하나여야 합니다. 반환 값의 형식은 CREATE FUNCTION 문의 RETURNS 절에 지정된 SQL 데이터 타입과 호환되어야 합니다.

  • 모듈에는 둘 이상의 함수가 포함될 수 있습니다. Snowflake에서 호출하는 함수는 동일한 모듈의 다른 함수 또는 다른 모듈의 다른 함수를 호출할 수 있습니다.

  • 함수(및 해당 함수에서 호출하는 모든 함수)는 Python UDF에 대해 Snowflake가 부과한 제약 조건 을 준수해야 합니다.

참고

벡터화된 Python UDF를 사용하면 입력 행 배치를 Pandas DataFrames 로 수신하고 결과 배치를 Pandas 배열 또는 Series 로 반환하는 Python 함수를 정의할 수 있습니다. 자세한 내용은 벡터화된 Python UDF 섹션을 참조하십시오.

Snowflake에서 함수 만들기

다음을 지정하려면 CREATE FUNCTION 문을 실행해야 합니다.

  • UDF에 사용할 이름입니다.

  • Python UDF가 호출될 때 호출할 Python 함수의 이름입니다.

UDF의 이름은 Python으로 작성된 핸들러 함수의 이름과 일치할 필요가 없습니다. CREATE FUNCTION 문의 HANDLER 절은 UDF 이름을 Python 함수와 연관시킵니다.

UDF의 이름을 선택할 때 프로시저와 UDF의 명명 및 오버로딩 섹션을 참조하십시오.

CREATE FUNCTION 문의 본문 내에서 함수 인자는 이름이 아닌 위치로 바인딩됩니다. CREATE FUNCTION 문에서 선언된 첫 번째 인자는 Python 함수에 전달된 첫 번째 인자입니다.

인자의 데이터 타입에 대한 자세한 내용은 SQL-Python 데이터 타입 매핑 을 참조하십시오.

runtime_version 을 코드에서 필요한 Python 런타임 버전으로 설정합니다. 지원되는 Python 버전은 다음과 같습니다.

  • 3.8

  • 3.9

  • 3.10

  • 3.11

인라인 코드가 있는 UDF와 스테이지에서 업로드된 코드가 있는 UDF

Python UDF에 대한 코드는 다음 방법 중 하나로 지정할 수 있습니다.

  • 스테이지에서 업로드됨: CREATE FUNCTION 문은 스테이지 에서 기존 Python 소스 코드의 위치를 지정합니다.

  • 인라인: CREATE FUNCTION 문은 Python 소스 코드를 지정합니다.

인라인 Python UDF 만들기

인라인 UDF의 경우, CREATE FUNCTION 문의 일부로서 Python 소스 코드를 제공합니다.

예를 들어, 다음 문은 주어진 정수에 1을 더하는 인라인 Python UDF를 생성합니다.

create or replace function addone(i int)
returns int
language python
runtime_version = '3.8'
handler = 'addone_py'
as
$$
def addone_py(i):
  return i+1
$$;
Copy

Python 소스 코드는 AS 절에 지정됩니다. 소스 코드는 작은따옴표나 한 쌍의 달러 기호($$)로 묶을 수 있습니다. 소스 코드에 작은따옴표가 포함되어 있는 경우, 일반적으로 이중 달러 기호를 사용하는 것이 더 쉽습니다.

UDF를 호출합니다.

select addone(10);
Copy

출력은 다음과 같습니다.

+------------+
| ADDONE(10) |
|------------|
|         11 |
+------------+
Copy

Python 소스 코드는 둘 이상의 모듈, 그리고 한 모듈에 둘 이상의 함수를 포함할 수 있으므로 HANDLER 절은 호출할 모듈과 함수를 지정합니다.

인라인 Python UDF는 IMPORTS 절에 포함된 모듈의 코드를 호출할 수 있습니다.

CREATE FUNCTION 문의 구문에 대한 자세한 내용은 CREATE FUNCTION 을 참조하십시오.

더 많은 예제는 인라인 Python UDF 예제 를 참조하십시오.

스테이지에서 업로드된 코드로 Python UDF 만들기

다음 문은 스테이지 에서 업로드된 코드를 사용하여 간단한 Python UDF를 만듭니다. 파일을 호스팅하는 스테이지는 UDF 소유자 가 읽을 수 있어야 합니다. 또한 ZIP 파일이 자체 포함되어야 하며 실행할 추가 설정 스크립트에 의존하면 안 됩니다.

소스 코드가 포함된 sleepy.py 라는 Python 파일을 다음과 같이 만듭니다.

def snore(n):   # return a series of n snores
    result = []
    for a in range(n):
        result.append("Zzz")
    return result
Copy

SnowSQL(CLI 클라이언트) 를 시작하고 PUT 명령을 사용하여 파일을 로컬 파일 시스템에서 @~ 라는 기본 사용자 스테이지로 복사합니다. (PUT 명령은 Snowflake GUI를 통해 실행할 수 없습니다.)

put
file:///Users/Me/sleepy.py
@~/
auto_compress = false
overwrite = true
;
Copy

파일을 삭제하거나 이름을 바꾸면 더 이상 UDF를 호출할 수 없습니다. 파일을 업데이트해야 하는 경우에는 UDF를 호출할 수 없는 동안 업데이트하십시오. 이전 파일이 아직 스테이지에 있는 경우, PUT 명령에 OVERWRITE=TRUE 절이 포함되어야 합니다.

UDF를 만듭니다. 이 핸들러는 모듈과 함수를 지정합니다.

create or replace function dream(i int)
returns variant
language python
runtime_version = '3.8'
handler = 'sleepy.snore'
imports = ('@~/sleepy.py')
Copy

UDF를 호출합니다.

select dream(3);

+----------+
| DREAM(3) |
|----------|
| [        |
|   "Zzz", |
|   "Zzz", |
|   "Zzz"  |
| ]        |
+----------+
Copy

여러 가져오기 파일 지정하기

다음은 여러 가져오기 파일을 지정하는 방법을 보여주는 예제입니다.

create or replace function multiple_import_files(s string)
returns string
language python
runtime_version=3.8
imports=('@python_udf_dep/bar/python_imports_a.zip', '@python_udf_dep/foo/python_imports_b.zip')
handler='compute'
as
$$
def compute(s):
  return s
$$;
Copy

참고

지정된 가져오기 파일 이름은 서로 달라야 합니다. 예를 들어 imports=('@python_udf_dep/bar/python_imports.zip', '@python_udf_dep/foo/python_imports.zip') 은 작동하지 않습니다.

함수에 대한 권한 부여

함수 소유자 이외의 역할이 함수를 호출하려면 소유자가 역할에 적절한 권한을 부여해야 합니다.

Python UDF에 대한 GRANT 문은 JavaScript UDF와 같은 다른 UDF에 대한 GRANT 문과 본질적으로 동일합니다.

예:

GRANT USAGE ON FUNCTION my_python_udf(number, number) TO my_role;
Copy