Usa le funzioni dati utente in Fabric Data Warehouse (anteprima)

si applica a:✅ Magazzino di dati in Microsoft Fabric

Importante

Questa funzionalità si trova in Anteprima.

In Fabric Data Warehouse, gli sviluppatori T-SQL possono chiamare le funzioni per i dati utente di Fabric dalle query T-SQL. Una funzione proxy T-SQL in un warehouse chiama la funzione Python di riferimento in un elemento pubblicato delle funzioni di dati utente.

Usa questa integrazione per estendere T-SQL con logica Python riutilizzabile per scenari come:

• Utilizzo di pacchetti PyPI specializzati per carichi di lavoro spaziali, numerici o di data science.
• Implementare logica aziendale personalizzata in Python.
• Chiamare API esterne.
• Interazione con altri elementi di Fabric e i servizi Azure, come data warehouse, lakehouse, database SQL o Cosmos DB.

Questo articolo mostra come fare riferimento a una funzione dati utente pubblicata da Fabric Data Warehouse e utilizzarla nelle query T-SQL.

Prerequisiti

Per utilizzare le funzioni dati utente di Fabric Data Warehouse, è necessario:

• Un magazzino di tessuti.

• Un elemento pubblicato di funzioni di dati utente che contiene la funzione Python che vuoi invocare.

• Accesso in lettura all'elemento delle funzioni dei dati utente e autorizzazione a invocare le relative funzioni pubblicate.

• Permesso di creare una funzione nel magazzino target.

• Una funzione Python che segue il modello di programmazione delle funzioni dati utente. Per i requisiti sintattici, i tipi di input e output supportati e l'uso dei decoratori, vedi panoramica del modello di programmazione delle funzioni dati utente Fabric.

• Se devi creare un nuovo elemento di funzione dati utente, serve anche una capacità Fabric in una regione supportata e uno spazio di lavoro Fabric assegnato a quella capacità. Per dettagli, vedi Creare una funzione dati utente in Fabric e Dettagli e limitazioni delle funzioni dati utente di Fabric.

Crea e pubblica una funzione dati utente

Prima di poter chiamare una funzione dati utente da un warehouse, crea e pubblica la funzione in un elemento di funzione dati utente. Per passaggi completi e funzioni di esempio in Python, vedi Crea un elemento di funzioni dati utente in Fabric.

Una funzione dati utente in Python che potresti creare è mostrata nel seguente esempio:

import fabric.functions as fn

udf = fn.UserDataFunctions()

@udf.function()
def hello_fabric(name: str) -> str:
    # Your function logic here
    return name

Usi il nome dell'elemento della funzione dati utente per associare una funzione proxy T-SQL alla funzione Python.

Crea una funzione proxy T-SQL

Crea una funzione T-SQL nel tuo warehouse e associala alla funzione Python pubblicata usando la AS EXTERNAL FUNCTION clausola.

CREATE OR ALTER FUNCTION dbo.hello_fabric
AS EXTERNAL FUNCTION FunctionSetName.hello_fabric;

Sostituisci FunctionSetName con il nome della funzione dati utente e sostituisci hello_fabric con il nome della funzione Python pubblicata.

Suggerimento

Puoi generare il codice di invocazione dall'esperienza delle funzioni dati utente e usarlo come punto di partenza per la funzione proxy del warehouse.

Di default, l'istruzione CREATE FUNCTION deduce la lista dei parametri e il tipo di ritorno dalla definizione della remota Fabric User Data Function (UDF). Puoi sovrascrivere il tipo di ritorno inferto specificandolo esplicitamente nella definizione della funzione. Fornire il tipo di ritorno è utile quando si vuole esporre un tipo di ritorno più preciso rispetto al tipo dedotto dai metadati della funzione remota.

CREATE OR ALTER FUNCTION dbo.hello_fabric
RETURNS VARCHAR(100)
AS EXTERNAL FUNCTION FunctionSetName.hello_fabric;

Ad esempio, un valore di ritorno in Python str viene tipicamente inferito come VARCHAR(MAX), ma se la funzione restituisce sempre un valore con una lunghezza massima nota, si può definire esplicitamente il tipo di ritorno come VARCHAR(100) o un'altra lunghezza appropriata per fornire metadati e informazioni di tipo più accurate.

Usa funzioni proxy nelle query T-SQL

