次の方法で共有

Unity Catalog のユーザー定義関数 (UDF)

  • [アーティクル]

重要

この機能はパブリック プレビュー段階にあります。

Unity カタログのユーザー定義関数 (UDF) は、Azure Databricks 内で SQL と Python の機能を拡張します。 これにより、カスタム関数を定義、使用、およびコンピューティング環境間で安全に共有および管理できます。

Unity Catalog の関数として登録されている Python UDF は、スコープとサポートが、ノートブックまたは SparkSession にスコープ指定された PySpark UDF とは異なります。 「ユーザー定義スカラー関数 - Python」を参照してください。

完全な SQL 言語リファレンスについては、 CREATE FUNCTION (SQL および Python) を参照してください。

要件

Unity カタログで UDF を使用するには、次の要件を満たす必要があります。

  • Unity Catalog に登録されている UDF で Python コードを使用するには、サーバーレスまたはプロの SQL ウェアハウスか、Databricks Runtime 13.3 LTS 以上を実行しているクラスターを使用する必要があります。
  • ビューに UC Python UDF が含まれている場合、SQL クラシック ウェアハウスでは失敗します。

Unity カタログでの UDF の作成

Unity カタログで UDF を作成するには、ユーザーには、スキーマに対する USAGE 権限と CREATE 権限、およびカタログに対する USAGE 権限が必要です。 詳細については、 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 Catalog 関数を使用できるようになりました。

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 をアップグレードする

Note

Unity Catalog の Python UDF の構文とセマンティクスは、SparkSession に登録されている Python UDF とは異なります。 ユーザー定義スカラー関数 (Python) を参照してください。

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 カタログ関数として登録するには、次の例のように 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 など) を指定します。

![ワークスペース 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 要求を行います。

Note

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 は、セキュリティで保護された分離された環境で実行され、ファイル システムや内部サービスへのアクセス権は持ちません。