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

重要

この機能はパブリックプレビュー段階であり、Databricks Runtime 13.3 LTS 以上が必要です。

Databricks は、Unity Catalog によって管理されるスキーマにカスタム関数を登録するための SQL ネイティブ構文を提供します。標準のCREATE FUNCTIONSQL 構文は、上のすべてのUnity Catalog ピュートに対してサポートされています。Databricksプロまたはサーバーレス SQL ウェアハウスおよびDatabricks Runtime 13.3LTS 以降では、Python に登録された関数にUnity Catalog コードを含めることができます。

Graviton インスタンスでは、Unity Catalog 対応クラスターの UDF はサポートされていません。

注

UDF を使用するクエリから登録されたビューでは、サポートされているコンピュートを使用する必要があります。 Classic SQLウェアハウスおよびDatabricks Runtime 12.2 LTS以下では、 Unity Catalogに登録されたUDFを含むビューを解決できません。

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

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

重要

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

重要

UDF および UDAF は、共有アクセスモードおよび Unity Catalogで構成された Graviton クラスタではサポートされません。

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 を使用して、テーブルまたはスカラー値を返すことができます。

登録する a Python UDF to Unity Catalog

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

重要

Pro とサーバレス SQLウェアハウスのみが Python UDF for Unity Catalog をサポートしています。

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

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

サーバレスコンピュート上または共有アクセスモードで実行されている 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)
$$