Unity 目錄中的使用者定義函式 （UDF）

Unity 目錄中的使用者定義函式 （UDF） 會擴充 Azure Databricks 內的 SQL 和 Python 功能。 它們可讓自定義函式在運算環境中定義、使用及安全地共用及控管。

在 Unity 目錄中註冊為函式的 Python UDF 在範圍與 PySpark UDF 的範圍和支援不同之處在於筆記本或 SparkSession。 請參閱使用者定義的純量函式 - 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 和 CREATE 許可權和 USAGE 許可權。 如需詳細資訊，請參閱 Unity 目錄 。

若要執行 UDF，使用者需要 UDF 的 EXECUTE 許可權。 使用者也需要架構和目錄的USAGE許可權。

下列範例會將新的函式註冊至 my_schema Unity 目錄架構：

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

在 Azure Databricks 筆記本中指定下列會話型 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 目錄中共用 UDF

UDF 的許可權是根據套用至 UDF 註冊之目錄、架構或資料庫的訪問控制來管理。 如需詳細資訊，請參閱 Unity 目錄 。

使用 Azure Databricks SQL 或 Azure Databricks 工作區 UI 來授與使用者或群組的許可權（建議）。

工作區 UI 中的許可權

1. 尋找儲存 UDF 的目錄和架構，然後選取 UDF。
2. 在 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;

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 要求。

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 來實作自定義令牌化、數據遮罩、數據修訂或加密機制。

下列範例會遮罩電子郵件位址的身分識別，同時維持長度和網域：

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 會在安全、隔離的環境中執行，而且無法存取檔系統或內部服務。