Dopo aver creato la funzione proxy, chiamala da T-SQL come qualsiasi altra funzione definita dall'utente.

Usa la funzione proxy in espressioni di query come:

• SELECT liste.
• WHERE clausole.
• GROUP BY clausole.
• Espressioni nelle istruzioni UPDATE e INSERT.

Il seguente schema mostra come chiamare una funzione proxy da una query:

SELECT dbo.<proxy_function_name>(<arguments>) AS function_result;

Per i modelli avanzati di Python, i tipi supportati, le connessioni e gli oggetti di contesto, vedi panoramica del modello di programmazione della funzione dati utente di Fabric.

Configura l'esecuzione della modalità batch

Fabric Data Warehouse può eseguire funzioni dati utente esterni in modalità batch.

L'esecuzione in modalità batch invia più invocazioni di funzione in una singola richiesta al servizio remoto Fabric User Data Function (UDF), riducendo il sovraccarico di rete e la latenza delle richieste. Un batch può contenere fino a 900 chiamate di funzione.

La modalità batch è tipicamente utilizzata quando la stessa funzione viene applicata a valori di una o più colonne della tabella, permettendo al processore di query di valutare molte righe in una singola chiamata remota invece di emettere una richiesta separata per ogni riga. Questo metodo può migliorare significativamente le prestazioni delle query, in particolare per grandi dataset e chiamate di funzioni esterne ad alta latenza.

Ad esempio, quando una query applica una funzione dati utente a ogni valore di una colonna, Fabric Data Warehouse può raggruppare i valori di input in batch e inviarli insieme per l'elaborazione remota. Il servizio remoto restituisce un corrispondente lotto di risultati, che vengono poi integrati nella pipeline di esecuzione delle query.

Per abilitare la modalità batch per una funzione dati utente:

1. Apri l'elemento delle funzioni dati utente .
2. Vai su Impostazioni di gestione> della biblioteca.
3. Attiva le funzionalità di Anteprima.

Imposta max_batch_size=900 nel decoratore @udf.function() per consentire al data warehouse di inviare fino a 900 righe di input in ogni invocazione:

Annotazioni

L'argomento max_batch_size è disponibile solo quando è abilitata l'anteprima in modalità batch.

import fabric.functions as fn

udf = fn.UserDataFunctions()

@udf.function(max_batch_size=900)
def normalizeText(value: str) -> str:
    return value.strip().lower()

Dopo aver creato una funzione proxy T-SQL che fa riferimento a una funzione dati utente abilitata a batch (UDF), Fabric Data Warehouse rileva automaticamente la configurazione batch, inclusa la dimensione massima del batch definita dalla funzione remota. Quando il query pattern supporta il batching, il processore di query raggruppa più invocazioni di funzioni in batch e le invia al servizio remoto per l'esecuzione invece di emettere richieste individuali per ogni riga.

Elenca le funzioni dei dati utente in un data warehouse

Le funzioni dati utente che crei con AS EXTERNAL FUNCTION vengono visualizzate in sys.objects con il tipo di oggetto XF.

Per elencare le funzioni dati utente in un warehouse, filtra sys.objects per type = 'XF'.

SELECT SCHEMA_NAME(schema_id) AS schema_name, name, object_id, type, type_desc
FROM sys.objects
WHERE type = 'XF';

Per elencare sia le funzioni scalari regolari (FN) sia le funzioni dati utente (XF) insieme alle loro firme di parametri e tipi di ritorno, si usa sys.parameters e sys.types:

WITH metadata AS
(
    SELECT o.schema_id, o.object_id, o.name, p.parameter_id, p.name AS parameter_name, t.name AS type_name
    FROM sys.objects AS o
    INNER JOIN sys.parameters AS p
        ON p.object_id = o.object_id
    INNER JOIN sys.types AS t
        ON t.user_type_id = p.user_type_id
    WHERE o.type IN ('FN', 'XF')
),
signature AS
(
    SELECT SCHEMA_NAME(schema_id) AS schema_name,
           name,
           ANY_VALUE(
               CASE WHEN parameter_id = 0 THEN type_name END
           ) AS return_type,
           CONCAT(
               SCHEMA_NAME(schema_id),
               '.',
               name,
               '(',
               STRING_AGG(
                   CASE
                       WHEN parameter_id > 0
                       THEN CONCAT(parameter_name, ' ', type_name)
                   END,
                   ', '
               ) WITHIN GROUP (ORDER BY parameter_id),
               ') -> ',
               MAX(CASE WHEN parameter_id = 0 THEN type_name END)
           ) AS signature
    FROM metadata
    GROUP BY schema_id, object_id, name
)
SELECT *
FROM signature;

