SQL- och Python användardefinierade funktioner (UDF: er) i Unity Catalog

Användardefinierade funktioner (UDF:er) i Unity Catalog utökar SQL- och Python-funktionerna i Azure Databricks. De låter dig definiera, använda och på ett säkert sätt dela och styra anpassade funktioner i olika datormiljöer.

Python-UDF:er som är registrerade som funktioner i Unity Catalog skiljer sig åt i omfattning och stöd från PySpark-UDF:er som är begränsade till en notebook-fil eller SparkSession. Se Python skalära användardefinierade funktioner (UDF:er).

Information om hur du registrerar UDF:er som skrivits i Scala eller Java i Unity Catalog finns i Scala och Java användardefinierade funktioner (UDF:er) i Unity Catalog.

För att se vilka arbetsbelastningar och tabeller som refererar till en UDF i Unity Catalog innan du ändrar den, se Visa UDF-härstamning.

Se CREATE FUNCTION (SQL, Python, Scala och Java) för fullständig SQL-språkreferens.

Krav

Om du vill använda UDF:er i Unity Catalog måste du uppfylla följande krav:

• Om du vill använda Python-kod i UDF:er som är registrerade i Unity Catalog måste du använda ett serverlöst eller pro SQL-lager eller ett kluster som kör Databricks Runtime 13.3 LTS eller senare.
• Om en vy innehåller en Unity Catalog Python UDF misslyckas den på klassiska SQL-lager.
• ARM-instansstöd för Scala UDF:er i Unity Catalog-aktiverade kluster är tillgängligt i Databricks Runtime 15.2 och senare.

Scalar och Batch Unity Catalog Python UDF finns generellt tillgängliga på alla stödda beräkningstyper.

Python UDF-funktionskrav

Kraven varierar beroende på funktion. Databricks Runtime 19 och miljöversion 6 är inte allmänna krav för Unity Catalog Python UDF.

För sessions-UDF:er i PySpark i serverlösa notebooks eller jobb avser miljökraven sessionsmiljön. För SQL-definierade Python UDF:er hänvisar de till environment_version i varje funktions ENVIRONMENT klausul. Att ändra sessionsmiljön ändrar inte miljön för en befintlig Unity Catalog-funktion. Till exempel kan en session med miljöversion 6 anropa en Unity-katalogfunktion definierad med miljöversion 5.

Befintliga UDF:er och funktioner som fanns tillgängliga under Public Preview fortsätter att fungera på tillämpliga tidigare runtime-versioner.

Miljöversionen avgör också om anropare behöver direkt åtkomst till beroenden lagrade i en Unity Catalog-volym. Se Behörigheter för beroenden i Unity Catalog-volymer.

Miljöversioner på klassisk beräkning

På klassisk beräkning kräver inställning environment_version till ett annat värde Databricks 'None' Runtime 18.2 eller högre. På Databricks Runtime 16.2 till 18.1, sätt environment_version = 'None' varje gång du använder klausulen ENVIRONMENT . Värdet 'None' använder standardmiljön i Python.

På Databricks Runtime 18.2 eller högre, för förutsägbart beteende, rekommenderar Azure Databricks att man explicit sätter en fast environment_version funktion i varje Unity Catalog Python UDF-definition. Välj en version som uppfyller UDF:s funktionskrav och följer dessa kompatibilitetsrekommendationer:

Skapa SQL- och Python UDF:er i Unity Catalog

För att skapa en SQL- eller Python-UDF i Unity Catalog behöver användarna behörigheterna USAGE och CREATE för schemat samt behörigheten USAGE för katalogen. Mer information finns i Unity Catalog.

För att kunna köra en UDF behöver användarna behörigheten EXECUTE på UDF. Användarna behöver också ANVÄNDNINGsbehörighet för schemat och katalogen.

Om du vill skapa och registrera en UDF i ett Unity Catalog-schema måste funktionsnamnet följa formatet catalog.schema.function_name. Du kan också välja rätt katalog och schema i SQL-redigeraren. I det här fallet får catalog.schema inte läggas till före funktionsnamnet:

I följande exempel registreras en ny funktion i my_schema schemat i my_catalog katalogen:

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

Python-UDF:er för Unity Catalog använder satser som avgränsas med dubbla dollartecken ($$). Du måste ange en datatypsmappning. I följande exempel registreras en UDF som beräknar kroppsmasseindex.

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

Du kan nu använda den här Unity Catalog-funktionen i dina SQL-frågor eller PySpark-kod:

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

Mer UDF-exempel finns i Exempel på radfilter och Kolumnmask .

Använd en namngiven hanterare i en skalär Python UDF

