Funzioni definite dall'utente (UDF) nel catalogo unity
Importante
Questa funzionalità è disponibile in anteprima pubblica.
Le funzioni definite dall'utente (UDF) nel catalogo unity estendono le funzionalità di SQL e Python in Azure Databricks. Consentono di definire, usare e gestire in modo sicuro le funzioni personalizzate in ambienti di elaborazione.
Le funzioni definite dall'utente Python registrate come funzioni nel catalogo unity differiscono nell'ambito e nel supporto dalle funzioni definite dall'utente pySpark con ambito a un notebook o sparkSession. Vedere Funzioni scalari definite dall'utente - Python.
Per informazioni di riferimento complete sul linguaggio SQL, vedere CREATE FUNCTION (SQL e Python).
Per usare funzioni definite dall'utente nel catalogo unity, è necessario soddisfare i requisiti seguenti:
- Per usare il codice Python nelle funzioni definite dall'utente registrate in Unity Catalog, è necessario usare un serverless o pro SQL Warehouse o un cluster che esegue Databricks Runtime 13.3 LTS o versione successiva.
- Se una vista include una funzione definita dall'utente python uc, avrà esito negativo nei warehouse classici di SQL.
Per creare una funzione definita dall'utente nel catalogo unity, gli utenti devono disporre dell'autorizzazione USAGE e CREATE per lo schema e l'autorizzazione USAGE per il catalogo. Per altri dettagli, vedere Catalogo unity.
Per eseguire una funzione definita dall'utente, gli utenti devono disporre dell'autorizzazione EXECUTE per la funzione definita dall'utente. Gli utenti necessitano anche dell'autorizzazione USAGE per lo schema e il catalogo.
L'esempio seguente registra una nuova funzione nello schema del my_schema
catalogo Unity:
CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight DOUBLE, height DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
AS
SELECT weight / (height * height);
Le funzioni definite dall'utente Python per il catalogo Unity usano le istruzioni offset per segni di dollaro doppio ($$). È anche necessario specificare un mapping dei tipi di dati. L'esempio seguente registra una funzione definita dall'utente che calcola l'indice di massa corporea:
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)
$$;
È ora possibile usare questa funzione del catalogo Unity nelle query SQL o nel codice PySpark:
SELECT person_id, my_catalog.my_schema.calculate_bmi(weight_kg, height_m) AS bmi
FROM person_data;
from pyspark.sql.functions import expr
result = df.withColumn("bmi", expr("my_catalog.my_schema.calculate_bmi(weight_kg, height_m)"))
display(result)
Nota
La sintassi e la semantica per le funzioni definite dall'utente Python nel catalogo unity differiscono dalle funzioni definite dall'utente Python registrate in SparkSession. Vedere Funzioni scalari definite dall'utente - Python.
Data la funzione definita dall'utente basata su sessione seguente in un notebook di Azure Databricks:
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()
Per registrare questa operazione come funzione del catalogo Unity, usare un'istruzione SQL CREATE FUNCTION
, come nell'esempio seguente:
CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
return f"Hello, {name}!"
$$
Le autorizzazioni per le funzioni definite dall'utente vengono gestite in base ai controlli di accesso applicati al catalogo, allo schema o al database in cui è registrata la funzione definita dall'utente. Per altre informazioni, vedere Catalogo unity.
Usare Azure Databricks SQL o l'interfaccia utente dell'area di lavoro di Azure Databricks per concedere autorizzazioni a un utente o a un gruppo (scelta consigliata).
- Trovare il catalogo e lo schema in cui è archiviata la funzione definita dall'utente e selezionare la funzione definita dall'utente.
- Cercare un'opzione Autorizzazioni nelle impostazioni della funzione definita dall'utente. Aggiungere utenti o gruppi e specificare il tipo di accesso che devono avere, ad esempio EXECUTE o MANAGE.
! [Autorizzazioni nell'interfaccia utente dell'area di lavoro](.. /_static/images/udf/high res udf permission.gif)
L'esempio seguente concede a un utente l'autorizzazione EXECUTE per una funzione:
GRANT EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi TO user@example.com;
Per rimuovere le autorizzazioni, usare il REVOKE
comando come nell'esempio seguente:
REVOKE EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi FROM user@example.com;
Per le funzioni definite dall'utente che devono essere accessibili a tutti gli utenti, Databricks consiglia di creare un catalogo e uno schema dedicati con i controlli di accesso appropriati.
Per le funzioni definite dall'utente specifiche del team, usare uno schema dedicato all'interno del catalogo del team per l'archiviazione e la gestione.
Azure Databricks consiglia di includere le informazioni seguenti nella documentazione della funzione definita dall'utente:
- Numero di versione corrente
- Log delle modifiche per tenere traccia delle modifiche tra le versioni
- Scopo, parametri e valore restituito della funzione definita dall'utente
- Esempio di come usare la funzione definita dall'utente
Di seguito è riportato un esempio di procedure consigliate per una funzione definita dall'utente:
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)
$$;
È possibile usare funzioni definite dall'utente per accedere alle API esterne da SQL. L'esempio seguente usa la libreria Python requests
per effettuare una richiesta HTTP.
Nota
Le funzioni definite dall'utente Python consentono il traffico di rete TCP/UDP sulle porte 80, 443 e 53 usando il calcolo serverless o configurato con la modalità di accesso condiviso.
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
$$;
Usare le funzioni definite dall'utente Python per implementare tokenizzazione personalizzata, maschera dati, rollforward dei dati o meccanismi di crittografia.
L'esempio seguente maschera l'identità di un indirizzo di posta elettronica mantenendo la lunghezza e il dominio:
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}"
$$
L'esempio seguente applica questa funzione definita dall'utente in una definizione di visualizzazione dinamica:
-- 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 |
+---+------------+------------------------+------------------------+
- È possibile definire un numero qualsiasi di funzioni Python all'interno di una funzione definita dall'utente Python, ma tutti devono restituire un valore scalare.
- Le funzioni Python devono gestire i valori NULL in modo indipendente e tutti i mapping dei tipi devono seguire i mapping del linguaggio SQL di Azure Databricks.
- È possibile importare librerie Python standard incluse in Azure Databricks, ma non è possibile includere librerie personalizzate o dipendenze esterne.
- Se non viene specificato alcun catalogo o schema, le funzioni definite dall'utente Python vengono registrate nello schema attivo corrente.
- Le funzioni definite dall'utente Python vengono eseguite in un ambiente protetto e isolato e non hanno accesso ai file system o ai servizi interni.