Door de gebruiker gedefinieerde Batch Python-functies (UDF's) in Unity Catalog

Belangrijk

Deze functie bevindt zich in openbare preview-versie.

Batch Unity Catalog Python UDF's breiden de mogelijkheden van Unity Catalog UDF's uit door u in staat te stellen Python-code te schrijven om te werken op batches met gegevens, waardoor de efficiëntie aanzienlijk wordt verbeterd door de overhead die is gekoppeld aan UDF's voor rij per rij te verminderen. Deze optimalisaties maken Unity Catalog batch Python UDF's ideaal voor grootschalige gegevensverwerking.

Behoeften

Batch Unity Catalog Python UDFs vereisen Databricks Runtime-versies 16.3 en hoger.

Maak een Batch Unity Catalog Python UDF

Het maken van een Batch Unity Catalog Python UDF is vergelijkbaar met het maken van een reguliere Unity Catalog UDF, met de volgende toevoegingen:

PARAMETER STYLE PANDAS: Hiermee geeft u op dat de UDF gegevens in batches verwerkt met behulp van pandas-iterators.
HANDLER 'handler_function': Hiermee geeft u de handler-functie op die wordt aangeroepen om de batches te verwerken.

In het volgende voorbeeld ziet u hoe u een Python UDF voor Batch Unity Catalog maakt:

%sql
CREATE OR REPLACE TEMPORARY FUNCTION calculate_bmi_pandas(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
DETERMINISTIC
PARAMETER STYLE PANDAS
HANDLER 'handler_function'
AS $$
import pandas as pd
from typing import Iterator, Tuple

def handler_function(batch_iter: Iterator[Tuple[pd.Series, pd.Series]]) -> Iterator[pd.Series]:
  for weight_series, height_series in batch_iter:
    yield weight_series / (height_series ** 2)
$$;

Nadat u de UDF hebt geregistreerd, kunt u deze aanroepen met behulp van SQL of Python:

SELECT person_id, calculate_bmi_pandas(weight_kg, height_m) AS bmi
FROM (
  SELECT 1 AS person_id, CAST(70.0 AS DOUBLE) AS weight_kg, CAST(1.75 AS DOUBLE) AS height_m UNION ALL
  SELECT 2 AS person_id, CAST(80.0 AS DOUBLE) AS weight_kg, CAST(1.80 AS DOUBLE) AS height_m
);

Batch-UDF-handlerfunctie

Batch Unity Catalog Python UDF's vereisen een handler-functie die batches verwerkt en resultaten oplevert. U moet de naam van de handlerfunctie opgeven wanneer u de UDF maakt met behulp van de HANDLER sleutel.

De handler-functie doet het volgende:

Accepteert een iterator-argument dat over een of meer pandas.Series doorloopt. Elk pandas.Series bevat de invoerparameters van de UDF.
Itereert de generator en verwerkt gegevens.
Hiermee wordt een generator-iterator geretourneerd.

Batch Unity Catalog Python UDF's moeten hetzelfde aantal rijen retourneren als de invoer. De handler-functie zorgt ervoor dat dit gebeurt door een pandas.Series met dezelfde lengte als de invoerreeks voor elke batch te genereren.

Aangepaste afhankelijkheden installeren

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

Zie UDF's uitbreiden met behulp van aangepaste afhankelijkheden.

Batch-UDF's kunnen enkele of meerdere parameters accepteren

Eén parameter: Wanneer de handler-functie één invoerparameter gebruikt, ontvangt deze een iterator die voor elke batch over een pandas.Series doorloopt.

%sql
CREATE OR REPLACE TEMPORARY FUNCTION one_parameter_udf(value INT)
RETURNS STRING
LANGUAGE PYTHON
DETERMINISTIC
PARAMETER STYLE PANDAS
HANDLER 'handler_func'
AS $$
import pandas as pd
from typing import Iterator
def handler_func(batch_iter: Iterator[pd.Series]) -> Iterator[pd.Series]:
  for value_batch in batch_iter:
    d = {"min": value_batch.min(), "max": value_batch.max()}
    yield pd.Series([str(d)] * len(value_batch))
$$;
SELECT one_parameter_udf(id), count(*) from range(0, 100000, 3, 8) GROUP BY ALL;

Meerdere parameters: Voor meerdere invoerparameters ontvangt de handler-functie een iterator die over meerdere elementen pandas.Series iterateert. De waarden in de reeks bevinden zich in dezelfde volgorde als de invoerparameters.

%sql
CREATE OR REPLACE TEMPORARY FUNCTION two_parameter_udf(p1 INT, p2 INT)
RETURNS INT
LANGUAGE PYTHON
DETERMINISTIC
PARAMETER STYLE PANDAS
HANDLER 'handler_function'
AS $$
import pandas as pd
from typing import Iterator, Tuple

def handler_function(batch_iter: Iterator[Tuple[pd.Series, pd.Series]]) -> Iterator[pd.Series]:
  for p1, p2 in batch_iter: # same order as arguments above
    yield p1 + p2
$$;
SELECT two_parameter_udf(id , id + 1) from range(0, 100000, 3, 8);

Prestaties optimaliseren door dure bewerkingen te scheiden

U kunt rekenkundige dure bewerkingen optimaliseren door deze bewerkingen te scheiden van de handler-functie. Dit zorgt ervoor dat ze slechts één keer worden uitgevoerd in plaats van tijdens elke iteratie via batches gegevens.

In het volgende voorbeeld ziet u hoe u ervoor kunt zorgen dat een dure berekening slechts eenmaal wordt uitgevoerd:

%sql
CREATE OR REPLACE TEMPORARY FUNCTION expensive_computation_udf(value INT)
RETURNS INT
LANGUAGE PYTHON
DETERMINISTIC
PARAMETER STYLE PANDAS
HANDLER 'handler_func'
AS $$
def compute_value():
  # expensive computation...
  return 1

expensive_value = compute_value()
def handler_func(batch_iter):
  for batch in batch_iter:
    yield batch * expensive_value
$$;
SELECT expensive_computation_udf(id), count(*) from range(0, 100000, 3, 8) GROUP BY ALL

Isolatiegrenzen en -beveiliging

Opmerking

Voor gedeelde isolatieomgevingen is Databricks Runtime 17.1 en hoger vereist. In eerdere versies worden alle Batch Unity Catalog Python UDF uitgevoerd in de strikte isolatiemodus.

Batch Unity Catalog Python UDF's met dezelfde eigenaar kunnen standaard een isolatieomgeving delen. Dit kan de prestaties verbeteren en het geheugengebruik verminderen door het aantal afzonderlijke omgevingen te verminderen dat moet worden gestart.

Strikte isolatie

Voeg de STRICT ISOLATION kenmerkcomponent toe om ervoor te zorgen dat een UDF altijd in een eigen, volledig geïsoleerde omgeving wordt uitgevoerd.

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 van eval(), exec()of vergelijkbare functies
Bestanden schrijven naar het lokale bestandssysteem
Globale variabelen of systeemstatus wijzigen
Omgevingsvariabelen openen of wijzigen

In het volgende voorbeeld ziet u een UDF die invoer als code uitvoert en strikte isolatie vereist:

CREATE OR REPLACE TEMPORARY FUNCTION eval_string(input STRING)
RETURNS STRING
LANGUAGE PYTHON
PARAMETER STYLE PANDAS
HANDLER 'handler_func'
STRICT ISOLATION
AS $$
import pandas as pd
from typing import Iterator

def handler_func(batch_iter: Iterator[pd.Series]) -> Iterator[pd.Series]:
  for code_series in batch_iter:
    def eval_func(code):
      try:
        return str(eval(code))
      except Exception as e:
        return f"Error: {e}"
    yield code_series.apply(eval_func)
$$;

Servicereferenties in Batch Unity Catalog Python UDF's

Batch Unity Catalog Python UDF's kunnen referenties van de Unity Catalog-service gebruiken voor toegang tot externe cloudservices. Dit is met name handig voor het integreren van cloudfuncties, zoals beveiligingstokenizers in werkstromen voor gegevensverwerking.

Opmerking

UDF-specifieke API voor servicereferenties:
Gebruik in UDF's databricks.service_credentials.getServiceCredentialsProvider() om toegang te krijgen tot servicereferenties.

Dit verschilt van de dbutils.credentials.getServiceCredentialsProvider() functie die wordt gebruikt in notebooks, die niet beschikbaar is in UDF-uitvoeringscontexten.

Zie Servicereferenties maken om een servicereferentie te creëren.

Geef de servicereferentie op die u wilt gebruiken in de CREDENTIALS component in de UDF-definitie:

CREATE OR REPLACE TEMPORARY FUNCTION example_udf(data STRING)
RETURNS STRING
LANGUAGE PYTHON
PARAMETER STYLE PANDAS
HANDLER 'handler_function'
CREDENTIALS (
  `credential-name` DEFAULT,
  `complicated-credential-name` AS short_name,
  `simple-cred`,
  cred_no_quotes
)
AS $$
# Python code here
$$;

Machtigingen voor service-inloggegevens

De maker van de UDF moet op de Unity Catalog-service-referentie beschikken over ACCESS toestemming. Voor UDF-aanroepers is het echter voldoende om hen EXECUTE toestemming te geven voor de UDF. In het bijzonder hebben UDF-aanroepers geen toegang nodig tot de onderliggende servicegegevens, omdat de UDF wordt uitgevoerd met behulp van de toegangsrechten van de UDF-maker.

Voor tijdelijke functies is de maker altijd de aanroeper. UDF's die worden uitgevoerd in No-PE bereik, ook wel toegewezen clusters genoemd, gebruiken in plaats daarvan de machtigingen van de beller.

Standaardreferentiegegevens en aliassen

U kunt meerdere referenties opnemen in de CREDENTIALS component, maar er kan slechts één worden gemarkeerd als DEFAULT. U kunt niet-standaardreferenties aliasen met behulp van het AS trefwoord. Elke referentie moet een unieke alias hebben.

Gepatchte cloud-SDK's halen automatisch standaardinloggegevens op. De standaardreferentie heeft voorrang op een standaard die is opgegeven in de Spark-configuratie van de berekening en blijft behouden in de UDF-definitie van de Unity Catalog.

U moet het azure-identity pakket installeren om de DefaultAzureCredential provider te kunnen gebruiken. Gebruik de ENVIRONMENT component om externe bibliotheken te installeren. Zie UDF's uitbreiden met aangepaste afhankelijkheden voor meer informatie over het installeren van externe bibliotheken.

Voorbeeld van servicereferenties - Azure Functions

In het volgende voorbeeld wordt een servicereferentie gebruikt om een Azure-functie aan te roepen vanuit een Batch Unity Catalog Python UDF:

%sql
CREATE OR REPLACE FUNCTION main.test.call_azure_func(data STRING, debug BOOLEAN) RETURNS STRING LANGUAGE PYTHON
PARAMETER STYLE PANDAS
HANDLER 'batchhandler'
CREDENTIALS (
  `batch-udf-service-creds-example-cred` DEFAULT
)
ENVIRONMENT (
  dependencies = '["azure-identity", "requests"]', environment_version = 'None'
)
AS $$
import json
import pandas as pd
import requests
from azure.identity import DefaultAzureCredential
from pyspark.taskcontext import TaskContext


def batchhandler(it):
  # DefaultAzureCredential automatically uses the DEFAULT credential
  credential = DefaultAzureCredential()
  token = credential.get_token("https://management.azure.com/.default")

  # Azure Function URL
  function_url = "https://your-function-app.azurewebsites.net/api/HashValuesFunction"

  # Propagate TaskContext information:
  user_ctx = {"custom": {"user": TaskContext.get().getLocalProperty("user")}}

  for vals, is_debug in it:
    payload = {
      "values": vals.to_list(),
      "is_debug": bool(is_debug[0]),
      "context": user_ctx
    }

    headers = {
      "Authorization": f"Bearer {token.token}",
      "Content-Type": "application/json"
    }

    response = requests.post(function_url, json=payload, headers=headers)

    if response.status_code != 200:
      raise Exception(f"Function call failed: {response.text}")

    response_data = response.json()
    if "errorMessage" in response_data:
      raise Exception(str(response_data))

    yield pd.Series(response_data["values"])
$$;

Roep de UDF aan nadat het is geregistreerd.

SELECT main.test.call_azure_func(data, false)
FROM VALUES
('abc'),
('def')
AS t(data)

Context voor taakuitvoering ophalen

Gebruik de TaskContext PySpark-API om contextinformatie op te halen, zoals de identiteit van de gebruiker, clustertags, spark-taak-id en meer. Zie Taakcontext ophalen in een UDF.

Instellen `DETERMINISTIC` 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 wordt ervan uitgegaan dat Python UDFS voor Batch Unity Catalog niet-deterministioc zijn, tenzij expliciet is gedeclareerd. Voorbeelden van niet-deterministische functies zijn: willekeurige waarden genereren, de huidige tijden of datums openen of externe API-aanroepen uitvoeren.

Zie CREATE FUNCTION (SQL en Python)

Beperkingen

Python-functies moeten onafhankelijk van elkaar waarden verwerken NULL en alle typetoewijzingen moeten azure Databricks SQL-taaltoewijzingen volgen.
Batch Unity Catalog Python UDF's worden uitgevoerd in een beveiligde, geïsoleerde omgeving en hebben geen toegang tot een gedeeld bestandssysteem of interne services.
Meerdere UDF-aanroepen binnen een fase worden geserialiseerd, en tussenresultaten worden gematerialiseerd en kunnen naar de schijf overlopen.
Servicereferenties zijn alleen beschikbaar in Batch Unity Catalog Python UDF's en Scalar Python UDF's. Ze worden niet ondersteund in standaard-Unity Catalog Python UDF's.
Voor toegewezen clusters en voor tijdelijke functies moet de functieoproeper machtigingen hebben ACCESS voor de servicereferenties. Zie Machtigingen verlenen om een servicereferentie te gebruiken voor toegang tot een externe cloudservice.
Schakel de openbare preview-functie Inschakelen netwerken in voor UDF's in serverloze SQL Warehouses op de pagina Previews van uw werkruimte om Batch Unity Catalog Python UDF-aanroepen te maken naar externe services op serverloze SQL Warehouse-rekenkracht.

Als u Batch Unity Catalog Python UDF-aanroepen wilt uitvoeren op een serverloos notebook of taakberekening, moet u serverloze egress-controle configureren.

Feedback

Is deze pagina nuttig?

Last updated on 2025-09-03