次の方法で共有

ユーザー定義関数 (UDF) とは

  • [アーティクル]

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

Note

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

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

UDF を使用する必要がある場合

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

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

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

登録済み UDF とセッション スコープ UDF

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

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

Note

現在、DBSQL では、Unity カタログに登録されている 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 カタログのユーザー定義関数 (UDF) とユーザー定義スカラー関数 ( Python) を参照してください。

ユーザー定義集計関数 (UDAF)

ユーザー定義集計関数 (UDAF) は複数の行で動作し、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    |
+-------------+-------------+

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

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

重要

この機能はパブリック プレビュー段階にあります。

Note

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

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

+-------+-------+-----------------+
| 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 UDF は 通常、Java 仮想マシン (JVM) 内で実行されるため高速であり、JVM との間でデータを移動するオーバーヘッドを回避できます。
  • Python UDF と Pandas UDF は 、データをシリアル化して JVM から Python インタープリターに移動する必要があるため、Scala UDF よりも低速になる傾向があります。 Pandas UDF は、シリアル化コストを削減するために Apache Arrow を使用するため、Python UDF よりも最大 100 倍高速です。