På klassisk beräkning kräver namngivna hanterare Databricks Runtime 18.1 eller högre. På serverlös beräkning samt på pro- och serverlösa SQL-datalager anger du uttryckligen UDF:ens environment_version till 6 eller högre. Följande exempel använder miljöversion 6. På klassisk beräkning som kör Databricks Runtime 18.1, ta bort klausulen ENVIRONMENT . På senare versioner under runtime, följ kompatibilitetsrekommendationerna om du inkluderar klausulen.

Använd klausulen HANDLER för att namnge en Python-funktion i UDF-kroppen som ingångspunkt. Den namngivna hanteraren accepterar UDF-argumenten och returnerar ett värde som matchar den deklarerade returtypen. Kod utanför hanteraren körs när varje Python-miljö initierar UDF, innan hanteraren bearbetar inmatningar. Använd denna kod för engångsinitiering som kan återanvändas i hanteraranrop.

I följande exempel initieras greeting_prefix innan greet_handler definieras, funktionen som hanterar UDF-indata:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
HANDLER 'greet_handler'
ENVIRONMENT (
  environment_version = '6'
)
AS $$
# Runs once when each Python environment initializes the UDF.
greeting_prefix = "Hello"

def greet_handler(name):
    return f"{greeting_prefix}, {name}!"
$$;

Använd hemligheter i en Python UDF

Skalära och batch-Unity Catalog Python-UDF:er får åtkomst till hemligheter som deklareras i klausulen SECRETS. UDF-definitionen måste uttryckligen sättas environment_version till 6 eller över. En Unity-kataloghemlighet använder ett tredelat namn (catalog.schema.secret) och skiljer sig från en arbetsytnivå-Azure Databricks-hemlighet. För beräkningsstöd, behörigheter och undantaget för dedikerad beräkning av kolumnmask, se UDF-krav och behörigheter.

För att få tillgång till en hemlighet från en UDF:

1. Lägg till hemlighetens tredelade namn till klausulen SECRETS i UDF-definitionen. En UDF kan endast hämta hemligheter som deklareras i denna klausul.
2. I UDF-kroppen anropar du databricks.secrets.get() med katalogen, schemat och namnet på hemligheten.

Följande skalär UDF-exempel använder en Unity Catalog-hemlighet som en hashbaserad meddelandeautentiseringskod (HMAC) signeringsnyckel. Använd samma SECRETS klausul tillsammans med PARAMETER STYLE PANDAS för att få åtkomst till deklarerade hemligheter från en Batch UDF-hanterare.

CREATE OR REPLACE FUNCTION main.default.sign_value(value STRING)
RETURNS STRING
LANGUAGE PYTHON
SECRETS (main.default.hmac_key)
ENVIRONMENT (
  environment_version = '6'
)
AS $$
import hashlib
import hmac
from databricks.secrets import get

key = get(catalog="main", schema="default", key="hmac_key")
return hmac.new(key.encode(), value.encode(), hashlib.sha256).hexdigest()
$$;

Utöka UDF:er med anpassade beroenden

Du kan utöka funktionerna i Unity Catalog Python UDF:er utöver Databricks Runtime-miljön genom att definiera anpassade beroenden för externa bibliotek.

krav

Anpassade beroenden för Unity Catalog UDFs stöds på följande beräkningstyper:

• Serverlösa notebook-filer och jobb
• Klassisk allmän beräkning med Databricks Runtime version 16.2 och senare versioner
• Pro- eller serverlöst SQL-lager

Beroendekällor

Installera beroenden från följande källor:

• PyPI-paket
• Filer lagrade i Unity-katalogvolymerSe Behörigheter för beroenden i Unity Catalog-volymer.
• Filer som är tillgängliga på offentliga URL:er Säkerhetsreglerna för arbetsytans nätverk måste tillåta åtkomst till offentliga URL:er. Se kraven.

Behörigheter för beroenden i Unity Catalog-volymer

Funktionsskaparen måste ha READ VOLUME på en källvolym för att lägga till ett beroende från den volymen till en UDF.

För en UDF vars definition uttryckligen anger environment_version till 6 eller högre, behöver anropare EXECUTE på UDF:en men inte READ VOLUME på källvolymen. Om UDF-definitionen utelämnar environment_version, sätter den till None, eller sätter den till en tidigare version, måste anropare också ha READ VOLUME på källvolymen.

Definiera beroenden

Använd avsnittet i ENVIRONMENT UDF-definitionen för att ange beroenden:

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 = '6'
)
AS $$
import simplejson as json
import custom_package
return json.dumps(custom_package.process(data))
$$;

Avsnittet ENVIRONMENT innehåller följande fält:

Använda Unity Catalogs UDF:er i PySpark

