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 gör att anpassade funktioner kan definieras, användas och delas på ett säkert sätt och styras 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 Användardefinierade skalärfunktioner – Python.

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

Krav

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

• 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 UC Python UDF misslyckas den på klassiska SQL-lager.

Skapa UDF:er i Unity-katalogen

För att skapa en UDF i Unity Catalog behöver användarna behörigheten USAGE och CREATE för schemat och ANVÄNDNINGsbehörigheten i 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.

I följande exempel registreras en ny funktion i my_schema Unity Catalog-schemat:

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:er för Unity Catalog använder instruktioner som förskjuts av dubbla dollartecken ($$). Du måste också ange en datatypsmappning. I följande exempel registreras en UDF som beräknar massindex för brödtext:

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

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;

Använda Unity Catalog UDF 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 med sessionsomfattning

Med följande sessionsbaserade 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-instruktion CREATE FUNCTION , 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

Behörigheter för UDF:er hanteras baserat på de åtkomstkontroller som tillämpas på katalogen, schemat eller databasen där UDF är registrerad. Mer information finns 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 användargränssnitt

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 ska 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 REVOKE kommandot som i följande exempel:

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

Metodtips för UDF:er

För UDF:er som måste 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 teamets katalog för lagring och hantering.

Azure Databricks rekommenderar att du inkluderar följande information i UDF:s dokumentsträng:

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

Här är ett exempel på en UDF enligt bästa praxis:

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: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()
   # 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:er för säkerhet och efterlevnad

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

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.
• Du kan importera python-standardbibliotek som ingår i Azure Databricks, men du kan inte inkludera anpassade bibliotek eller externa beroenden.
• Om ingen katalog eller schema har angetts registreras Python-UDF:er i 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.