Unity Catalog UDF(사용자 정의 함수)

Unity의 사용자 정의 함수(UDF)는 Azure Databricks 내에서 SQL 및 Python의 기능을 확장합니다. Catalog 이를 통해 컴퓨팅 환경에서 사용자 지정 함수를 정의, 사용 및 안전하게 공유하고 제어할 수 있습니다.

Unity Catalog 함수로 등록된 Python UDF는 범위 및 지원 측면에서 Notebook이나 SparkSession에 범위가 지정된 PySpark UDF와 다릅니다. 사용자 정의 스칼라 함수 - Python을 참조하세요.

전체 SQL 언어 참조는 CREATE FUNCTION(SQL 및 Python) 참조하세요.

요구 사항

Unity CatalogUDF를 사용하려면 다음 요구 사항을 충족해야 합니다.

• Python 코드를 Unity Catalog에 등록된 UDF에서 사용하려면, 서버리스 또는 pro SQL 웨어하우스 혹은 Databricks Runtime 13.3 LTS 이상의 버전을 실행하는 클러스터를 사용해야 합니다.
• 보기에 UC Python UDF가 포함되어 있으면 SQL 클래식 웨어하우스에서 실패합니다.

Unity에서 UDF 생성 Catalog

Unity CatalogUDF를 만들려면 사용자는 schema에 대한 USAGE 및 CREATE 권한과 catalog에 대한 USAGE 권한이 필요합니다. 자세한 내용은 Unity Catalog 참조하세요.

UDF를 실행하려면 UDF에 대한 EXECUTE 권한이 필요합니다. 또한 사용자는 schema 및 catalog에 대한 USAGE 권한이 필요합니다.

다음 예제는 my_schema Unity Catalogschema에 새 함수를 등록하는 방법을 보여줍니다.

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight DOUBLE, height DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
AS
SELECT weight / (height * height);

Unity에서 Python UDF는 더블 달러 기호($$)를 사용하여 Catalog이 offset 문을 사용합니다. 또한 데이터 형식 매핑을 지정해야 합니다. 다음 예제에서는 체질량 인덱스를 계산하는 UDF를 등록합니다.

CREATE 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 Catalog 함수를 사용할 수 있습니다.

SELECT person_id, my_catalog.my_schema.calculate_bmi(weight_kg, height_m) AS bmi
FROM person_data;

PySpark에서 Unity Catalog 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 업그레이드

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 Catalog 함수로 등록하려면 다음 예제와 같이 SQL CREATE FUNCTION 문을 사용합니다.

CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
return f"Hello, {name}!"
$$

Unity Catalog UDF 공유

UDF에 대한 권한은 UDF가 등록될 wherecatalog, schema또는 데이터베이스에 적용되는 액세스 제어를 기반으로 관리됩니다. 자세한 내용은 Unity Catalog 참조하세요.

Azure Databricks SQL 또는 Azure Databricks 작업 영역 UI를 사용하여 사용자 또는 그룹에 권한을 부여합니다(권장).

작업 영역 UI의 권한

1. catalog과 schemawhere를 찾아 UDF가 저장된 후 UDF를 select하십시오.
2. UDF 설정에서 사용 권한 옵션을 찾습니다. 사용자 또는 그룹을 추가하고 EXECUTE 또는 MANAGE와 같은 액세스 유형을 지정합니다.

Azure Databricks SQL을 사용하는 권한

다음 예제에서는 사용자에게 함수에 대한 EXECUTE 권한을 부여합니다.

GRANT EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi TO user@example.com;

remove 권한을 설정하려면, 다음 예제와 같이 REVOKE 명령을 사용하십시오.

REVOKE EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi FROM user@example.com;

UDF 모범 사례

모든 사용자가 액세스할 수 있어야 하는 UDF의 경우 Databricks는 적절한 액세스 제어를 사용하여 전용 catalog 및 schema 만드는 것이 좋습니다.

팀별 UDF의 경우 스토리지 및 관리를 위해 팀 catalog 내의 전용 schema 사용합니다.

Azure Databricks는 UDF의 문서 문자열에 다음 정보를 포함하는 것이 좋습니다.

• 현재 버전 번호
• 버전 간 수정 내용을 추적하는 변경 로그
• UDF의 용도, parameters및 반환 값
• 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
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)
$$;

외부 API에 액세스하기 위한 UDF

UDF를 사용하여 SQL에서 외부 API에 액세스할 수 있습니다. 다음 예제에서는 Python requests 라이브러리를 사용하여 HTTP 요청을 만듭니다.

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()
   # Assuming 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
AS $$
parts = email.split('@')
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 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 |
+---+------------+------------------------+------------------------+

제한 사항

• Python UDF 내에서 원하는 수의 Python 함수를 정의할 수 있지만 모두 스칼라 값을 반환해야 합니다.
• Python 함수는 NULL values 독립적으로 처리해야 하며 모든 형식 매핑은 Azure Databricks SQL 언어 매핑을 따라야 합니다.
• Azure Databricks에 포함된 표준 Python 라이브러리를 가져올 수 있지만 사용자 지정 라이브러리 또는 외부 종속성은 포함할 수 없습니다.
• catalog 또는 schema이 지정되지 않으면, Python UDF는 현재 활성 schema에 등록됩니다.
• Python UDF는 안전하고 격리된 환경에서 실행되며 파일 시스템 또는 내부 서비스에 액세스할 수 없습니다.