Unity Catalog のユーザー定義関数 (UDF)
プレビュー
この機能はパブリックプレビュー段階です。
Unity Catalog のユーザー定義関数 (UDF) は、Databricks 内の SQL と Python の機能を拡張します。 これにより、カスタム関数を定義し、使用し、コンピューティング環境全体で安全に共有および管理できます。
Unity Catalog で関数として登録された Python UDF は、ノートブックまたは SparkSession をスコープとする PySpark UDF とはスコープとサポートが異なります。ユーザー定義スカラー関数 - Python を参照してください。
完全な SQL 言語リファレンスについては、 CREATE FUNCTION (SQL と Python) を参照してください。
要件
Unity Catalog で UDF を使用するには、次の要件を満たす必要があります。
Databricks Runtime 14.1 以上。
Unity Catalog に登録されている UDF で Python コードを使用するには、プロ SQL ウェアハウスまたは Databricks Runtime14.1 以上を実行しているクラスターを使用する必要があります。
Unity Catalog に登録された UDF を使用して作成されたビューを解決するには、Databricks Runtime 14.1 以降を使用する必要があります。 SQLウェアハウスは使用できません。
Unity Catalog での UDF の作成
Unity Catalog で UDF を作成するには、スキーマに対する USAGE 権限と CREATE 権限、およびカタログに対する USAGE 権限が必要です。 詳細については、 Unity Catalog を参照してください。
UDF を実行するには、UDF に対する EXECUTE 権限が必要です。 ユーザーには、スキーマとカタログに対する USAGE 権限も必要です。
次の例では、新しい関数を my_schema
Unity Catalog スキーマに登録します。
CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight DOUBLE, height DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
AS
SELECT weight / (height * height);
Unity Catalog の 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)
$$;
これで、この Unity Catalog 関数を SQL クエリまたは PySpark コードで使用できるようになりました。
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 のアップグレード
注
Unity Catalog の Python UDF の構文とセマンティクスは、SparkSession に登録されている Python UDF とは異なります。 ユーザー定義のスカラー関数 - Pythonを参照してください。
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}!"
$$
外部APIs にアクセスするための UDFs
UDFs を使用して、APIs から外部SQL にアクセスできます。次の例では、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 UDFs を使用して、カスタムトークン化、データマスキング、データ編集、または暗号化メカニズムを実装します。
次の例では、Eメール アドレスの 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 値を個別に処理する必要があり、すべての型マッピングは Databricks SQL 言語マッピングに従う必要があります。
Databricks に含まれる標準の Python ライブラリをインポートすることはできますが、カスタム ライブラリや外部依存関係を含めることはできません。
カタログまたはスキーマが指定されていない場合、Python UDF は現在アクティブなスキーマに登録されます。
Python UDF は安全で分離された環境で実行され、ファイルシステムや内部サービスにアクセスできません。