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

プレビュー

Databricks は、Unity Catalog によって管理されるスキーマにカスタム関数を登録するための SQL ネイティブ構文を提供します。 Unity Catalog に関数として登録された Python UDF は、ノートブックまたは SparkSession にスコープが設定された PySpark UDF とはスコープとサポートが異なります。「ユーザー定義スカラー関数 - Python」を参照してください。

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

Unity Catalog で関数のアクセス許可を管理する方法については、「関数の作成」を参照してください。

要件

Databricks Runtime 13.3 LTS 以上。
Unity Catalog に登録されている UDF で Python コードを使用するには、サーバーレスまたは pro SQL ウェアハウス、あるいはDatabricks Runtime 13.3 LTS 以上を実行しているクラスターを使用する必要があります。
Unity Catalog に登録された UDF を使用して作成されたビューを解決するには、サーバーレスまたは pro SQL ウェアハウスを使用する必要があります。
Unity Catalog 対応クラスター上の Scala UDF に対する Graviton インスタンスのサポートは、Databricks Runtime 15.2 以降で利用できます。

Unity Catalog のカスタム SQL 関数

Unity Catalog用に構成されたコンピュートを使用してSQL関数を作成すると、その関数はデフォルトで現在アクティブなスキーマに登録されます。次の例は、新しい関数のターゲットカタログとスキーマを宣言するために使用できる構文を示しています。

CREATE FUNCTION target_catalog.target_schema.roll_dice()
    RETURNS INT
    LANGUAGE SQL
    NOT DETERMINISTIC
    CONTAINS SQL
    COMMENT 'Roll a single 6 sided die'
    RETURN (rand() * 6)::INT + 1;

関数に対する十分な権限を持つすべてのユーザーは、次の例のように、Unity Catalog用に構成されたコンピュート環境で関数を使用できます。

SELECT target_catalog.target_schema.roll_dice()

注

LANGUAGE SQL を使っている UDF を使用して、テーブルまたはスカラー値を返すことができます。

Python UDF を Unity Catalog に登録する

Databricks Runtime 13.3 LTS以降では、 SQL CREATE FUNCTION ステートメントを使用して、スカラーPython UDF をUnity Catalogに登録できます。

重要

SQLウェアハウスを使用してPython UDFs in Unity Catalogを登録する場合、その SQL ウェアハウスは Pro またはサーバーレスSQLウェアハウスである必要があります。

Python UDF は、SQL 関数内で直接 Python の完全な表現力を提供するように設計されており、高度な変換、データマスキング、ハッシュなどのカスタマイズされた操作を可能にします。

Python UDF は安全で分離された環境で実行され、ファイルシステムや内部サービスにアクセスできません。

Databricks Runtime 13.3 LTSから 14.2 では、サーバーレスコンピュートまたは共有アクセスモードで実行されているPython UDF により、ポート 80、443、および 53 経由の TCP/UDP ネットワークトラフィックが許可されます。

「どの UDF が最も効率的か」を参照してください。

注

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

Unity Catalog 用の Python UDF は、次のコード例のように、二重ドル記号 ($$) で設定されたステートメントを使用します。

CREATE FUNCTION target_catalog.target_schema.greet(s STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
  return f"Hello, {s}"
$$

次の例は、この関数を使用して、 studentsという名前のテーブルの first_name 列に格納されているすべての名前のあいさつ文を返す方法を示しています。

SELECT target_catalog.target_schema.greet(first_name)
FROM students;

Python UDF 内で任意の数の Python 関数を定義できますが、スカラー値を返す必要があります。

Python 関数は NULL 値を個別に処理する必要があり、すべての型マッピングは Databricks SQL 言語マッピングに従う必要があります。

Databricks に含まれる標準の Python ライブラリをインポートすることはできますが、カスタムライブラリや外部依存関係を含めることはできません。

カタログまたはスキーマが指定されていない場合、Python UDF は現在アクティブなスキーマに登録されます。

次の例では、ライブラリをインポートし、Python UDF 内で複数の関数を使用します。

CREATE FUNCTION roll_dice(num_dice INTEGER, num_sides INTEGER)
RETURNS INTEGER
LANGUAGE PYTHON
AS $$
  import numpy as np

  def roll_die(num_sides):
    return np.random.randint(num_sides) + 1

  def sum_dice(num_dice,num_sides):
    return sum([roll_die(num_sides) for x in range(num_dice)])

  return sum_dice(num_dice, num_sides)
$$