Unity 카탈로그의 UDF(사용자 정의 함수)는 Azure Databricks 내에서 SQL 및 Python 기능을 확장합니다. 이를 통해 컴퓨팅 환경에서 사용자 지정 함수를 정의, 사용 및 안전하게 공유하고 제어할 수 있습니다.
Unity 카탈로그에 함수로 등록된 Python UDF는 범위가 다르며 Notebook 또는 SparkSession으로 범위가 지정된 PySpark UDF의 지원도 다릅니다. UDF(스칼라 사용자 정의 함수)Python 참조하세요.
Scala로 작성된 UDF를 등록하거나 Unity 카탈로그에서 Java 등록하려면 Unity 카탈로그에서 Scala 및 UDF(사용자 정의 함수) Java 참조하세요.
Unity 카탈로그에서 UDF를 수정하기 전에 어떤 워크로드와 테이블이 이를 참조하는지 확인하려면 UDF 계보 보기를 참조하세요.
전체 SQL 언어 참조는 (SQL, Python, Scala 및 Java)를 참조CREATE FUNCTION하세요.
요구 사항
Unity 카탈로그에서 UDF를 사용하려면 다음 요구 사항을 충족해야 합니다.
- Unity 카탈로그에 등록된 UDF에서 Python 코드를 사용하려면 서버리스 또는 pro SQL 웨어하우스 또는 Databricks Runtime 13.3 LTS 이상을 실행하는 클러스터를 사용해야 합니다.
- 뷰에 Unity 카탈로그 Python UDF가 포함되어 있으면 클래식 SQL 웨어하우스에서 실패합니다.
- Unity 카탈로그 지원 클러스터의 Scala UDF에 대한 ARM 인스턴스 지원은 Databricks Runtime 15.2 이상에서 사용할 수 있습니다.
스칼라 및 배치 Unity Catalog Python UDF는 지원되는 모든 컴퓨트 유형에서 정식으로 사용할 수 있습니다.
Python UDF 기능 요구사항
요구사항은 특징마다 다릅니다. Databricks 런타임 19와 환경 버전 6은 Unity 카탈로그 Python UDF의 일반적인 요구사항이 아닙니다.
서버리스 노트북이나 작업에서 PySpark 세션 UDF의 경우, 환경 요구사항은 세션 환경을 의미합니다. SQL로 정의된 Python UDF의 경우 각 함수의 environment_version 절에서 ENVIRONMENT를 참조합니다. 세션 환경을 변경한다고 해서 기존 Unity 카탈로그 함수의 환경이 변경되는 것은 아닙니다. 예를 들어, 환경 버전 6을 사용하는 세션은 환경 버전 5로 정의된 Unity 카탈로그 함수를 호출할 수 있습니다.
| 특징 | 요구 사항 |
|---|---|
ENVIRONMENT 조항 및 관습 의존성 |
서버리스 노트북과 작업; 프로 또는 서버리스 SQL 웨어하우스; 클래식 컴퓨트의 Databricks Runtime 16.2 이상 Databricks Runtime 16.2부터 18.1 environment_version 까지 실행되는 클래식 컴퓨트에서는 반드시 .'None' |
| Batch Unity 카탈로그 Python UDFs | 서버 없는 컴퓨트; 프로 및 서버리스 SQL 웨어하우스; 클래식 컴퓨트에서 Databricks 런타임 16.3 이상 |
| Python 스칼라 UDF용 명명된 핸들러 | Databricks Runtime 18.1 이상을 클래식 컴퓨트에서 지원할 수 있습니다. 서버리스 컴퓨트와 프로 및 서버리스 SQL 웨어하우스에서는 UDF의 environment_version를 명시적으로 6 이상으로 설정하세요. |
| 스칼라 Python UDF에서의 서비스 자격 증명 | Databricks Runtime 18.1 이상을 클래식 컴퓨트에서 지원할 수 있습니다. 서버리스 컴퓨트와 프로 및 서버리스 SQL 웨어하우스에서는 UDF의 environment_version를 명시적으로 6 이상으로 설정하세요. 클래식 컴퓨트는 환경 버전 6이 필요하지 않습니다. 서버리스 SQL 웨어하우스에서는 별도의 워크로드 네트워킹 공개 프리뷰도 활성화하세요. |
| Batch Unity Catalog Python UDF의 서비스 자격 증명 | 서버리스 컴퓨트; 프로 및 서버리스 SQL 웨어하우스; 클래식 컴퓨트에서 Databricks 런타임 16.3 이상 지원. 환경 버전 6은 필수가 아닙니다. 서버리스 SQL 웨어하우스에서는 별도의 워크로드 네트워킹 공개 프리뷰도 활성화하세요. |
| 스칼라 또는 배치 Unity Catalog Python UDF의 비밀 정보 |
environment_version를 명시적으로 6 이상으로 설정합니다. 서버리스 컴퓨트, 프로 및 서버리스 SQL 웨어하우스, 그리고 클래식 컴퓨트에서 표준 액세스 모드를 사용하는 Databricks Runtime 19 이상. 전용 접근 모드 계산에서는 직접 호출이 지원되지 않습니다. |
PySpark 호환 TIMESTAMP 입력 동작 |
Databricks Runtime 18.1 이상을 클래식 컴퓨트에서 지원할 수 있습니다. 서버리스 컴퓨트와 프로 및 서버리스 SQL 웨어하우스에서는 UDF의 environment_version를 명시적으로 6 이상으로 설정하세요. |
| 쿼리에서 5회 이상의 UDF 호출 | Databricks Runtime 18.1 이상을 클래식 컴퓨트에서 지원할 수 있습니다. 서버리스 컴퓨트와 프로 및 서버리스 SQL 웨어하우스에서 각 UDF environment_version6 를 명시적으로 이상으로 설정하세요. |
공개 프리뷰 기간 동안 제공되었던 기존 UDF와 기능들은 해당 이전 런타임 버전에서 계속 작동하고 있습니다.
환경 버전은 또한 호출자가 Unity 카탈로그 볼륨에 저장된 의존성에 직접 접근해야 하는지 여부를 결정합니다. Unity 카탈로그 볼륨의 의존성 권한을 참조하세요.
클래식 컴퓨트의 환경 버전
클래식 컴퓨트에서는 이 'None' 값이 아닌 값으로 설정 environment_version 하려면 Databricks Runtime 18.2 이상이 필요합니다. Databricks 런타임 16.2부터 18.1까지는 절을 사용할 ENVIRONMENT 때마다 설정 environment_version = 'None' 하세요. 값 'None' 은 기본 Python 환경을 사용합니다.
Databricks Runtime 18.2 이상에서는 예측 가능한 동작을 위해 Azure Databricks가 각 Unity Catalog Python UDF 정의에서 명시적으로 고정 environment_version 설정을 권장합니다. UDF의 기능 요구 사항을 충족하고 다음 호환성 권장 사항을 따르는 버전을 선택하세요:
| Databricks Runtime 버전 정보 | 최대 권장 환경 버전 |
|---|---|
| 18.2부터 18.x까지 | 5 |
| 19.x | 6 |
Unity 카탈로그에서 SQL 및 Python UDF 만들기
Unity Catalog에서 SQL 또는 Python UDF를 생성하려면 사용자에게는 스키마에 대한 USAGE 및 CREATE 권한과 카탈로그에 대한 USAGE 권한이 필요합니다. 자세한 내용은 Unity 카탈로그 참조하세요.
UDF를 실행하려면 UDF에 대한 EXECUTE 권한이 필요합니다. 또한 사용자는 스키마 및 카탈로그에 대한 USAGE 권한이 필요합니다.
Unity 카탈로그 스키마에서 UDF를 만들고 등록하려면 함수 이름이 형식 catalog.schema.function_name을 따라야 합니다. 또는 SQL 편집기에서 올바른 카탈로그 및 스키마를 선택할 수 있습니다.
이 경우 함수 이름 앞에 catalog.schema가 추가되어서는 안 됩니다.
다음 예제에서는 my_schema 카탈로그 내의 my_catalog 스키마에 새 함수를 등록합니다.
CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight DOUBLE, height DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
RETURN
SELECT weight / (height * height);
Unity 카탈로그용 Python UDF는 이중 달러 기호로 구분된 문($$)을 사용합니다. 데이터 형식 매핑을 지정해야 합니다. 다음 예제에서는 체질량 인덱스를 계산하는 UDF를 등록합니다.
CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
return weight_kg / (height_m ** 2)
$$;
이제 SQL 쿼리 또는 PySpark 코드에서 이 Unity 카탈로그 함수를 사용할 수 있습니다.
SELECT person_id, my_catalog.my_schema.calculate_bmi(weight_kg, height_m) AS bmi
FROM person_data;
더 많은 UDF 예제는 행 필터 예제 및 열 마스크 예제 를 참조하세요.
스칼라 Python UDF에서 이름 있는 핸들러를 사용하세요
클래식 컴퓨트에서는 이름 있는 핸들러가 Databricks Runtime 18.1 이상이어야 합니다. 서버리스 컴퓨트와 프로 및 서버리스 SQL 웨어하우스에서는 UDF의 environment_version를 명시적으로 6 이상으로 설정하세요. 다음 예시는 환경 버전 6을 사용합니다. Databricks Runtime 18.1을 실행하는 클래식 컴퓨트에서는 절을 ENVIRONMENT 생략하세요. 이후 런타임 버전에서는 조항을 포함하면 호환성 권장사항을 따르세요.
UDF 본문 내 Python 함수를 진입점으로 지정하는 절을 HANDLER 사용하세요. 명명된 핸들러는 UDF 인자를 받아들이고 선언된 반환 타입과 일치하는 값을 반환합니다. 핸들러 외부의 코드는 각 Python 환경이 UDF를 초기화할 때 실행되며, 핸들러가 입력을 처리하기 전에 실행됩니다. 이 코드를 일회용 초기화에 사용하여 핸들러 호출 간에 재사용할 수 있습니다.
다음 예시는 UDF 입력을 처리하는 함수를 정의greet_handler하기 전에 초기화합니다greeting_prefix:
CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
HANDLER 'greet_handler'
ENVIRONMENT (
environment_version = '6'
)
AS $$
# Runs once when each Python environment initializes the UDF.
greeting_prefix = "Hello"
def greet_handler(name):
return f"{greeting_prefix}, {name}!"
$$;
Python UDF에서 비밀을 사용하세요
스칼라 및 배치 Unity Catalog Python UDF는 SECRETS 절에서 선언된 시크릿에 접근할 수 있습니다. UDF 정의는 6를 environment_version 이상으로 명시적으로 설정해야 합니다. Unity Catalog 비밀은 세 부분 이름(catalog.schema.secret)을 사용하며, 작업 공간 수준의 Azure Databricks 비밀과는 구별됩니다. 컴퓨트 지원, 권한, 그리고 전용 컴퓨트 컬럼-마스크 예외에 대해서는 UDF 요구사항 및 권한(requirements and permissions)을 참조하세요.
UDF에서 시크릿에 액세스하려면:
- UDF 정의의
SECRETS절에 시크릿의 3부분 이름을 추가하세요. UDF는 이 절에서 선언된 비밀 정보만 조회할 수 있습니다. - UDF 본체에서 카탈로그, 스키마, 비밀 이름을 입력해 호출
databricks.secrets.get()합니다.
다음 스칼라 UDF 예시는 Unity 카탈로그 비밀을 해시 기반 메시지 인증 코드(HMAC) 서명 키로 사용합니다. 배치 UDF 핸들러에서 선언된 시크릿에 액세스하려면 PARAMETER STYLE PANDAS와 함께 동일한 SECRETS 구문을 사용하세요.
CREATE OR REPLACE FUNCTION main.default.sign_value(value STRING)
RETURNS STRING
LANGUAGE PYTHON
SECRETS (main.default.hmac_key)
ENVIRONMENT (
environment_version = '6'
)
AS $$
import hashlib
import hmac
from databricks.secrets import get
key = get(catalog="main", schema="default", key="hmac_key")
return hmac.new(key.encode(), value.encode(), hashlib.sha256).hexdigest()
$$;
Warning
UDF에서 비밀 값을 반환하지 마세요. 비밀 편집은 오류와 로그에서의 우발적 노출을 줄이지만, UDF 코드가 쿼리 결과에서 비밀 자료를 노출하는 것을 막지는 못합니다.
사용자 지정 종속성을 사용하여 UDF 확장
참고
서버리스 SQL 웨어하우스에 인터넷에서 사용자 지정 종속성을 설치하려면 작업 영역에서 미리 보기 페이지의 공개 미리 보기 기능인 Serverless SQL Warehouses의 격리된 워크로드에 네트워킹 사용이 활성화되어 있어야 합니다.
외부 라이브러리에 대한 사용자 지정 종속성을 정의하여 Databricks 런타임 환경 이상으로 Unity 카탈로그 Python UDF의 기능을 확장할 수 있습니다.
요구 사항
Unity 카탈로그 UDF에 대한 사용자 지정 종속성은 다음 컴퓨팅 유형에서 지원됩니다.
- 서버리스 Notebook 및 작업
- Databricks 런타임 버전 16.2 이상을 사용하는 클래식 다목적 컴퓨팅
- Pro 또는 서버리스 SQL 웨어하우스
종속성 원본
다음 원본에서 종속성을 설치합니다.
- PyPI 패키지
- Unity 카탈로그 볼륨에 저장된 파일Unity 카탈로그 볼륨 내 의존성에 대한 권한 항목을 참조하세요.
- 공용 URL에서 사용할 수 있는 파일 작업 영역 네트워크 보안 규칙은 공용 URL에 대한 액세스를 허용해야 합니다. 요구 사항을 참조하세요.
참고
작업 영역에서 서버리스 네트워크 액세스를 제한하는 경우 공용 URL을 허용하도록 네트워크 보안 규칙을 구성해야 합니다. 송신 규칙 설정을 참조하세요.
Unity 카탈로그 볼륨에서 의존성 권한
함수 생성자는 소스 볼륨에서 UDF로의 종속성을 추가하려면 해당 소스 볼륨에 대한 READ VOLUME 권한이 있어야 합니다.
정의에서 environment_version를 명시적으로 EXECUTE 이상으로 설정한 UDF의 경우, 호출자는 UDF에 대해 READ VOLUME가 필요하지만 소스 볼륨에 대해서는 6가 필요하지 않습니다. UDF 정의에서 environment_version를 생략하거나, None로 설정하거나, 그보다 이전 버전으로 설정하는 경우 호출자는 소스 볼륨에도 READ VOLUME가 있어야 합니다.
종속성 정의
ENVIRONMENT UDF 정의의 섹션을 사용하여 종속성을 지정합니다.
CREATE OR REPLACE FUNCTION my_catalog.my_schema.mixed_process(data STRING)
RETURNS STRING
LANGUAGE PYTHON
ENVIRONMENT (
dependencies = '["simplejson==3.19.3", "/Volumes/my_catalog/my_schema/my_volume/packages/custom_package-1.0.0.whl", "https://my-bucket.s3.amazonaws.com/packages/special_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]',
environment_version = '6'
)
AS $$
import simplejson as json
import custom_package
return json.dumps(custom_package.process(data))
$$;
섹션에는 ENVIRONMENT 다음 필드가 포함되어 있습니다.
| 분야 | 설명 | 유형 | 사용 예시 |
|---|---|---|---|
dependencies |
설치할 쉼표로 구분된 종속성 목록입니다. 각 항목은 pip 요구 사항 파일 형식을 준수하는 문자열입니다. | STRING |
dependencies = '["simplejson==3.19.3", "/Volumes/catalog/schema/volume/packages/my_package-1.0.0.whl"]'dependencies = '["https://my-bucket.s3.amazonaws.com/packages/my_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]' |
environment_version |
UDF를 실행할 환경 버전을 지정합니다. 이 필드는 절이 ENVIRONMENT 존재할 때마다 필요합니다. 고정 환경 버전은 기본 Databricks Runtime의 Python 버전 및 패키지와 관계없이 특정 Python 버전 및 사전 설치된 패키지 집합으로 UDF를 실행합니다.지원되는 값은 예를 들어 '6'와 같은 환경 버전 3 이상 또는 문자열 'None'입니다. 이 값 'None' 은 기본 Python 환경을 선택합니다. 클래식 컴퓨트에서는 이 'None' 값이 아닌 값으로 설정 environment_version 하려면 Databricks Runtime 18.2 이상이 필요합니다. Databricks 런타임 16.2부터 18.1 'None' 까지만 지원됩니다. 고정된 환경 버전이 지원되는 경우, 예상 가능한 동작을 위해 그중 하나를 명시적으로 선택하세요.서버리스 컴퓨트와 프로 및 서버리스 SQL 웨어하우스에서는 일부 기능이 명시적인 환경 버전을 요구합니다. 각 UDF 정의에서 environment_version를 필요한 버전 이상으로 설정하세요. 전체 ENVIRONMENT 조항이나 설정을 environment_version = 'None' 생략해도 해당 기능들이 활성화되지 않습니다.
Python UDF 기능 요구사항을 참조하세요.클래식 컴퓨트 버전 호환성에 대해서는 클래식 컴퓨트의 환경 버전을 참조하세요. 사용 가능한 버전 목록은 환경 버전을 참조하세요. |
STRING |
environment_version = '6' |
PySpark에서 Unity 카탈로그 UDF 사용
from pyspark.sql.functions import expr
result = df.withColumn("bmi", expr("my_catalog.my_schema.calculate_bmi(weight_kg, height_m)"))
display(result)
UDF의 세션 범위 업그레이드
참고
Unity 카탈로그의 Python UDF에 대한 구문 및 의미 체계는 SparkSession에 등록된 Python UDF와 다릅니다. 사용자 정의 스칼라 함수 - Python을 참조하세요.
Azure Databricks Notebook에서 다음 세션 기반 UDF를 지정합니다.
from pyspark.sql.functions import udf
from pyspark.sql.types import StringType
@udf(StringType())
def greet(name):
return f"Hello, {name}!"
# Using the session-based UDF
result = df.withColumn("greeting", greet("name"))
result.show()
이를 Unity 카탈로그 함수로 등록하려면 다음 예제와 같이 SQL CREATE FUNCTION 문을 사용합니다.
CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
return f"Hello, {name}!"
$$
Unity 카탈로그에서 UDF 공유
UDF를 등록하는 카탈로그, 스키마 또는 데이터베이스에 적용되는 액세스 제어는 해당 권한을 관리합니다. 자세한 내용은 Unity 카탈로그의 권한 관리를 참조하세요.
Azure Databricks SQL 또는 Azure Databricks 작업 영역 UI를 사용하여 사용자 또는 그룹에 권한을 부여합니다(권장).
작업 영역 UI의 권한
- UDF가 저장되는 카탈로그 및 스키마를 찾아서 UDF를 선택합니다.
- UDF 설정에서 사용 권한 옵션을 찾습니다. 사용자 또는 그룹을 추가하고 EXECUTE 또는 MANAGE와 같은 액세스 유형을 지정합니다.
Azure Databricks SQL을 사용하는 권한
다음 예제에서는 사용자에게 함수에 대한 EXECUTE 권한을 부여합니다.
GRANT EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi TO `user@example.com`;
권한을 제거하려면 다음 예제와 같이 REVOKE 명령을 사용합니다.
REVOKE EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi FROM `user@example.com`;
환경 분리
참고
공유 격리 환경은 Databricks 런타임 18.1 이상이 필요합니다. 이전 버전에서는 모든 Unity 카탈로그 Python UDF가 엄격한 격리 모드에서 실행됩니다.
동일한 소유자 및 세션이 있는 Unity 카탈로그 Python UDF는 기본적으로 격리 환경을 공유할 수 있습니다. 이렇게 하면 실행해야 하는 별도의 환경 수가 줄어들어 성능이 향상되고 메모리 사용량이 줄어듭니다.
엄격한 격리
UDF가 항상 완전히 격리된 자체 환경에서 실행되는지 확인하려면 특성 절을 STRICT ISOLATION 추가합니다.
대부분의 UDF는 엄격한 격리가 필요하지 않습니다. 표준 데이터 처리 UDF는 기본 공유 격리 환경의 이점을 활용하고 메모리 사용량을 줄이면 더 빠르게 실행됩니다.
UDF에 STRICT ISOLATION 다음과 같은 특성 절을 추가합니다.
-
eval(),exec()또는 유사한 함수를 사용하여 입력을 코드로 실행합니다. - 로컬 파일 시스템에 파일을 씁니다.
- 전역 변수 또는 시스템 상태를 수정합니다.
- 환경 변수에 액세스하거나 수정합니다.
다음 코드는 을 사용하여 STRICT ISOLATION실행해야 하는 UDF의 예를 보여 줌 이 UDF는 임의의 Python 코드를 실행하므로 시스템 상태를 변경하거나 환경 변수에 액세스하거나 로컬 파일 시스템에 쓸 수 있습니다. 절을 STRICT ISOLATION 사용하면 UDF 간 간섭 또는 데이터 누출을 방지할 수 있습니다.
CREATE OR REPLACE TEMPORARY FUNCTION run_python_snippet(python_code STRING)
RETURNS STRING
LANGUAGE PYTHON
STRICT ISOLATION
AS $$
import sys
from io import StringIO
# Capture standard output and error streams
captured_output = StringIO()
captured_errors = StringIO()
sys.stdout = captured_output
sys.stderr = captured_errors
try:
# Execute the user-provided Python code in an empty namespace
exec(python_code, {})
except SyntaxError:
# Retry with escaped characters decoded (for cases like "\n")
def decode_code(raw_code):
return raw_code.encode('utf-8').decode('unicode_escape')
python_code = decode_code(python_code)
exec(python_code, {})
# Return everything printed to stdout and stderr
return captured_output.getvalue() + captured_errors.getvalue()
$$
DETERMINISTIC 함수가 일관된 결과를 생성하는지 설정
동일한 입력에 대해 동일한 출력을 생성하는 경우 함수 정의에 추가 DETERMINISTIC 합니다. 이렇게 하면 쿼리 최적화를 통해 성능을 향상시킬 수 있습니다.
기본적으로 Azure Databricks는 명시적으로 달리 선언하지 않는 한 Batch Unity Catalog Python UDF를 비결정적인 것으로 간주합니다. 비결정적 함수의 예로는 임의 값 생성, 현재 시간 또는 날짜 액세스 또는 외부 API 호출 등이 있습니다.
참조 CREATE FUNCTION (SQL, Python, Scala 및 Java)
에이전트 도구용 UDF
AI 에이전트는 Unity 카탈로그 UDF를 도구로 사용하여 작업을 수행하고 사용자 지정 논리를 실행할 수 있습니다.
Unity 카탈로그 함수를 사용하여 에이전트 도구 만들기를 참조하세요.
외부 API에 액세스하기 위한 UDF
UDF를 사용하여 SQL에서 외부 API에 액세스할 수 있습니다. 다음 예제에서는 Python requests 라이브러리를 사용하여 HTTP 요청을 만듭니다.
참고
Python UDF는 표준 액세스 모드로 구성된 서버리스 컴퓨팅 또는 컴퓨팅을 사용할 때 포트 80, 443 및 53을 통한 TCP/UDP 네트워크 트래픽을 허용합니다.
CREATE FUNCTION my_catalog.my_schema.get_food_calories(food_name STRING)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
import requests
api_url = f"https://example-food-api.com/nutrition?food={food_name}"
response = requests.get(api_url)
if response.status_code == 200:
data = response.json()
# Assume the API returns a JSON object with a 'calories' field
calories = data.get('calories', 0)
return calories
else:
return None # API request failed
$$;
보안 및 규정 준수를 위한 UDF
Python UDF를 사용하여 사용자 지정 토큰화, 데이터 마스킹, 데이터 편집 또는 암호화 메커니즘을 구현합니다.
다음 예제에서는 길이 및 도메인을 유지하면서 전자 메일 주소의 ID를 마스킹합니다.
CREATE OR REPLACE FUNCTION my_catalog.my_schema.mask_email(email STRING)
RETURNS STRING
LANGUAGE PYTHON
DETERMINISTIC
AS $$
parts = email.split('@', 1)
if len(parts) == 2:
username, domain = parts
else:
return None
masked_username = username[0] + '*' * (len(username) - 2) + username[-1]
return f"{masked_username}@{domain}"
$$
다음 예제에서는 동적 뷰 정의에 이 UDF를 적용합니다.
-- First, create the view
CREATE OR REPLACE VIEW my_catalog.my_schema.masked_customer_view AS
SELECT
id,
name,
my_catalog.my_schema.mask_email(email) AS masked_email
FROM my_catalog.my_schema.customer_data;
-- Now you can query the view
SELECT * FROM my_catalog.my_schema.masked_customer_view;
+---+------------+------------------------+------------------------+
| id| name| email| masked_email |
+---+------------+------------------------+------------------------+
| 1| John Doe| john.doe@example.com | j*******e@example.com |
| 2| Alice Smith|alice.smith@company.com |a**********h@company.com|
| 3| Bob Jones| bob.jones@email.org | b********s@email.org |
+---+------------+------------------------+------------------------+
모범 사례
모든 사용자가 UDF에 액세스할 수 있도록 Databricks는 적절한 액세스 제어를 사용하여 전용 카탈로그 및 스키마를 만드는 것이 좋습니다.
팀별 UDF의 경우 스토리지 및 관리를 위해 팀 카탈로그 내에서 전용 스키마를 사용합니다.
Databricks는 UDF 문서 문자열에 다음 정보를 포함하도록 권장합니다.
- 현재 버전 번호
- 버전 간 수정 내용을 추적하는 변경 로그
- UDF 용도, 매개 변수 및 반환 값
- UDF를 사용하는 방법의 예
다음 예제에서는 모범 사례를 따르는 UDF를 보여 줍니다.
CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
COMMENT "Calculates Body Mass Index (BMI) from weight and height."
LANGUAGE PYTHON
DETERMINISTIC
AS $$
"""
Parameters:
calculate_bmi (version 1.2):
- weight_kg (float): Weight of the individual in kilograms.
- height_m (float): Height of the individual in meters.
Returns:
- float: The calculated BMI.
Example Usage:
SELECT calculate_bmi(weight, height) AS bmi FROM person_data;
Change Log:
- 1.0: Initial version.
- 1.1: Improved error handling for zero or negative height values.
- 1.2: Optimized calculation for performance.
Note: BMI is calculated as weight in kilograms divided by the square of height in meters.
"""
if height_m <= 0:
return None # Avoid division by zero and ensure height is positive
return weight_kg / (height_m ** 2)
$$;
한 번에 행 단위 입력에 대한 타임스탬프 타임존 동작
TIMESTAMP 입력은 UTC 기준의 타임존 비지정 datetime 값으로 한 번에 한 행씩 처리하는 Python UDF에 전달됩니다. 클래식 컴퓨트에서는 이 동작이 Databricks Runtime 18.1 이상이어야 합니다. 서버리스 컴퓨트와 프로 및 서버리스 SQL 웨어하우스에서는 UDF의 environment_version를 명시적으로 6 이상으로 설정하세요. 객체는 datetime 속성에 tzinfo 시간대 메타데이터를 포함하지 않습니다.
배치 Unity Catalog Python UDF는 타임스탬프 입력을 pandas.Series 객체로 받으며 이 datetime 매핑을 사용하지 않습니다.
이 변경으로 Unity 카탈로그 Python UDF가 Apache Spark의 화살표 최적화 Python UDF와 일치합니다.
예를 들어, 다음 쿼리는 환경 버전 6과 세션 시간대를 UTC로 명시적으로 설정합니다:
SET TIME ZONE 'UTC';
CREATE FUNCTION timezone_udf(date TIMESTAMP)
RETURNS STRING
LANGUAGE PYTHON
ENVIRONMENT (
environment_version = '6'
)
AS $$
return f"{type(date)} {date} {date.tzinfo}"
$$;
SELECT timezone_udf(TIMESTAMP '2024-10-23 10:30:00');
이전 실행 경로는 세션 시간대 기준의 시간대 정보가 포함된 값을 반환합니다. 이는 Databricks Runtime 18.1 이전의 클래식 컴퓨트에서 적용됩니다. 서버리스 컴퓨트와 프로 및 서버리스 SQL 웨어하우스에서도 ENVIRONMENT 절을 생략하거나, environment_version = 'None'을 설정하거나, 6보다 이전 버전을 선택하는 경우에도 적용됩니다. 세션 시간대를 UTC로 설정했을 때, 이전 경로는 다음과 같습니다:
<class 'datetime.datetime'> 2024-10-23 10:30:00+00:00 UTC
설명된 정의에 따르면, 서버리스 컴퓨트와 프로 및 서버리스 SQL 웨어하우스는 PySpark 호환 동작을 사용합니다. Databricks Runtime 18.1 이상을 실행하는 클래식 컴퓨트도 다음 절을 조정하거나 생략 ENVIRONMENT 할 때 동일한 동작을 사용합니다:
<class 'datetime.datetime'> 2024-10-23 10:30:00 None
이 변경은 클럭 필드뿐만 아니라 tzinfo에도 영향을 미칠 수 있습니다. 순간 2024-10-23T10:30:00Z의 경우, America/Los_Angeles 세션에서의 이전 동작은 2024-10-23 03:30:00-07:00를 생성합니다. 새로운 동작은 시간대 순응 UTC 값을 2024-10-23 10:30:00생성합니다.
만약 UDF가 시간대 정보에 의존한다면, UTC를 명시적으로 복원하세요:
from datetime import timezone
date = date.replace(tzinfo=timezone.utc)
UTC 시간대 정보를 추가해도 이전의 세션-로컬 클럭 필드는 복원되지 않습니다. 로직에 해당 필드가 필요하다면, 인식 값도 의도한 세션 시간대로 변환하세요. 다음은 그 예입니다.
from zoneinfo import ZoneInfo
date = date.astimezone(ZoneInfo("America/Los_Angeles"))
제한 사항
- Python UDF 내에서 원하는 수의 Python 함수를 정의할 수 있지만 모두 스칼라 값을 반환해야 합니다.
- Python 함수는 NULL 값을 독립적으로 처리해야 하며 모든 형식 매핑은 Azure Databricks SQL 언어 매핑을 따라야 합니다.
- 카탈로그 또는 스키마를 지정하지 않으면 Azure Databricks Python UDF를 현재 활성 스키마에 등록합니다.
- Python UDF는 안전하고 격리된 환경에서 실행되며 파일 시스템 또는 내부 서비스에 액세스할 수 없습니다.
- Databricks Runtime 18.1 이상을 실행하는 클래식 컴퓨트에서는 쿼리에서 5개 이상의 UDF를 호출할 수 있습니다. 서버리스 컴퓨트 및 프로와 서버리스 SQL 웨어하우스에서는 각 UDF 정의에서
6을(를)environment_version이상으로 명시적으로 설정해야 합니다.