from pyspark.sql.functions import expr

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

Uppgradera en UDF som är begränsad till sessionen

Givet följande sessionbaserade UDF i en Azure Databricks-notebook-fil:

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

Om du vill registrera detta som en Unity Catalog-funktion använder du en SQL-CREATE FUNCTION-instruktion, som i följande exempel:

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

Dela UDF:er i Unity-katalogen

Åtkomstkontrollerna som tillämpas på katalogen, schemat eller databasen där du registrerar UDF hanterar dess behörigheter. Mer information finns i Hantera privilegier i Unity Catalog .

Använd Azure Databricks SQL eller Azure Databricks-arbetsytans användargränssnitt för att ge behörighet till en användare eller grupp (rekommenderas).

Behörigheter i arbetsytans UI

1. Leta upp katalogen och schemat där UDF lagras och välj UDF.
2. Leta efter ett behörighetsalternativ i UDF-inställningarna. Lägg till användare eller grupper och ange vilken typ av åtkomst de måste ha, till exempel EXECUTE eller MANAGE.

Behörigheter med Azure Databricks SQL

I följande exempel får en användare behörigheten EXECUTE för en funktion:

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

Om du vill ta bort behörigheter använder du kommandot REVOKE som i följande exempel:

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

Miljöisolering

Unity Catalog Python UDF:er med samma ägare och session kan dela en isoleringsmiljö som standard. Detta förbättrar prestanda och minskar minnesanvändningen genom att minska antalet separata miljöer som måste startas.

Strikt isolering

Om du vill verifiera att en UDF alltid körs i en egen, helt isolerad miljö lägger du till egenskapssatsen STRICT ISOLATION .

De flesta UDF:er behöver inte strikt isolering. UDF:er för standarddatabearbetning drar nytta av standardmiljön för delad isolering och körs snabbare med lägre minnesförbrukning.

Lägg till egenskapssatsen STRICT ISOLATION i UDF:er som:

• Kör indata som kod med hjälp av eval(), exec()eller liknande funktioner.
• Skriv filer till det lokala filsystemet.
• Ändra globala variabler eller systemtillstånd.
• Få åtkomst till eller ändra miljövariabler.

Följande kod visar ett exempel på en UDF som måste köras med .STRICT ISOLATION Den här UDF:n kör godtycklig Python kod, så den kan ändra systemtillståndet, komma åt miljövariabler eller skriva till det lokala filsystemet. Med hjälp av STRICT ISOLATION satsen kan du förhindra störningar eller dataläckor mellan UDF:er.

CREATE OR REPLACE TEMPORARY FUNCTION run_python_snippet(python_code STRING)
RETURNS STRING
LANGUAGE PYTHON
STRICT ISOLATION
AS $$
import sys
from io import StringIO

# Capture standard output and error streams
captured_output = StringIO()
captured_errors = StringIO()
sys.stdout = captured_output
sys.stderr = captured_errors

try:
    # Execute the user-provided Python code in an empty namespace
    exec(python_code, {})
except SyntaxError:
    # Retry with escaped characters decoded (for cases like "\n")
    def decode_code(raw_code):
        return raw_code.encode('utf-8').decode('unicode_escape')
    python_code = decode_code(python_code)
    exec(python_code, {})

# Return everything printed to stdout and stderr
return captured_output.getvalue() + captured_errors.getvalue()
$$

Ange DETERMINISTIC om funktionen ger konsekventa resultat

Lägg till DETERMINISTIC i funktionsdefinitionen om den genererar samma utdata för samma indata. På så sätt kan frågeoptimeringar förbättra prestandan.

Som standard behandlar Azure Databricks Batch Unity Catalog Python UDF:er som icke-deterministiska om du inte uttryckligen deklarerar något annat. Exempel på icke-deterministiska funktioner är att generera slumpmässiga värden, komma åt aktuella tider eller datum eller göra externa API-anrop.

Se CREATE FUNCTION (SQL, Python, Scala och Java)

UDF:er för agentverktyg

AI-agenter kan använda UDF:er i Unity Catalog som verktyg för att utföra uppgifter och köra anpassad logik.

Se Skapa agentverktyg med hjälp av Unity Catalog-funktioner.

UDF:er för åtkomst till externa API:er

Du kan använda UDF:er för att komma åt externa API:er från SQL. I följande exempel används Python-biblioteket requests för att göra en HTTP-begäran.

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()
   # Assume the API returns a JSON object with a 'calories' field
   calories = data.get('calories', 0)
   return calories
else:
   return None  # API request failed

$$;

Användardefinierade funktioner för säkerhet och regelefterlevnad