Osservazioni:

• La funzione proxy T-SQL dipende dal nome dell'elemento e della funzione dei dati utente pubblicati. Se rinomini o elimini la funzione Python, aggiorna di conseguenza la funzione proxy del warehouse.
• Il modello di programmazione delle funzioni dati utente definisce i tipi di input e output supportati. Verifica che le annotazioni Python dei parametri e del valore restituito siano compatibili con i valori trasmessi dalle query T-SQL.
• Le funzioni dati utente hanno limiti di servizio per la dimensione del payload delle richieste, il timeout di esecuzione, la dimensione della risposta, la dimensione della libreria e la ritenzione dei log. Per i limiti attuali, vedi Dettagli del servizio e limitazioni delle funzioni dati utente di Fabric.
• I nomi dei parametri devono usare camelCase e includere annotazioni di tipo. Le funzioni decorate con @udf.function() devono anche specificare un tipo di ritorno. Per le regole sintassiche complete, vedi panoramica del modello di programmazione delle funzioni dei dati utente Fabric.
• Per funzioni di trasformazione del testo integrate che non richiedono codice Python personalizzato, vedi Usa funzioni AI (anteprima).
• Le funzioni dati utente hanno limiti di servizio per la dimensione del payload delle richieste, il timeout di esecuzione, la dimensione della risposta, la dimensione della libreria e la ritenzione dei log. Per i limiti attuali, vedi Dettagli del servizio e limitazioni delle funzioni dati utente di Fabric.
• I nomi dei parametri devono usare camelCase e includere annotazioni di tipo. Le funzioni decorate con @udf.function() devono anche specificare un tipo di ritorno. Per le regole sintassiche complete, vedi panoramica del modello di programmazione delle funzioni dei dati utente Fabric.
• Per funzioni di trasformazione del testo integrate che non richiedono codice Python personalizzato, vedi Usa funzioni AI (anteprima).

Esempi

Gli scenari seguenti mostrano modi comuni per estendere Fabric Data Warehouse con le funzioni dati dell'utente.

A. Estendi T-SQL con parsing degli indirizzi IP

Usa una funzione dati utente in Python quando la query del tuo warehouse necessita di funzionalità che non sono disponibili come funzione T-SQL integrata. Ad esempio, puoi usare un pacchetto di indirizzi IP per restituire la subnet di un indirizzo IP. Puoi applicare questa funzione a batch quando una query elabora indirizzi IP da molte righe. Per i passaggi di configurazione, vedi Configura modalità batch.

Annotazioni

Se la funzione utilizza un pacchetto che non fa parte della libreria standard Python, aggiungi il pacchetto nella gestione delle librerie prima di pubblicare l'elemento della funzione dati utente. Questo esempio utilizza il netaddr package.

Definisci e pubblica la funzione Python in un elemento di funzione dati utente:

from netaddr import IPNetwork
import fabric.functions as fn

udf = fn.UserDataFunctions()

@udf.function(max_batch_size=900)
def ipSubnet(ipAddress: str, prefixLength: int = 24) -> str:
    return str(IPNetwork(f"{ipAddress}/{prefixLength}").cidr)

Crea una funzione proxy T-SQL nel warehouse che faccia riferimento alla funzione Python pubblicata:

CREATE OR ALTER FUNCTION dbo.ip_subnet
AS EXTERNAL FUNCTION inet.ipSubnet;

Chiama la funzione proxy da una query del data warehouse:

SELECT dbo.ip_subnet('192.168.1.25', 24) AS subnet;

Risultato previsto:192.168.1.0/24

B. Invoca un'API pubblica esterna

Usa una funzione dati utente quando una query warehouse deve chiamare un'API esterna come parte di un flusso di lavoro di arricchimento dati.

Nel database SQL di Fabric, in database SQL di Azure e in Istanza gestita di SQL di Azure, sys.sp_invoke_external_rest_endpoint invoca un endpoint REST HTTPS. In Fabric Data Warehouse, una funzione dati utente può fornire un pattern alternativo avvolgendo una chiamata HTTPS in Python ed esponendola a T-SQL tramite una funzione proxy.

