SQL en Python door de gebruiker gedefinieerde functies (UDF's) in Unity Catalog

Door de gebruiker gedefinieerde functies (UDF's) in Unity Catalog breiden SQL- en Python-mogelijkheden uit binnen Azure Databricks. Hiermee kunt u aangepaste functies definiëren, gebruiken en veilig delen en beheren in computeromgevingen.

Python UDF's die zijn geregistreerd als functies in Unity Catalog verschillen in bereik en ondersteuning van PySpark UDF's die zijn gericht op een notebook of SparkSession. Zie Python scalaire door de gebruiker gedefinieerde functies (UDF's).

Als u UDF's wilt registreren die zijn geschreven in Scala of Java in Unity Catalog, raadpleegt u Scala en Java door de gebruiker gedefinieerde functies (UDF's) in Unity Catalog.

Om te zien welke workloads en tabellen naar een UDF verwijzen in Unity Catalog voordat je deze aanpast, raadpleeg je View UDF lineage.

Zie CREATE FUNCTION (SQL, Python, Scala en Java) voor volledige naslaginformatie over SQL-talen.

Vereisten

Als u UDF's in Unity Catalog wilt gebruiken, moet u voldoen aan de volgende vereisten:

  • Als u Python-code wilt gebruiken in UDF's die zijn geregistreerd in Unity Catalog, moet u een serverloze of pro SQL-warehouse of een cluster met Databricks Runtime 13.3 LTS of hoger gebruiken.
  • Als een weergave een Unity Catalog Python UDF bevat, mislukt deze in klassieke SQL-warehouses.
  • Arm-exemplaarondersteuning voor Scala UDF's op clusters met Unity Catalog is beschikbaar in Databricks Runtime 15.2 en hoger.

Scalar en Batch Unity Catalog Python UDF's zijn over het algemeen beschikbaar op alle ondersteunde computetypes.

Python UDF-functievereisten

De vereisten verschillen per functie. Databricks Runtime 19 en omgevingsversie 6 zijn geen algemene eisen voor Unity Catalog Python UDF's.

Voor PySpark-sessie-UDF's op serverless notebooks of jobs hebben omgevingsvereisten betrekking op de sessieomgeving. Voor SQL-gedefinieerde Python UDF's verwijzen ze naar environment_version in de clausule ENVIRONMENT van elke functie. Het wijzigen van de sessieomgeving verandert niet de omgeving van een bestaande Unity Catalog-functie. Een sessie met omgevingsversie 6 kan bijvoorbeeld een Unity Catalog-functie aanroepen die is gedefinieerd met omgevingsversie 5.

Feature Vereisten
ENVIRONMENT clausule en custom afhankelijkheden Serverless notebooks en jobs; pro of serverless SQL warehouses; Databricks Runtime 16.2 of hoger op klassieke rekenresources. Op klassieke rekenkracht die Databricks Runtime 16.2 tot en met 18.1 draait, environment_version moet zijn 'None'.
Batch Unity Catalog Python UDF's Serverless compute; pro- en serverloze SQL-warehouses; Databricks Runtime 16.3 of nieuwer op klassieke rekenresources
Benoemde afhandelaar voor een scalaire Python-UDF Databricks Runtime 18.1 of hoger op klassieke compute. Op serverless compute en op Pro- en serverless SQL-warehouses stel je de environment_version van de UDF expliciet in op 6 of hoger.
Servicegegevens in een scalar Python UDF Databricks Runtime 18.1 of hoger op klassieke compute. Op serverless compute en op Pro- en serverless SQL-warehouses stel je de environment_version van de UDF expliciet in op 6 of hoger. Klassieke berekening vereist geen omgevingsversie 6. Op serverless SQL-warehouses kun je ook het geïsoleerde workload-netwerk Public Preview inschakelen.
Service-inloggegevens in een batch Unity Catalog Python UDF Serverless compute; pro- en serverless SQL-warehouses; Databricks Runtime 16.3 of hoger op klassieke compute. Environment versie 6 is niet vereist. Op serverless SQL-warehouses kun je ook het geïsoleerde workload-netwerk Public Preview inschakelen.
Secrets in een scalaire of Batch Unity Catalog Python UDF Stel environment_version expliciet in op 6 of hoger; serverless compute; pro en serverless SQL-warehouses; Databricks Runtime 19 of hoger met de standaardtoegangsmodus op klassieke compute. Direct aanroepen wordt niet ondersteund bij dedicated access mode compute.
PySpark-compatibel TIMESTAMP invoergedrag Databricks Runtime 18.1 of hoger op klassieke compute. Op serverless compute en op Pro- en serverless SQL-warehouses stel je de environment_version van de UDF expliciet in op 6 of hoger.
Meer dan vijf UDF-aanroepen in een query Databricks Runtime 18.1 of hoger op klassieke compute. Op serverless compute en op pro- en serverless SQL-warehouses stel je expliciet elke UDF environment_version op 6 of hoger in.

Bestaande UDF's en functies die beschikbaar waren tijdens Public Preview blijven werken op de toepasbare eerdere runtime-versies.

De omgevingsversie bepaalt ook of aanroepers directe toegang nodig hebben tot afhankelijkheden die zijn opgeslagen in een Unity Catalog-volume. Zie Rechten voor afhankelijkheden in Unity Catalog-volumes.

Omgevingsversies op klassieke compute

Bij klassieke berekening vereist het instellen environment_version van een andere waarde Databricks 'None' Runtime 18.2 of hoger. Op Databricks Runtime 16.2 tot en met 18.1, stel environment_version = 'None' je in wanneer je de ENVIRONMENT clausule gebruikt. De waarde 'None' gebruikt de standaard Python-omgeving.

Op Databricks Runtime 18.2 of hoger, voor voorspelbaar gedrag, raadt Azure Databricks aan om expliciet een vaste environment_version in elke Unity Catalog Python UDF-definitie in te stellen. Kies een versie die voldoet aan de functie-eisen van de UDF en deze compatibiliteitsaanbevelingen volgt:

Databricks Runtime-versie Maximaal aanbevolen omgevingsversie
18.2 tot en met 18.x 5
19.x 6

SQL- en Python-UDF's maken in Unity Catalog

Als u een SQL- of Python UDF in Unity Catalog wilt maken, hebben gebruikers GEBRUIKs- en CREATE-machtigingen nodig voor het schema en gebruiksmachtigingen voor de catalogus. Zie Unity Catalog voor meer informatie.

Gebruikers hebben EXECUTE-rechten nodig om een UDF uit te voeren. Gebruikers hebben ook gebruiksmachtigingen nodig voor het schema en de catalogus.

Als u een UDF wilt maken en registreren in een Unity Catalog-schema, moet de naam van de functie de indeling catalog.schema.function_namevolgen. U kunt ook de juiste catalogus en het juiste schema selecteren in de SQL-editor. In dit geval mag catalog.schema niet voor uw functienaam geplaatst worden:

Een UDF maken met de catalogus en het vooraf geselecteerde schema.

In het volgende voorbeeld wordt een nieuwe functie geregistreerd voor het my_schema schema in de my_catalog catalogus:

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's voor Unity Catalog gebruiken statements die worden afgebakend door dubbele dollartekens ($$). U moet een toewijzing van een gegevenstype opgeven. In het volgende voorbeeld wordt een UDF geregistreerd waarmee de hoofdmassaindex wordt berekend:

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

U kunt deze Unity Catalog-functie nu gebruiken in uw SQL-query's of PySpark-code:

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

Zie voorbeelden van rijfilters en voorbeelden van kolommaskers voor meer UDF-voorbeelden.

Gebruik een benoemde handler in een scalaire Python-UDF

Op klassieke compute vereisen handlers met een naam Databricks Runtime 18.1 of hoger. Op serverless compute en op Pro- en serverless SQL-warehouses stel je de environment_version van de UDF expliciet in op 6 of hoger. Het volgende voorbeeld gebruikt omgevingsversie 6. Op klassieke rekenkracht met Databricks Runtime 18.1, laat de ENVIRONMENT clausule weg. Volg bij latere runtime-versies de compatibiliteitsaanbevelingen als je de clausule opneemt.

Gebruik de HANDLER clausule om een Python-functie in het UDF-lichaam als instappunt te benoemen. De benoemde handler accepteert de UDF-argumenten en geeft een waarde terug die overeenkomt met het type gedeclareerde return. Code buiten de handler draait wanneer elke Python-omgeving de UDF initialiseert, voordat de handler invoer verwerkt. Gebruik deze code voor eenmalige initialisatie die hergebruikt kan worden over handler-aanroepen heen.

Het volgende voorbeeld initialiseert greeting_prefix voordat wordt gedefinieerd greet_handler, de functie die UDF-invoer verwerkt:

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

Geheime gegevens gebruiken in een Python UDF

Scalar en Batch Unity Catalog Python UDF's kunnen geheimen benaderen die in de SECRETS clausule zijn gedeclareerd. De UDF-definitie moet expliciet op 6 of hoger worden ingesteldenvironment_version. Een Unity Catalog-geheim gebruikt een driedelige naam (catalog.schema.secret) en is verschillend van een werkruimte-niveau Azure Databricks-geheim. Voor compute-ondersteuning, permissies en de dedicated-compute column-mask exception, zie UDF-vereisten en permissies.

Om toegang te krijgen tot een geheim van een UDF:

  1. Voeg de driedelige naam van het geheim toe aan de SECRETS clausule in de UDF-definitie. Een UDF kan alleen geheimen ophalen die in deze clausule zijn opgegeven.
  2. Roep in de hoofdtekst van de UDF databricks.secrets.get() aan met de catalogus, het schema en de naam van het geheim.

Het volgende scalaire UDF-voorbeeld gebruikt een Unity Catalog-geheim als een hash-gebaseerde berichtauthenticatiecode (HMAC) ondertekeningssleutel. Gebruik dezelfde SECRETS clausule met PARAMETER STYLE PANDAS om toegang te krijgen tot gedeclareerde geheimen vanuit een Batch UDF-handler.

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

Warning

Geef geen geheime waarden terug van een UDF. Het maskeren van geheimen helpt onbedoelde blootstelling in foutmeldingen en logboeken te verminderen, maar voorkomt niet dat UDF-code geheime gegevens in queryresultaten blootlegt.

UDF's uitbreiden met behulp van aangepaste afhankelijkheden

Notitie

Als u aangepaste afhankelijkheden van internet wilt installeren in een serverloos SQL-warehouse, moet in uw werkruimte de openbare previewfunctie Netwerken inschakelen voor geïsoleerde workloads in serverloze SQL-warehouses zijn ingeschakeld op de Previews-pagina.

U kunt de mogelijkheden van Unity Catalog uitbreiden Python UDF's buiten de Databricks Runtime-omgeving door aangepaste afhankelijkheden voor externe bibliotheken te definiëren.

vereisten voor

Aangepaste afhankelijkheden voor UDF's van Unity Catalog worden ondersteund voor de volgende rekentypen:

  • Serverloze notebooks en taken
  • Klassieke all-purpose compute met Databricks Runtime versie 16.2 en hoger
  • Pro ofwel serverloze SQL-warehouse

Afhankelijkheidsbronnen

Installeer afhankelijkheden uit de volgende bronnen:

Notitie

Als uw werkruimte serverloze netwerktoegang beperkt, moet u netwerkbeveiligingsregels configureren om de openbare URL's toe te staan. Zie Regels voor uitgaand verkeer instellen.

Machtigingen voor afhankelijkheden in Unity Catalog-volumes

De maker van de functie moet READ VOLUME op een bronvolume hebben om een afhankelijkheid van dat volume naar een UDF toe te voegen.

Voor een UDF waarvan de definitie expliciet is ingesteld op environment_version of hoger voor 6, hebben aanroepers EXECUTE op de UDF nodig, maar niet READ VOLUME op het bronvolume. Als de UDF-definitie environment_version weglaat, deze instelt op None, of deze op een eerdere versie instelt, moeten oproepende functies ook READ VOLUME op het bronvolume hebben.

Afhankelijkheden definiëren

Gebruik de sectie ENVIRONMENT van de UDF-definitie om afhankelijkheden op te geven:

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

De sectie ENVIRONMENT bevat de volgende velden:

Veld Beschrijving Typ Voorbeeld van gebruik
dependencies Een lijst met door komma's gescheiden afhankelijkheden die moeten worden geïnstalleerd. Elke vermelding is een tekenreeks die voldoet aan de pip Requirements File Format. STRING 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 Specificeert de omgevingsversie waarin de UDF moet draaien. Dit veld is vereist telkens wanneer de ENVIRONMENT clausule aanwezig is. Met een vaste omgevingsversie wordt de UDF uitgevoerd met een specifieke Python versie en een set vooraf geïnstalleerde pakketten, onafhankelijk van de Python versie en pakketten in de onderliggende Databricks Runtime.
Ondersteunde waarden zijn een omgevingsversie van 3 of hoger, zoals '6', of de string 'None'. De waarde 'None' selecteert de standaard Python-omgeving. Bij klassieke berekening vereist het instellen environment_version van een andere waarde Databricks 'None' Runtime 18.2 of hoger. Op Databricks Runtime 16.2 tot en met 18.1 wordt alleen 'None' ondersteund. Wanneer versies van vaste omgevingen worden ondersteund, selecteer er dan expliciet één voor voorspelbaar gedrag.
Op serverless compute en op pro- en serverless SQL-warehouses vereisen sommige functies een expliciete omgevingsversie. Stel environment_version in elke UDF-definitie in op de vereiste versie of hoger. Het weglaten van de hele ENVIRONMENT clausule of instelling environment_version = 'None' maakt die functies niet mogelijk. Zie vereisten voor de Python UDF-functie.
Voor klassieke computeversiecompatibiliteit, zie Omgevingsversies op klassieke compute. Voor de lijst van beschikbare versies, zie Omgevingsversies.		 STRING environment_version = '6'

UDF's van Unity Catalog gebruiken 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)

Een UDF met sessiebereik upgraden

Notitie

Syntaxis en semantiek voor Python UDF's in Unity Catalog verschillen van Python UDF's die zijn geregistreerd bij SparkSession. Bekijk door de gebruiker gedefinieerde scalaire functies - Python.

Gezien de volgende sessiegebonden UDF in een 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()

Als u dit wilt registreren als een Unity Catalog-functie, gebruikt u een SQL-CREATE FUNCTION-instructie, zoals in het volgende voorbeeld:

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

UDFs delen in Unity Catalog

De toegangsbeheer die zijn toegepast op de catalogus, het schema of de database waar u de UDF registreert, beheert de machtigingen. Zie Bevoegdheden beheren in Unity Catalog voor meer informatie.

Gebruik azure Databricks SQL of de gebruikersinterface van de Azure Databricks-werkruimte om machtigingen te verlenen aan een gebruiker of groep (aanbevolen).

Machtigingen in de gebruikersinterface van de werkruimte

  1. Zoek de catalogus en het schema waarin uw UDF is opgeslagen en selecteer de UDF.
  2. Zoek naar een optie Machtigingen in de UDF-instellingen. Voeg gebruikers of groepen toe en geef het type toegang op dat ze moeten hebben, zoals EXECUTE of MANAGE.

machtigingen in de gebruikersinterface van de werkruimte

Machtigingen met Behulp van Azure Databricks SQL

In het volgende voorbeeld verleent een gebruiker de MACHTIGING EXECUTE voor een functie:

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

Als u machtigingen wilt verwijderen, gebruikt u de opdracht REVOKE zoals in het volgende voorbeeld:

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

Omgevingsisolatie

Notitie

Gedeelde isolatieomgevingen vereisen Databricks Runtime 18.1 en hoger. In eerdere versies worden alle Unity Catalog Python UDF's uitgevoerd in de strikte isolatiemodus.

UDF's van Unity Catalog python met dezelfde eigenaar en sessie kunnen standaard een isolatieomgeving delen. Dit verbetert de prestaties en vermindert het geheugengebruik door het aantal afzonderlijke omgevingen te verminderen dat moet worden gestart.

Strikte isolatie

Als u wilt controleren of een UDF altijd in een eigen, volledig geïsoleerde omgeving wordt uitgevoerd, voegt u de STRICT ISOLATION kenmerkcomponent toe.

De meeste UDF's hebben geen strikte isolatie nodig. UDF's voor standaardgegevensverwerking profiteren van de standaardomgeving voor gedeelde isolatie en worden sneller uitgevoerd met een lager geheugenverbruik.

Voeg de STRICT ISOLATION kenmerkcomponent toe aan UDF's die:

  • Voer invoer uit als code met behulp vaneval()exec(), of vergelijkbare functies.
  • Schrijf bestanden naar het lokale bestandssysteem.
  • Wijzig globale variabelen of systeemstatus.
  • Omgevingsvariabelen openen of wijzigen.

De volgende code toont een voorbeeld van een UDF die moet worden uitgevoerd met behulp van STRICT ISOLATION. Met deze UDF wordt willekeurige Python code uitgevoerd, waardoor de systeemstatus, toegang tot omgevingsvariabelen of schrijfbewerkingen naar het lokale bestandssysteem kunnen worden gewijzigd. Het gebruik van de STRICT ISOLATION component helpt interferentie of gegevenslekken tussen UDF's te voorkomen.

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

Stel DETERMINISTIC in als uw functie consistente resultaten produceert

Voeg deze DETERMINISTIC toe aan uw functiedefinitie als deze dezelfde uitvoer produceert voor dezelfde invoer. Hierdoor kunnen queryoptimalisaties de prestaties verbeteren.

Standaard behandelt Azure Databricks Batch Unity Catalog Python UDF's als niet-deterministisch, tenzij u expliciet anders declareert. Voorbeelden van niet-deterministische functies zijn het genereren van willekeurige waarden, het openen van huidige tijden of datums of het maken van externe API-aanroepen.

Zie CREATE FUNCTION (SQL, Python, Scala en Java)

UDF’s voor agenttools

AI-agents kunnen UDF's van Unity Catalog als hulpprogramma's gebruiken om taken uit te voeren en aangepaste logica uit te voeren.

Zie Agenthulpprogramma's maken met behulp van Unity Catalog-functies.

UDF's voor toegang tot externe API's

U KUNT UDF's gebruiken voor toegang tot externe API's vanuit SQL. In het volgende voorbeeld wordt de Python-bibliotheek requests gebruikt om een HTTP-aanvraag te maken.

Notitie

Python UDF's staan TCP/UDP-netwerkverkeer toe via poorten 80, 443 en 53 bij gebruik van serverloze berekeningen of berekeningen die zijn geconfigureerd met de standaardtoegangsmodus.

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

$$;

UDF's voor beveiliging en naleving

Gebruik Python UDF's om aangepaste tokenisatie, gegevensmaskering, gegevensversleuteling of versleutelingsmechanismen te implementeren.

In het volgende voorbeeld wordt de identiteit van een e-mailadres gemaskeerd terwijl de lengte en het domein behouden blijven:

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

In het volgende voorbeeld wordt deze UDF toegepast in een dynamische weergavedefinitie:

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

Beste praktijken

Databricks raadt aan een speciale catalogus en een specifiek schema te maken met de juiste toegangsbeheer om UDF's toegankelijk te maken voor alle gebruikers.

Gebruik voor teamspecifieke UDF's een speciaal schema in de teamcatalogus voor opslag en beheer.

Databricks raadt u aan de volgende informatie op te nemen in de UDF-docstring:

  • Het huidige versienummer
  • Een wijzigingenlogboek voor het bijhouden van wijzigingen in verschillende versies
  • Het UDF-doel, de parameters en de retourwaarde
  • Een voorbeeld van het gebruik van de UDF

In het volgende voorbeeld ziet u een UDF die de aanbevolen procedures volgt:

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

Gedrag van de tijdzone van tijdstempels voor invoer per rij

Een TIMESTAMP invoer komt rij voor rij bij een Python UDF binnen als een tijdzone-onbewuste datetime waarde in UTC. Op klassieke berekening vereist dit gedrag Databricks Runtime 18.1 of hoger. Op serverless compute en op Pro- en serverless SQL-warehouses stel je de environment_version van de UDF expliciet in op 6 of hoger. Het datetime object bevat geen tijdzonemetadata in zijn tzinfo attribuut.

Batch Unity Catalog Python UDF's ontvangen tijdstempelinvoer in pandas.Series objecten en gebruiken deze datetime mapping niet.

Met deze wijziging worden Python UDF's van Unity Catalog uitgelijnd met python-UDF's die zijn geoptimaliseerd voor pijlen in Apache Spark.

Bijvoorbeeld, de volgende query stelt expliciet omgevingsversie 6 en de sessietijdzone in op 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');

Het eerdere executiepad geeft een waarde met tijdzone-informatie terug in de sessietijdzone. Dit geldt voor klassieke compute vóór Databricks Runtime 18.1. Het geldt ook voor serverless compute en op pro- en serverless SQL-warehouses wanneer je de ENVIRONMENT clausule weglaat, instelt environment_version = 'None'of een versie eerder dan 6 selecteert. Met de sessietijdzone ingesteld op UTC, levert het eerdere pad het volgende op:

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

Met de weergegeven definitie maken serverless compute en pro- en serverless SQL-warehouses gebruik van PySpark-compatibel gedrag. Klassieke compute met Databricks Runtime 18.1 of hoger vertoont hetzelfde gedrag wanneer je de clausule ENVIRONMENT aanpast of weglaat:

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

Deze wijziging kan zowel de klokvelden als tzinfo beïnvloeden. Voor het moment 2024-10-23T10:30:00Z, produceert 2024-10-23 03:30:00-07:00het eerdere gedrag in een America/Los_Angeles sessie . Het nieuwe gedrag produceert de tijdzone-naïeve UTC-waarde 2024-10-23 10:30:00.

Als je UDF afhankelijk is van tijdzone-informatie, herstel dan expliciet UTC:

from datetime import timezone

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

Het toevoegen van UTC-tijdzone-informatie herstelt de vorige sessie-lokale klokvelden niet. Als je logica die velden nodig heeft, zet dan ook de bewuste waarde om naar de bedoelde sessietijdzone. Voorbeeld:

from zoneinfo import ZoneInfo

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

Beperkingen

  • U kunt een willekeurig aantal Python-functies definiëren binnen een Python UDF, maar alle functies moeten een scalaire waarde retourneren.
  • Python-functies moeten NULL-waarden onafhankelijk verwerken en alle typetoewijzingen moeten azure Databricks SQL-taaltoewijzingen volgen.
  • Als u geen catalogus of schema opgeeft, registreert Azure Databricks Python UDF's voor het huidige actieve schema.
  • Python UDF's worden uitgevoerd in een beveiligde, geïsoleerde omgeving en hebben geen toegang tot bestandssystemen of interne services.
  • Je kunt meer dan vijf UDF's aanroepen in een query op klassieke compute met Databricks Runtime 18.1 of hoger. Op serverless compute en op pro- en serverless SQL-warehouses moet elke UDF-definitie expliciet op 6 of hoger worden ingesteldenvironment_version.
  • Laatst bijgewerkt om