Använd Python-UDF:er för att implementera anpassad tokenisering, datamaskering, dataredigering eller krypteringsmekanismer.

I följande exempel maskeras identiteten för en e-postadress samtidigt som längden och domänen bibehålls:

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

I följande exempel tillämpas denna UDF i en dynamisk vydefinition:

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

Metodtips

För att UDF:er ska vara tillgängliga för alla användare rekommenderar Databricks att du skapar en dedikerad katalog och ett schema med lämpliga åtkomstkontroller.

För teamspecifika UDF:er använder du ett dedikerat schema i teamkatalogen för lagring och hantering.

Databricks rekommenderar att du inkluderar följande information i UDF-dokumentsträngen:

• Det aktuella versionsnumret
• En ändringslogg för att spåra ändringar mellan versioner
• UDF-syfte, parametrar och returvärde
• Ett exempel på hur du använder UDF

I följande exempel visas en UDF som följer metodtipsen:

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

Beteende för tidszoner i tidsstämplar för indata rad för rad

Ett TIMESTAMP-indatavärde når en radvis Python-UDF som ett tidszonsnaivt datetime-värde i UTC. På klassisk beräkning kräver detta beteende Databricks Runtime 18.1 eller högre. På serverlös beräkning samt på pro- och serverlösa SQL-datalager anger du uttryckligen UDF:ens environment_version till 6 eller högre. Objektet datetime inkluderar inte tidszonsmetadata i sitt tzinfo attribut.

Batch Unity Catalog Python UDF:er tar emot tidsstämpelindata i pandas.Series objekt och använder inte denna datetime mappning.

Den här ändringen justerar Unity Catalog Python UDF:er med piloptimerade Python-UDF:er i Apache Spark.

Till exempel sätter följande fråga uttryckligen miljöversion 6 och sessionstidszonen till UTC:

SET TIME ZONE 'UTC';

CREATE FUNCTION timezone_udf(date TIMESTAMP)
RETURNS STRING
LANGUAGE PYTHON
ENVIRONMENT (
  environment_version = '6'
)
AS $$
return f"{type(date)} {date} {date.tzinfo}"
$$;

SELECT timezone_udf(TIMESTAMP '2024-10-23 10:30:00');

Den tidigare exekveringsvägen returnerar ett tidszonsmedvetet värde i sessionens tidszon. Detta gäller för klassisk beräkning före Databricks Runtime 18.1. Det gäller också för serverless compute och för Pro- och serverless SQL-datalager när du utelämnar klausulen ENVIRONMENT, anger environment_version = 'None' eller väljer en version tidigare än 6. Med sessionstidszonen inställd på UTC ger den tidigare vägen:

<class 'datetime.datetime'> 2024-10-23 10:30:00+00:00 UTC

Med definitionen som visas använder serverless compute samt pro- och serverless SQL-datalager det PySpark-kompatibla beteendet. Klassisk beräkning som kör Databricks Runtime 18.1 eller högre använder samma beteende när du justerar eller utelämnar klausulen ENVIRONMENT :

<class 'datetime.datetime'> 2024-10-23 10:30:00 None

Denna förändring kan påverka klockfälten samt tzinfo. För tillfället 2024-10-23T10:30:00Z ger det tidigare beteendet i en America/Los_Angeles-session 2024-10-23 03:30:00-07:00. Det nya beteendet ger det tidszonsnaiva UTC-värdet 2024-10-23 10:30:00.

Om din UDF förlitar sig på tidszonsinformation, återställ UTC uttryckligen:

from datetime import timezone

date = date.replace(tzinfo=timezone.utc)

Att lägga till UTC-tidszonsinformation återställer inte de tidigare sessionslokala klockfälten. Om din logik behöver dessa fält, konvertera också det medvetna värdet till den avsedda sessionstidszonen. Ett exempel:

from zoneinfo import ZoneInfo

date = date.astimezone(ZoneInfo("America/Los_Angeles"))

Begränsningar

• Du kan definiera valfritt antal Python-funktioner i en Python UDF, men alla måste returnera ett skalärt värde.
• Python-funktioner måste hantera NULL-värden oberoende av varandra, och alla typmappningar måste följa Azure Databricks SQL-språkmappningar.
• Om du inte anger en katalog eller ett schema registrerar Azure Databricks Python UDF:er till det aktuella aktiva schemat.
• Python UDF:er körs i en säker, isolerad miljö och har inte åtkomst till filsystem eller interna tjänster.
• Du kan anropa mer än fem UDF:er i en fråga på klassisk beräkning som kör Databricks Runtime 18.1 eller högre. I serverless compute och i pro- och serverless SQL-datalager måste varje UDF-definition uttryckligen ange environment_version till 6 eller senare.