Caution

Chiamare un endpoint esterno può trasferire dati fuori dal tuo warehouse. Utilizza endpoint approvati, evita di inviare dati sensibili a meno che non sia autorizzato e segui i requisiti di sicurezza e conformità della tua organizzazione.

Annotazioni

Aggiungi librerie di terze parti obbligatorie, come requests, nella gestione della libreria prima di pubblicare la funzione.

Definisci e pubblica la funzione Python in un elemento di funzione dati utente. Questo esempio utilizza nomi di parametri simili a sys.sp_invoke_external_rest_endpoint:

import json
import requests
import fabric.functions as fn

udf = fn.UserDataFunctions()

@udf.function()
def invokeExternalRestEndpoint(
    url: str,
    method: str = "GET",
    payload: str | None = None,
    headers: str | None = None,
    timeout: int = 30
) -> str:
    requestHeaders = json.loads(headers) if headers else None
    requestPayload = payload if payload else None

    response = requests.request(
        method=method,
        url=url,
        data=requestPayload,
        headers=requestHeaders,
        timeout=timeout
    )
    response.raise_for_status()
    return response.text

Crea una funzione proxy T-SQL nel warehouse:

CREATE OR ALTER FUNCTION dbo.invoke_external_rest_endpoint
AS EXTERNAL FUNCTION api.invokeExternalRestEndpoint;

Chiama la funzione proxy da una query del data warehouse:

SELECT dbo.invoke_external_rest_endpoint(
    'https://ipapi.co/8.8.8.8/country_name/',
    'GET',
    NULL,
    NULL,
    30
) AS response;

C. Utilizzare un periodo di conservazione configurabile

Usa una funzione dati utente quando le query warehouse necessitano di valori di configurazione gestiti centralmente da una libreria di variabili Fabric. Ad esempio, memorizza un periodo di conservazione nella libreria variabile, recuperalo tramite una funzione proxy e usalo come argomento numerico della DATEADD funzione T-SQL.

Prima di pubblicare la funzione, aggiungi una connessione dall'elemento delle funzioni dati utente alla libreria variabile e annota l'alias di connessione. La libreria di variabili in questo esempio contiene un RETENTION_DAYS valore come 90.

Definisci e pubblica la funzione Python in un elemento di funzione dati utente:

import fabric.functions as fn

udf = fn.UserDataFunctions()

@udf.connection(argName="varLib", alias="WarehouseConfig")
@udf.function()
def getRetentionDays(varLib: fn.FabricVariablesClient) -> int:
    variables = varLib.getVariables()
    return int(variables["RETENTION_DAYS"])

Sostituisci WarehouseConfig con l'alias della tua connessione alla libreria variabile.

Crea una funzione proxy T-SQL nel warehouse:

CREATE OR ALTER FUNCTION dbo.get_retention_days
AS EXTERNAL FUNCTION config.getRetentionDays;

Su una connessione T-SQL persistente, recupera il valore configurato una volta e memorizzalo usando sp_set_session_context:

DECLARE @retention_days int = dbo.get_retention_days();

EXECUTE sys.sp_set_session_context
    @key = N'retention_days',
    @value = @retention_days,
    @read_only = 1;

Il valore rimane disponibile per tutta la durata della sessione. Recuperalo con SESSION_CONTEXT e convertilo da sql_variant a int prima di usarlo con DATEADD e GETDATE. Ad esempio, calcola un cutoff di retention:

SELECT DATEADD(
    day,
    -CONVERT(int, SESSION_CONTEXT(N'retention_days')),
    GETDATE()
) AS retention_cutoff;

Riutilizza lo stesso valore della sessione in un'altra istruzione per filtrare una tabella:

SELECT *
FROM dbo.events
WHERE event_timestamp >= DATEADD(
    day,
    -CONVERT(int, SESSION_CONTEXT(N'retention_days')),
    GETDATE()
);

Importante

Utilizza questo schema da un client che mantiene una connessione T-SQL persistente, come SQL Server Management Studio o l'estensione MSSQL per Visual Studio Code. L'editor di query SQL nel portale Fabric non supporta sp_set_session_context, e ogni esecuzione utilizza una sessione separata. Per ulteriori informazioni, vedi limitazioni dell'editor di query SQL.

