ユーザー定義関数 (UDF) とは何ですか?

ユーザー定義関数 (UDF) を使用すると、Databricks の組み込み機能を拡張するコードを再利用および共有できます。 UDFs を使用して、複雑な計算、変換、カスタムデータ操作などの特定のタスクを実行します。

注

共有アクセスモードのクラスターでは、Python スカラー UDF は Databricks Runtime 13.3 LTS 以降でサポートされ、Scala UDF は Databricks Runtime 14.2 以降でサポートされます。

Python スカラー UDF は、Databricks Runtime 13.3 LTS 以降の SQL 構文を使用して Unity Catalog に登録できます。「Unity Catalog のユーザー定義関数 (UDF)」を参照してください。

どのような場合に UDF を使用する必要がありますか?

UDFs は、組み込みの Apache Spark 関数では表現しにくいロジックに使用します。組み込みの Apache Spark 関数は、分散処理用に最適化されており、一般に、大規模でより優れたパフォーマンスを提供します。詳細については、「関数」を参照してください。

Databricks では、アドホッククエリ、手動データクレンジング、探索的データ分析、および小規模から中規模のデータセットに対する操作に UDF を推奨しています。 UDF の一般的なユースケースには、データの暗号化と復号化、ハッシュ化、JSON 解析、検証などがあります。

Apache Spark メソッドは、非常に大規模なデータセットや、ETL ジョブやストリーミング操作など、定期的または継続的に実行されるワークロードに対する操作に使用します。

登録済みおよびセッションスコープの UDF

SQL を使用して作成された UDF は Unity Catalog に登録され、アクセス許可が関連付けられていますが、ノートブック内で作成された UDF はセッションベースであり、現在の SparkSession にスコープが設定されます。

セッションベースの UDF は、Databricks でサポートされている任意の言語を使用して定義し、アクセスできます。 UDF は、スカラーまたは非スカラーにすることができます。

注

現在、DBSQL で使用できるのは、Unity Catalog に登録されている SQL と Python のスカラー UDF のみです。

スカラー UDF

スカラー UDF は 1 つの行で動作し、各行に対して 1 つの値を返します。次の例では、スカラー UDF を使用して、 name 列の各名前の長さを計算し、新しい列 name_lengthに値を追加します。

+-------+-------+
| name  | score |
+-------+-------+
| alice |  10.0 |
| bob   |  20.0 |
| carol |  30.0 |
| dave  |  40.0 |
| eve   |  50.0 |
+-------+-------+

-- Create a SQL UDF for name length
CREATE OR REPLACE FUNCTION get_name_length(name STRING)
RETURNS INT
RETURN LENGTH(name);

-- Use the UDF in a SQL query
SELECT name, get_name_length(name) AS name_length
FROM your_table;

+-------+-------+-------------+
| name  | score | name_length |
+-------+-------+-------------+
| alice |  10.0 |      5      |
|  bob  |  20.0 |      3      |
| carol |  30.0 |      5      |
| dave  |  40.0 |      4      |
|  eve  |  50.0 |      3      |
+-------+-------+-------------+

これを PySpark を使用して Databricks ノートブックに実装するには、次のようにします。

from pyspark.sql.functions import udf
from pyspark.sql.types import IntegerType


@udf(returnType=IntegerType())
def get_name_length(name):
   return len(name)

df = df.withColumn("name_length", get_name_length(df.name))

# Show the result
display(df)

詳細については、Unity Catalogのユーザー定義関数 (UDFs) およびユーザー定義スカラー関数 - Pythonを参照してください。

ユーザー定義の集計関数 (UDAFs)

ユーザー定義の集計関数 (UDAFs) は、複数の行を操作し、1 つの集計結果を返します。次の例では、スコアを集計する UDAF が定義されています。

from pyspark.sql.functions import pandas_udf
from pyspark.sql import SparkSession
import pandas as pd

# Define a pandas UDF for aggregating scores
@pandas_udf("int")
def total_score_udf(scores: pd.Series) -> int:
    return scores.sum()

# Group by name length and aggregate
result_df = (df.groupBy("name_length")
              .agg(total_score_udf(df["score"]).alias("total_score")))

display(result_df)

+-------------+-------------+
| name_length | total_score |
+-------------+-------------+
|      3      |     70.0    |
|      4      |     40.0    |
|      5      |     40.0    |
+-------------+-------------+

PandasPythonのユーザー定義関数Scala およびユーザー定義集計関数 - を参照してください。

Python ユーザー定義テーブル関数 (UDTF)

プレビュー

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

注

Python UDTF は、Databricks Runtime 14.3 LTS 以降で使用できます。

Python ユーザー定義テーブル関数 (UDTF) は、入力行ごとに複数の行と列を返すことができます。次の例では、score 列の各値がカテゴリのリストに対応しています。 UDTF は、コンマ区切りのリストを複数の行に分割するために定義されます。 Python ユーザー定義テーブル関数 (UDTFs)を参照してください。

+-------+-------+-----------------+
| name  | score |   categories    |
+-------+-------+-----------------+
| alice |  10.0 |  math,science   |
|  bob  |  20.0 |  history,math   |
| carol |  30.0 | science,history |
| dave  |  40.0 |    math,art     |
|  eve  |  50.0 |  science,art    |
+-------+-------+-----------------+

from pyspark.sql.functions import udtf

@udtf(returnType="score: int, categories: string, name: string")
class ScoreCategoriesUDTF:
    def eval(self, name: str, score: float, categories: str):
        category_list = categories.split(',')
        for category in category_list:
            yield (name, score, category)

# Apply the UDTF
result_df = df.select(ScoreCategoriesUDTF(df.score, df.categories, df.name))
display(result_df)

+-------+-------+----------+
| name  | score | category |
+-------+-------+----------+
| alice |  10.0 |   math   |
| alice |  10.0 | science  |
|  bob  |  20.0 | history  |
|  bob  |  20.0 |   math   |
| carol |  30.0 | science  |
| carol |  30.0 | history  |
| dave  |  40.0 |   math   |
| dave  |  40.0 |   art    |
|  eve  |  50.0 | science  |
|  eve  |  50.0 |   art    |
+-------+-------+----------+

パフォーマンスに関する考慮事項

組み込み関数と SQL UDF は、利用可能な最も効率的なオプションです。
Scala UDFs は、Java 仮想マシン (JVM) 内で実行され、JVM との間でデータを移動するオーバーヘッドを回避するため、一般的に高速です。
Python UDFs と Pandas UDF は、データをシリアル化して JVM から Python インタープリターに移動する必要があるため、Scala UDFs よりも遅くなる傾向があります。 Pandas UDFs は、Apache Arrowを使用してシリアル化コストを削減するため、Python UDFsよりも最大100倍高速です。