Freigeben über

Benutzerdefinierte Funktionen (UDFs) in Unity Catalog

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.

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 Benutzende USAGE- und CREATE-Berechtigungen für das Schema und die USAGE-Berechtigung 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
RETURN
SELECT weight / (height * height);

Python-UDFs für den Unity Catalog verwenden Anweisungen, die durch doppelte Dollarzeichen ($$) versetzt werden. Sie müssen eine Datentypzuordnung angeben. Im folgenden Beispiel wird eine Benutzerdefinierte Funktion (UDF) registriert, die den Körpermasseindex berechnet.

CREATE OR REPLACE 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;

Erweitern von UDFs mithilfe von benutzerdefinierten Abhängigkeiten

Wichtig

Dieses Feature befindet sich in der Public Preview.

Erweitern Sie die Funktionalität von Unity Catalog Python UDFs über die Databricks-Runtime-Umgebung hinaus, indem Sie benutzerdefinierte Abhängigkeiten für externe Bibliotheken definieren.

Installieren Sie Abhängigkeiten aus den folgenden Quellen:

  • PyPi-Pakete
  • Dateien, die in Unity-Katalogvolumes gespeichert sind Der Benutzer, der die UDF aufruft, muss READ VOLUME über Berechtigungen für das Quellvolume verfügen.
  • Dateien, die in öffentlichen URLs verfügbar sind Die Netzwerksicherheitsregeln Ihres Arbeitsbereichs müssen den Zugriff auf öffentliche URLs zulassen.

Hinweis

Informationen zum Konfigurieren von Netzwerksicherheitsregeln für den Zugriff auf öffentliche URLs aus einem serverlosen SQL-Warehouse finden Sie unter Validate with Databricks SQL.

  • Serverless-SQL-Warehouses erfordern die Aktivierung der Public-Preview-Funktion Aktivieren des Netzwerkzugriffs für UDFs in Serverless-SQL-Warehouses, um auf das Internet für benutzerdefinierte Abhängigkeiten zugreifen zu können.

Benutzerdefinierte Abhängigkeiten für Unity Catalog UDFs werden für die folgenden Computetypen unterstützt:

  • Serverlose Notizbücher und Jobs
  • Allzweck-Compute mit Databricks Runtime Version 16.2 und höher
  • SQL Warehouse Classic oder Pro

Verwenden Sie den ENVIRONMENT Abschnitt der UDF-Definition, um Abhängigkeiten anzugeben:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.mixed_process(data STRING)
RETURNS STRING
LANGUAGE PYTHON
ENVIRONMENT (
  dependencies = '["simplejson==3.19.3", "/Volumes/my_catalog/my_schema/my_volume/packages/custom_package-1.0.0.whl", "https://my-bucket.s3.amazonaws.com/packages/special_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]',
  environment_version = 'None'
)
AS $$
import simplejson as json
import custom_package
return json.dumps(custom_package.process(data))
$$;

Der ENVIRONMENT Abschnitt enthält die folgenden Felder:

Feld BESCHREIBUNG Typ Anwendungsbeispiel
dependencies STRING Eine Liste der zu installierenden kommagetrennten Abhängigkeiten. Jeder Eintrag ist eine Zeichenfolge, die dem Pip Requirements-Dateiformat entspricht. dependencies = '["simplejson==3.19.3", "/Volumes/catalog/schema/volume/packages/my_package-1.0.0.whl"]'
dependencies = '["https://my-bucket.s3.amazonaws.com/packages/my_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]'
environment_version STRING Gibt die serverlose Umgebungsversion an, in der die UDF ausgeführt werden soll.
Derzeit wird nur der Wert None unterstützt.		 environment_version = 'None'

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.

Angenommen, Sie haben die folgende sitzungsbasierte UDF in einem Azure Databricks-Notebook:

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}!"
$$

Teilen 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 Benutzeroberfläche des Arbeitsbereichs

  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 der Arbeitsbereichs-Benutzeroberfläche

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

Damit UDFs für alle Benutzer zugänglich sind, empfiehlt Databricks, einen dedizierten Katalog und ein dediziertes Schema mit entsprechenden Zugriffssteuerelementen zu erstellen.

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 wird ein Beispiel für eine UDF mit den folgenden bewährten Methoden angezeigt:

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 KI-Agent-Tools

Generative KI-Agents können Unity Catalog UDFs als Tools verwenden, um Aufgaben auszuführen und benutzerdefinierte Logik auszuführen.

Siehe Erstellen von benutzerdefinierten KI-Agent-Tools mit Unity Catalog-Funktionen.

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 Ports 80, 443 und 53 mithilfe von serverlosen Rechenressourcen oder Konfigurationen, die mit dem Standardzugriffsmodus eingerichtet sind.

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 = parts[0][0] + '*' * (len(parts[0]) - 2) + parts[0][-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 masked_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.
  • 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.
  • Sie können nicht mehr als fünf benutzerdefinierte Funktionen (UDFs) pro Abfrage aufrufen.