Delen via

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

  • Artikel

Belangrijk

Deze functie is beschikbaar als openbare preview.

Door de gebruiker gedefinieerde functies (UDF's) in Unity Catalog breiden SQL- en Python-mogelijkheden uit binnen Azure Databricks. Hiermee kunnen aangepaste functies worden gedefinieerd, gebruikt en veilig worden gedeeld en beheerd 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 door de gebruiker gedefinieerde scalaire functies - Python.

Zie CREATE FUNCTION (SQL en Python) voor volledige SQL-taalreferenties.

Vereisten

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

  • 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 UC Python UDF bevat, mislukt deze in KLASSIEKE SQL Warehouses.

UDF's maken in Unity Catalog

Als u een UDF in Unity Catalog wilt maken, hebben gebruikers gebruiks- en CREATE-machtigingen nodig voor het schema en gebruiksmachtiging voor de catalogus. Zie Unity Catalog voor meer informatie.

Als u een UDF wilt uitvoeren, hebben gebruikers de machtiging EXECUTE nodig voor de UDF. Gebruikers hebben ook gebruiksmachtigingen nodig voor het schema en de catalogus.

In het volgende voorbeeld wordt een nieuwe functie geregistreerd in het my_schema Unity Catalog-schema:

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

Python UDF's voor Unity Catalog gebruiken instructies offset door dubbele dollartekens ($$). U moet ook een toewijzing van gegevenstypen opgeven. In het volgende voorbeeld wordt een UDF geregistreerd waarmee de hoofdmassaindex wordt berekend:

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

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;

De Unity Catalog UDF 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 sessiegebaseerde 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-instructie CREATE FUNCTION , 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}!"
$$

UDF's delen in Unity Catalog

Machtigingen voor UDF's worden beheerd op basis van de toegangsbeheer die zijn toegepast op de catalogus, het schema of de database waarop de UDF is geregistreerd. Zie 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](.. /_static/images/udf/high res udf permission.gif)

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 REVOKE opdracht zoals in het volgende voorbeeld:

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

Aanbevolen procedures voor UDF's

Voor UDF's die toegankelijk moeten zijn voor alle gebruikers, raadt Databricks aan om een speciale catalogus en schema te maken met de juiste toegangsbeheer.

Gebruik voor teamspecifieke UDF's een speciaal schema in de catalogus van het team voor opslag en beheer.

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

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

Hier volgt een voorbeeld van een UDF met de volgende aanbevolen procedures:

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

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 met behulp van serverloze rekenkracht of berekening die is geconfigureerd met de modus voor gedeelde toegang.

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

$$;

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
AS $$
parts = email.split('@')
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 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 |
+---+------------+------------------------+------------------------+

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.
  • U kunt standaard Python-bibliotheken importeren die zijn opgenomen in Azure Databricks, maar u kunt geen aangepaste bibliotheken of externe afhankelijkheden opnemen.
  • Als er geen catalogus of schema is opgegeven, worden Python UDF's geregistreerd bij het huidige actieve schema.
  • Python UDF's worden uitgevoerd in een beveiligde, geïsoleerde omgeving en hebben geen toegang tot bestandssystemen of interne services.