Freigeben über

Benutzerdefinierte Funktionen (UDFs) in Unity Catalog

  • Artikel

Wichtig

Dieses Feature befindet sich in der Public Preview.

Benutzerdefinierte Funktionen (USER-Defined Functions, UDFs) im Unity-Katalog erweitern die Funktionen von SQL und Python innerhalb von Azure Databricks. Sie ermöglichen es, benutzerdefinierte Funktionen für computerübergreifende Umgebungen zu definieren, zu verwenden und sicher gemeinsam zu nutzen und zu regeln.

Python-UDFs, die in Unity Catalog als Funktionen registriert sind, unterscheiden sich in Umfang und Unterstützung von PySpark-UDFs, die einem Notebook-Bereich oder SparkSession zugeordnet sind. Weitere Informationen finden Sie unter Benutzerdefinierte Skalarfunktionen: Python.

Eine vollständige SQL-Sprachreferenz finden Sie unter CREATE FUNCTION (SQL und Python ).

Anforderungen

Um UDFs im Unity-Katalog zu verwenden, müssen die folgenden Anforderungen erfüllt sein:

  • Um Python-Code in UDFs zu verwenden, die im Unity-Katalog registriert sind, müssen Sie ein serverloses oder pro SQL Warehouse oder einen Cluster mit Databricks Runtime 13.3 LTS oder höher verwenden.
  • Wenn eine Ansicht eine UC Python UDF enthält, schlägt sie in SQL Classic Warehouses fehl.

Erstellen von UDFs im Unity-Katalog

Um eine UDF im Unity-Katalog zu erstellen, benötigen Benutzer VERWENDUNGs- und CREATE-Berechtigung für das Schema und die VERWENDUNGsberechtigung für den Katalog. Weitere Details finden Sie im Unity-Katalog .

Um eine UDF auszuführen, benötigen Benutzer EXECUTE-Berechtigungen für die UDF. Benutzer benötigen auch die VERWENDUNGsberechtigung für das Schema und den Katalog.

Im folgenden Beispiel wird eine neue Funktion im my_schema Unity-Katalogschema registriert:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight DOUBLE, height DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
AS
SELECT weight / (height * height);

Python UDFs für Unity Catalog verwenden Anweisungen, die durch doppelte Dollarzeichen ($$) versetzt werden. Sie müssen auch eine Datentypzuordnung angeben. Im folgenden Beispiel wird ein UDF registriert, das den Body-Massenindex berechnet:

CREATE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
return weight_kg / (height_m ** 2)
$$;

Sie können diese Unity-Katalogfunktion jetzt in Ihren SQL-Abfragen oder PySpark-Code verwenden:

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

Verwenden des Unity-Katalog-UDF in PySpark

from pyspark.sql.functions import expr

result = df.withColumn("bmi", expr("my_catalog.my_schema.calculate_bmi(weight_kg, height_m)"))
display(result)

Upgrade einer sitzungsbezogenen UDF

Hinweis

Syntax und Semantik für Python-UDFs in Unity Catalog unterscheiden sich von Python-UDFs, die für SparkSession registriert sind. Siehe benutzerdefinierte skalare Funktionen – Python.

Aufgrund der folgenden sitzungsbasierten UDF in einem Azure Databricks-Notizbuch:

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()

Um dies als Unity-Katalogfunktion zu registrieren, verwenden Sie wie im folgenden Beispiel eine SQL-Anweisung CREATE FUNCTION :

CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
return f"Hello, {name}!"
$$

Freigeben von UDFs im Unity-Katalog

Berechtigungen für UDFs werden basierend auf den Zugriffssteuerelementen verwaltet, die auf den Katalog, das Schema oder die Datenbank angewendet werden, in denen die UDF registriert ist. Weitere Informationen finden Sie im Unity-Katalog .

Verwenden Sie die Azure Databricks SQL- oder azure Databricks-Arbeitsbereich-UI, um Einem Benutzer oder einer Gruppe Berechtigungen zu erteilen (empfohlen).

Berechtigungen in der Arbeitsbereich-UI

  1. Suchen Sie den Katalog und das Schema, in dem Ihre UDF gespeichert ist, und wählen Sie die UDF aus.
  2. Suchen Sie in den UDF-Einstellungen nach einer Berechtigungsoption . Fügen Sie Benutzer oder Gruppen hinzu, und geben Sie den Typ des Zugriffs an, über den sie verfügen sollen, z. B. EXECUTE oder MANAGE.

! [Berechtigungen in arbeitsbereichs-UI](.. /_static/images/udf/high res udf permission.gif)

Berechtigungen mit Azure Databricks SQL

Im folgenden Beispiel wird einem Benutzer die EXECUTE-Berechtigung für eine Funktion gewährt:

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

Um Berechtigungen zu entfernen, verwenden Sie den REVOKE Befehl wie im folgenden Beispiel:

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

Bewährte Methoden für UDFs

Für UDFs, die für alle Benutzer zugänglich sein müssen, empfiehlt Databricks das Erstellen eines dedizierten Katalogs und Schemas mit entsprechenden Zugriffssteuerelementen.

Verwenden Sie für teamspezifische UDFs ein dediziertes Schema im Teamkatalog für Speicher und Verwaltung.

Azure Databricks empfiehlt, die folgenden Informationen in die Dokumentzeichenfolge der UDF aufzunehmen:

  • Die aktuelle Versionsnummer
  • Ein Änderungsprotokoll zum Nachverfolgen von Änderungen in allen Versionen
  • Zweck, Parameter und Rückgabewert der UDF
  • Ein Beispiel für die Verwendung der UDF

Nachfolgend sehen Sie ein Beispiel für eine UDF mit den folgenden bewährten Methoden:

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

UDFs für den Zugriff auf externe APIs

Sie können UDFs verwenden, um über SQL auf externe APIs zuzugreifen. Im folgenden Beispiel wird die Python-Bibliothek requests verwendet, um eine HTTP-Anforderung zu erstellen.

Hinweis

Python UDFs ermöglichen TCP/UDP-Netzwerkdatenverkehr über die Ports 80, 443 und 53 mit serverlosem Compute oder Compute, der mit dem modus für gemeinsam genutzten Zugriff konfiguriert ist.

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

$$;

UDFs für Sicherheit und Compliance

Verwenden Sie Python UDFs, um benutzerdefinierte Tokenisierung, Datenmasken, Daten redaction oder Verschlüsselungsmechanismen zu implementieren.

Im folgenden Beispiel wird die Identität einer E-Mail-Adresse maskiert, während Länge und Domäne beibehalten werden:

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

Im folgenden Beispiel wird diese UDF in einer dynamischen Ansichtsdefinition angewendet:

-- 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 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 |
+---+------------+------------------------+------------------------+

Begrenzungen

  • Sie können eine beliebige Anzahl von Python-Funktionen innerhalb einer Python-UDF definieren, aber alle müssen einen skalaren Wert zurückgeben.
  • Python-Funktionen müssen NULL-Werte unabhängig verarbeiten, und alle Typzuordnungen müssen Azure Databricks SQL-Sprachzuordnungen folgen.
  • Sie können standardmäßige Python-Bibliotheken importieren, die in Azure Databricks enthalten sind. Benutzerdefinierte Bibliotheken oder externe Abhängigkeiten können jedoch nicht einbezogen werden.
  • Wenn kein Katalog oder Schema angegeben ist, werden Python-UDFs für das aktuelle aktive Schema registriert.
  • Python-UDFs werden in einer sicheren, isolierten Umgebung ausgeführt und haben keinen Zugriff auf Dateisysteme oder interne Dienste.