Condividi tramite

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 Python UDF registrate come funzioni nel Catalogo Unity differiscono nell'ambito e nel supporto dalle UDF di PySpark con ambito a un notebook o SparkSession. Vedere Funzioni scalari definite dall'utente - Python.

Per informazioni di riferimento complete sul linguaggio SQL, vedere (SQL e Python).

Requisiti

Per utilizzare le funzioni definite dall'utente nel Unity Catalog, è necessario soddisfare i seguenti requisiti:

  • Per usare il codice Python nelle funzioni definite dall'utente registrate nel Catalogo Unity, è necessario usare un SQL Warehouse serverless o pro, o un cluster che esegue Databricks Runtime 13.3 LTS o versione successiva.
  • Se una vista include una UC Python UDF, fallirà nei warehouse classici di SQL.

Creazione di UDF (funzioni definite dall'utente) nel catalogo Unity

Per creare una funzione definita dall'utente nel catalogo Unity, gli utenti devono disporre dell'autorizzazione USAGE e CREATE per lo schema e dell'autorizzazione USAGE per il catalogo. Per altri dettagli, vedere del catalogo Unity.

Per eseguire una funzione definita dall'utente (UDF), gli utenti devono disporre dell'autorizzazione EXECUTE sulla UDF. Gli utenti necessitano anche dell'autorizzazione USAGE per lo schema e il catalogo.

L'esempio seguente registra una nuova funzione nello schema del catalogo Unity my_schema:

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

Le funzioni definite dall'utente Python per il Catalogo Unity utilizzano istruzioni delimitate dai doppi segni di dollaro ($$). È 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 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)
$$;

È 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;

Ampliare le funzioni definite dall'utente utilizzando dipendenze personalizzate

Importante

Questa funzionalità è disponibile in anteprima pubblica.

Estendere le funzionalità delle UDF Python del catalogo Unity oltre l'ambiente del Databricks Runtime, definendo le dipendenze personalizzate per le librerie esterne.

Installare le dipendenze dalle seguenti fonti.

  • Pacchetti PyPi
  • File archiviati nei volumi di Unity Catalog L'utente che richiama la UDF deve disporre READ VOLUME delle autorizzazioni per il volume di origine.
  • File disponibili negli URL pubblici Le regole di sicurezza di rete dell'area di lavoro devono consentire l'accesso agli URL pubblici.

Nota

Per configurare le regole di sicurezza di rete per consentire l'accesso agli URL pubblici da un sql warehouse serverless, vedere Convalidare con Databricks SQL.

  • I Serverless SQL Warehouses richiedono che la funzionalità Anteprima Pubblica Abilita rete per le UDF nei Serverless SQL Warehouses sia attivata per accedere a Internet per le dipendenze personalizzate.

Le dipendenze personalizzate per le UDF del Unity Catalog sono supportate nei tipi di calcolo seguenti:

  • Serverless notebook e attività
  • Calcolo tutto scopo con Databricks Runtime versione 16.2 e successive
  • SQL Warehouse classico o Pro

Utilizzare la sezione ENVIRONMENT della definizione della funzione definita dall'utente per specificare le dipendenze:

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 = 'None'
)
AS $$
import simplejson as json
import custom_package
return json.dumps(custom_package.process(data))
$$;

La ENVIRONMENT sezione contiene i campi seguenti:

Campo Descrizione TIPO Esempio di utilizzo
dependencies STRING Elenco delle dipendenze separate da virgole da installare. Ogni voce è una stringa conforme al formato di file pip Requirements. 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 STRING Specifica la versione dell'ambiente serverless in cui eseguire la UDF (funzione definita dall'utente).
Attualmente è supportato solo il valore None .		 environment_version = 'None'

Utilizzo della UDF del catalogo Unity 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)

Aggiornare una funzione definita dall'utente con ambito sessione

Nota

La sintassi e la semantica per le funzioni definite dall'utente Python nel Unity Catalog 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}!"
$$

Condividere UDF nel catalogo Unity

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 del 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).

Autorizzazioni nell'interfaccia utente dell'area di lavoro

  1. Trova il catalogo e lo schema in cui è archiviata la UDF e seleziona l'UDF.
  2. Cercare un'opzione Autorizzazioni nelle impostazioni dell'UDF. 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

Autorizzazioni con Azure Databricks SQL

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 comando REVOKE come nell'esempio seguente:

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

Migliori pratiche per le funzioni definite dall'utente

Affinché le funzioni definite dall'utente siano accessibili a tutti gli utenti, Databricks consiglia di creare un catalogo e uno schema dedicati con controlli di accesso appropriati.

Per le funzioni specifiche del team definite dall'utente, utilizzare uno schema dedicato all'interno del catalogo del team per la gestione e l'archiviazione.

Azure Databricks consiglia di includere le seguenti informazioni nel docstring dell'UDF:

  • 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
  • Un esempio di come usare la UDF (funzione definita dall'utente)

Ecco un esempio di una funzione definita dall'utente (UDF) che segue le migliori pratiche:

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

Funzioni definite dall'utente per gli strumenti dell'agente di intelligenza artificiale

Gli agenti di intelligenza artificiale generativa possono utilizzare le funzioni definite dall'utente (UDF) del Catalogo Unity come strumenti per svolgere compiti ed eseguire logica personalizzata.

Consulta le funzioni del Catalogo Unity per creare strumenti dell'agente di intelligenza artificiale personalizzati.

Funzioni UDF (definite dall'utente) per l'accesso alle API esterne

È possibile usare le funzioni definite dall'utente per accedere da SQL alle API esterne. L'esempio seguente usa la libreria Python requests per effettuare una richiesta HTTP.

Nota

Le funzioni definite dall'utente in Python consentono il traffico di rete TCP/UDP sulle porte 80, 443 e 53 utilizzando elaborazione serverless o elaborazione configurata con la modalità di accesso standard.

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

$$;

Funzioni definite dall'utente per la sicurezza e la conformità

Usare le funzioni definite dall'utente Python per implementare tokenizzazione personalizzata, mascheramento dei dati, redazione 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 = parts[0][0] + '*' * (len(parts[0]) - 2) + parts[0][-1]
return f"{masked_username}@{domain}"
$$

L'esempio seguente applica questa UDF 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 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 |
+---+------------+------------------------+------------------------+

Limiti

  • È possibile definire un numero qualsiasi di funzioni Python all'interno di una funzione definita dall'utente (UDF) di Python, ma tutte queste 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.
  • Se non viene specificato alcun catalogo o schema, le funzioni definite dall'utente di Python vengono registrate nello schema attivo corrente.
  • Le funzioni definite dall'utente (UDF) di Python vengono eseguite in un ambiente protetto e isolato e non hanno accesso ai sistemi di file o ai servizi interni.
  • Non è possibile chiamare più di cinque funzioni definite dall'utente per ogni query.