Unity 카탈로그의 UDF(사용자 정의 함수)

아티클
10/25/2024

Important

이 기능은 공개 미리 보기 상태입니다.

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

Unity 카탈로그에 함수로 등록된 Python UDF는 범위가 다르며 Notebook 또는 SparkSession으로 범위가 지정된 PySpark UDF의 지원도 다릅니다. 사용자 정의 스칼라 함수 - Python을 참조하세요.

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

요구 사항

Unity 카탈로그에서 UDF를 사용하려면 다음 요구 사항을 충족해야 합니다.

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

Unity 카탈로그에서 UDF 만들기

Unity 카탈로그에서 UDF를 만들려면 사용자는 카탈로그에 대한 스키마 및 USAGE 권한에 대한 USAGE 및 CREATE 권한이 필요합니다. 자세한 내용은 Unity 카탈로그를 참조하세요.

UDF를 실행하려면 UDF에 대한 EXECUTE 권한이 필요합니다. 또한 사용자는 스키마 및 카탈로그에 대한 USAGE 권한이 필요합니다.

다음 예제에서는 Unity 카탈로그 스키마에 새 함수를 my_schema 등록합니다.

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는 이중 달러 기호($$)로 오프셋된 문을 사용합니다. 또한 데이터 형식 매핑을 지정해야 합니다. 다음 예제에서는 체질량 인덱스를 계산하는 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 카탈로그 함수를 사용할 수 있습니다.

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

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}!"
$$

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

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

작업 영역 UI의 권한

UDF가 저장되는 카탈로그 및 스키마를 찾아서 UDF를 선택합니다.
UDF 설정에서 사용 권한 옵션을 찾습니다. 사용자 또는 그룹을 추가하고 EXECUTE 또는 MANAGE와 같은 액세스 유형을 지정합니다.

! [작업 영역 UI의 사용 권한](.. /_static/images/udf/high res udf permission.gif)

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;

UDF 모범 사례

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

팀별 UDF의 경우 스토리지 및 관리를 위해 팀 카탈로그 내의 전용 스키마를 사용합니다.

Azure 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
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 요청을 만듭니다.

참고 항목

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()
   # 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 값을 독립적으로 처리해야 하며 모든 형식 매핑은 Azure Databricks SQL 언어 매핑을 따라야 합니다.
Azure Databricks에 포함된 표준 Python 라이브러리를 가져올 수 있지만 사용자 지정 라이브러리 또는 외부 종속성은 포함할 수 없습니다.
카탈로그 또는 스키마를 지정하지 않으면 Python UDF가 현재 활성 스키마에 등록됩니다.
Python UDF는 안전하고 격리된 환경에서 실행되며 파일 시스템 또는 내부 서비스에 액세스할 수 없습니다.

다음을 통해 공유

Unity 카탈로그의 UDF(사용자 정의 함수)

요구 사항

Unity 카탈로그에서 UDF 만들기

PySpark에서 Unity 카탈로그 UDF 사용

세션 범위 UDF 업그레이드

작업 영역 UI의 권한

Azure Databricks SQL을 사용하는 권한

UDF 모범 사례

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

보안 및 규정 준수를 위한 UDF

제한 사항

피드백

추가 리소스

다음을 통해 공유

Unity 카탈로그의 UDF(사용자 정의 함수)

요구 사항

Unity 카탈로그에서 UDF 만들기

PySpark에서 Unity 카탈로그 UDF 사용

세션 범위 UDF 업그레이드

Unity 카탈로그에서 UDF 공유

작업 영역 UI의 권한

Azure Databricks SQL을 사용하는 권한

UDF 모범 사례

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

보안 및 규정 준수를 위한 UDF

제한 사항

피드백

추가 리소스