Risolvere i problemi delle funzioni dei dati utente

Query Insights fornisce le informazioni di esecuzione e prestazioni necessarie per risolvere i problemi delle funzioni di Fabric. Puoi identificare le query che hanno richiamato una funzione, determinare se la funzione ha usato l'elaborazione in batch o per riga e analizzare la latenza del servizio esterno, i tentativi di nuovo invio, le righe non riuscite e la dimensione del payload. Usa le seguenti due viste per passare da una panoramica a livello di query a statistiche dettagliate per ciascuna funzione:

• Usa queryinsights.exec_requests_history per identificare le query che hanno richiamato Fabric o funzioni di IA. La visualizzazione include il testo della richiesta, lo stato, il tempo di invio e il tempo totale trascorso.
• Usalo queryinsights.external_api_call_stats per ottenere statistiche dettagliate per ogni funzione invocata da una query. La visuale include il tipo di funzione, la modalità di esecuzione, il conteggio delle chiamate e dei tentativi di ritorno, il tempo di attesa per il servizio esterno, la dimensione del payload e i risultati delle righe.

Le viste utilizzano distributed_statement_id per identificare la stessa esecuzione della query.

Trova le query che utilizzano funzioni Fabric

Usa queryinsights.exec_requests_history per trovare affermazioni recenti che hanno invocato una funzione Fabric o AI:

SELECT TOP 100
       h.distributed_statement_id,
       h.submit_time,
       h.status,
       h.total_elapsed_time_ms,
       h.command
FROM queryinsights.exec_requests_history AS h
WHERE h.is_using_external_api = 1
ORDER BY h.submit_time DESC;

Copia la distributed_statement_id carta per la dichiarazione che vuoi approfondire. La query successiva filtra le statistiche dettagliate verso le funzioni Fabric.

Visualizza le statistiche per ogni funzione in una dichiarazione

Sostituisci <distributed_statement_id> con un identificatore restituito dalla query precedente. La seguente query restituisce una riga per ogni diversa funzione di Fabric richiamata dall'istruzione:

DECLARE @distributed_statement_id uniqueidentifier =
    '<distributed_statement_id>';

SELECT function_name,
       execution_mode,
       call_count,
       batch_call_count,
       row_call_count,
       call_retry_count,
       external_service_wait_time_ms,
       external_service_wait_time_ms
           / call_count AS average_wait_time_ms_per_call,
       rows_total,
       rows_succeeded,
       rows_failed,
       data_sent_bytes,
       data_received_bytes
FROM queryinsights.external_api_call_stats
WHERE distributed_statement_id = @distributed_statement_id
  AND function_type = 'FABRIC_FUNCTION'
ORDER BY external_service_wait_time_ms DESC;

I risultati ricordano il seguente esempio:

function_name	modalità di esecuzione	call_count	batch_call_count	row_call_count	numero_tentativi_richiamata	external_service_wait_time_ms	tempo_di_attesa_medio_ms_per_chiamata	rows_total	righe completate con successo	righe_non_riuscite	dati_inviati_byte	dati_ricevuti_byte
inet.ipSubnet	batch	12	12	0	0	840	70	600	600	0	12,000	9,600
api.invokeExternalRestEndpoint	row	4	0	4	1	1,920	480	4	4	0	1,024	512

Suggerimenti per la risoluzione dei problemi

• Un valore elevato di row_call_count o un valore di row per execution_mode può indicare che la funzione non utilizza l'esecuzione batch. Se prevedi il batching, conferma che l'anteprima in modalità batch sia abilitata e che la funzione utilizzi l'argomento max_batch_size .
• Usa external_service_wait_time_ms e average_wait_time_ms_per_call per identificare le risposte esterne lente. Se questi valori sono alti e data_sent_bytesdata_received_bytes sono bassi, il tempo di risposta del servizio esterno è probabilmente il ritardo principale.
• I valori grandi data_sent_bytes o data_received_bytes possono anche aumentare i tempi di esecuzione. Riduci il payload in ingresso o uscita quando la funzione trasferisce più dati di quelli richiesti nello scenario.

Contenuti correlati

• Crea un elemento di funzioni dati utente in Fabric
• Panoramica del modello di programmazione delle funzioni dei dati utente Fabric
• Dettagli del servizio e limitazioni delle funzioni dati utente di Fabric