メインコンテンツまでスキップ

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 を使用するには、次の要件を満たす必要があります。

  • Pythonに登録された UDF でUnity Catalog コードを使用するには、サーバレスまたはプロSQL の ウェアハウスを使用するか、13.3Databricks Runtime LTS以降 実行しているクラスタリングを使用する必要があります。
  • ビューに UC Python UDFが含まれている場合、 SQL Classic ウェアハウスでは失敗します。
  • GravitonScala有効なクラスターでの UDF の インスタンスのサポートは、Databricks Runtime 15.2 以降で使用できます。

Unity Catalog での UDF の作成​

Unity Catalog で UDF を作成するには、スキーマに対する USAGE 権限と CREATE 権限、およびカタログに対する USAGE 権限が必要です。 詳細については、 Unity Catalog を参照してください。

UDF を実行するには、UDF に対する EXECUTE 権限が必要です。 ユーザーには、スキーマとカタログに対する USAGE 権限も必要です。

次の例では、新しい関数を my_schema Unity Catalog スキーマに登録します。

SQL
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 を登録するとします。

SQL
CREATE OR REPLACE 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 コードで使用できるようになりました。

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

カスタムの依存関係を使用した UDF の拡張​

備考

プレビュー

この機能は パブリック プレビュー段階です。

Unity Catalog Python UDFs の機能を Databricks Runtime 環境を超えて拡張するには、外部ライブラリのカスタム依存関係を定義します。

次のソースから依存関係をインストールします。

  • PyPi パッケージ
  • Unity Catalog ボリュームに格納されたファイル UDF を呼び出すユーザーは、ソース ボリュームに対する READ VOLUME アクセス許可を持っている必要があります。
  • 公開URLで利用可能なファイル ワークスペースのネットワーク セキュリティ規則で、公開 URL へのアクセスを許可する必要があります。
注記

サーバレス SQLウェアハウスからパブリック URL へのアクセスを許可するようにネットワーク セキュリティ規則を構成するには、Databricks SQLでの検証を参照してください

Unity Catalog UDF のカスタム依存関係は、次のコンピュートタイプでサポートされています。

  • サーバーレスコンピュート
  • Databricks Runtimeバージョン16.2以上を使用した汎用コンピュート
  • SQLウェアハウス クラシックまたはプロ

UDF 定義の ENVIRONMENT セクションを使用して、依存関係を指定します。

SQL
CREATE OR REPLACE FUNCTION my_catalog.my_schema.mixed_process(data STRING)
RETURNS STRING
LANGUAGE PYTHON
ENVIRONMENT (
  dependencies = '["simplejson==3.19.3", "/Volumes/my_catalog/my_schema/my_volume/packages/custom_package-1.0.0.whl", "https://my-bucket.s3.amazonaws.com/packages/special_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]',
  environment_version = 'None'
)
AS $$
import simplejson as json
import custom_package
return json.dumps(custom_package.process(data))
$$;

ENVIRONMENT セクションには、次のフィールドが含まれています。

フィールド

説明

タイプ

使用例

dependencies

STRING

インストールするコンマ区切りの依存関係の一覧。各エントリは、 pip Requirements File Format に準拠した文字列です。

dependencies = '["simplejson==3.19.3", "/Volumes/catalog/schema/volume/packages/my_package-1.0.0.whl"]'

dependencies = '["https://my-bucket.s3.amazonaws.com/packages/my_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]'

environment_version

STRING

UDFを実行するサーバレス環境のバージョンを指定します。

現在、値 None のみがサポートされています。

environment_version = 'None'

PySpark での Unity Catalog UDF の使用​

Python
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 があるとします。

Python
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 ステートメントを使用します。

SQL
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 が登録されているカタログ、スキーマ、またはデータベースに適用されるアクセス制御に基づいて管理されます。 詳細については、Unity Catalogを参照してください。

Databricks SQL または Databricks ワークスペース UI を使用して、ユーザーまたはグループにアクセス許可を付与します (推奨)。

ワークスペース UI のアクセス許可​

  1. UDF が格納されているカタログとスキーマを検索し、UDF を選択します。
  2. UDF 設定で アクセス許可 オプションを探します。 ユーザーまたはグループを追加し、EXECUTE や MANAGE など、必要なアクセスのタイプを指定します。

ワークスペース UI の権限

Databricks SQL を使用したアクセス許可​

次の例では、関数に対する EXECUTE パーミッションをユーザーに付与します。

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

アクセス許可を削除するには、次の例のように REVOKE コマンドを使用します。

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

UDF のベスト プラクティス​

すべてのユーザーが UDF にアクセスできるようにするために、Databricks では、適切なアクセス制御を備えた専用のカタログとスキーマを作成することをお勧めします。

チーム固有の UDF の場合は、チームのカタログ内でストレージと管理に専用のスキーマを使用します。

Databricks では、UDF の docstring に次の情報を含めることをお勧めします。

  • 現在のバージョン番号
  • バージョン間での変更を追跡するための変更ログ
  • UDF の目的、パラメーター、および戻り値
  • UDF の使用方法の例

以下は、ベストプラクティスに従った UDF の例です。

SQL
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)
$$;

AI エージェント ツールの UDFs​

生成AI エージェントは、 Unity Catalog UDF をタスクの実行およびカスタムロジックの実行のためのツールとして使用できます。

Unity Catalog 関数を使用したカスタム AI エージェント ツールの作成を参照してください。

外部APIにアクセスするための UDF​

UDF を使用して、SQLから外部API にアクセスできます。次の例では、Python requests ライブラリを使用して HTTP リクエストを行います。

注記

Python UDF は、サーバレス コンピュートまたは標準アクセス モードで設定されたコンピュートを使用して、ポート 80、443、および 53 を介した TCP/UDP ネットワーク トラフィックを許可します。

SQL
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 を使用して、カスタムトークン化、データマスキング、データ編集、または暗号化メカニズムを実装します。

次の例では、Eメール アドレスの ID をマスクしながら、長さとドメインを維持します。

SQL
CREATE OR REPLACE FUNCTION my_catalog.my_schema.mask_email(email STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
parts = email.split('@')
masked_username = parts[0][0] + '*' * (len(parts[0]) - 2) + parts[0][-1]
return f"{masked_username}@{domain}"
$$

次の例では、この UDF を動的ビュー定義に適用します。

SQL
-- 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 masked_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 言語マッピングに従う必要があります。
  • カタログまたはスキーマが指定されていない場合、Python UDF は現在アクティブなスキーマに登録されます。
  • Python UDF は、安全で分離された環境で実行され、ファイルシステムや内部サービスにはアクセスできません。
  • クエリごとに 5 つを超える UDF を呼び出すことはできません。
に最終更新