Bruk brukerdatafunksjoner i Fabric datalager (forhåndsvisning)

Gjelder for:✅ Warehouse i Microsoft Fabric

I Fabric datalager kan T-SQL-utviklere kalle Fabric brukerdatafunksjoner fra T-SQL-spørringer. En T-SQL-proxy-funksjon i et lager kaller den refererte Python-funksjonen i et publisert brukerdata-funksjonselement.

Bruk denne integrasjonen til å utvide T-SQL med gjenbrukbar Python-logikk for scenarier som:

• Å bruke spesialiserte PyPI-pakker for romlige, numeriske eller datavitenskapelige arbeidsbelastninger.
• Implementering av egendefinert forretningslogikk i Python.
• Kalle eksterne API-er.
• Samhandling med andre Fabric-elementer og Azure-tjenester, som lagre, innsjøhus, SQL-databaser eller en Cosmos-database.

Denne artikkelen viser hvordan man refererer til en publisert brukerdatafunksjon fra Fabric datalager og bruker den i T-SQL-spørringer.

Forutsetninger

For å bruke brukerdatafunksjoner fra Fabric datalager, trenger du:

• Et stofflager.

• Et publisert element for brukerdatafunksjoner som inneholder Python-funksjonen du ønsker å kalle.

• Lesetilgang til brukerdatafunksjonselementet og tillatelse til å kalle de publiserte funksjonene.

• Tillatelse til å opprette en funksjon i mållageret.

• En Python-funksjon som følger programmeringsmodellen for brukerdatafunksjoner. For syntakskrav, støttede inn- og utdatatyper, samt bruk av dekoratorer, se Fabric user data function programming model overview.

• Hvis du trenger å opprette et nytt element for brukerdatafunksjoner, trenger du også en Fabric-kapasitet i en støttet region og et Fabric-arbeidsområde tildelt den kapasiteten. For detaljer, se Opprett en brukerdatafunksjon i Fabric and Service detaljer og begrensninger for Fabric brukerdatafunksjoner.

Opprett og publiser en brukerdatafunksjon

Før du kan kalle en user data-funksjon fra et warehouse, bør du opprette og publisere funksjonen i et user data functions-element. For komplette steg og eksempler på Python-funksjoner, se Opprett et element for brukerdatafunksjoner i Fabric.

En Python-funksjon for brukerdata som du kan lage, vises i følgende eksempel:

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Du bruker navnet på brukerdatafunksjonen for å binde en T-SQL-proxyfunksjon til Python-funksjonen.

Opprett en T-SQL-proxy-funksjon

Lag en T-SQL-funksjon i lageret ditt og bind den til den publiserte Python-funksjonen ved å bruke klausulenAS EXTERNAL FUNCTION.

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

Erstatt FunctionSetName med navnet på brukerdatafunksjonene dine, og erstatt hello_fabric med navnet på den publiserte Python-funksjonen.

Som standard utleder CREATE FUNCTION-setningen parameterlisten og returtypen fra definisjonen av den eksterne Fabric User Data Function (UDF). Du kan overstyre den utledte returtypen ved å spesifisere den eksplisitt i funksjonsdefinisjonen. Å oppgi returtypen er nyttig når du ønsker å eksponere en mer presis returtype enn typen som er utledet fra den eksterne funksjonsmetadataen.

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

For eksempel blir en Python-returverdi str vanligvis utledet som VARCHAR(MAX), men hvis funksjonen alltid returnerer en verdi med kjent maksimal lengde, kan du eksplisitt definere returtypen som VARCHAR(100) eller en annen passende lengde for å gi mer nøyaktig metadata og typeinformasjon.

Bruk proxy-funksjoner i T-SQL-spørringer

Etter at du har opprettet proxy-funksjonen, kall den fra T-SQL som en hvilken som helst annen brukerdefinert funksjon.

Bruk proxy-funksjonen i spørringsuttrykk som:

• SELECT lister.
• WHERE klausuler.
• GROUP BY klausuler.
• Uttrykk i UPDATE og INSERT uttalelser.

Følgende mønster viser hvordan man kaller en proxy-funksjon fra en spørring:

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

For avanserte Python-mønstre, støttede typer, forbindelser og kontekstobjekter, se Fabric user data function programming model overview.

Konfigurer batchmodus-utførelse

Fabric datalager kan utføre eksterne brukerdatafunksjoner i batchmodus.

Batch-modus kjøring sender flere funksjonskall i én enkelt forespørsel til den eksterne Fabric User Data Function (UDF)-tjenesten, noe som reduserer nettverksoverhead og forespørselsforsinkelse. En batch kan inneholde opptil 900 funksjonskall.

Batch-modus brukes vanligvis når samme funksjon brukes på verdier fra én eller flere tabellkolonner, slik at spørringsprosessoren kan evaluere mange rader i et enkelt fjernanrop i stedet for å sende en separat forespørsel for hver rad. Denne metoden kan betydelig forbedre spørringsytelsen, spesielt for store datasett og eksterne funksjonskall med høy forsinkelse.

For eksempel, når en spørring anvender en user data-funksjon på hver verdi i en kolonne, kan Fabric datalager gruppere inndataverdiene i batcher og sende dem sammen for fjernbehandling. Den eksterne tjenesten returnerer en tilsvarende batch med resultater, som deretter integreres i spørringskjøringspipelinen.

For å aktivere batch-modus for en user data-funksjon:

1. Åpne elementet for User Data Functions .
2. Gå tilInnstillinger for bibliotekadministrasjon>.
3. Slå på forhåndsvisningsfunksjonene.

Satt max_batch_size=900 i dekoratoren @udf.function() slik at lageret kan sende opptil 900 inndatarader i hver invokasjon:

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Etter at du har opprettet en T-SQL-proxyfunksjon som refererer til en batch-aktivert brukerdatafunksjon (UDF), oppdager Fabric datalager automatisk batch-konfigurasjonen, inkludert maksimal batchstørrelse definert av fjernfunksjonen. Når spørringsmønsteret støtter batching, grupperer spørringsprosessoren flere funksjonskall i batcher og sender dem til den eksterne tjenesten for utførelse i stedet for å sende individuelle forespørsler for hver rad.

List opp brukerdatafunksjoner i et varehus

Brukerdatafunksjoner du oppretter med AS EXTERNAL FUNCTION vises i sys.objects med objekttypen XF.

For å liste brukerdatafunksjoner i et lager, filtrer sys.objects etter type = 'XF'.

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

For å liste både vanlige skalarfunksjoner (FN) og brukerdatafunksjoner (XF) sammen med deres parameter- og returtypesignaturer, bruk sys.parameters og 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;

Merknader

• T-SQL-proxyfunksjonen avhenger av det publiserte elementet for brukerdatafunksjoner og funksjonsnavn. Hvis du gir nytt navn eller sletter Python-funksjonen, oppdater lagerproxy-funksjonen deretter.
• Programmeringsmodellen for brukerdatafunksjoner definerer de støttede inn- og utdatatypene. Sjekk at Python-parameteren og returannotasjonene støtter verdiene T-SQL-spørringene dine gir.
• Brukerdatafunksjoner har tjenestebegrensninger for forespørslingslaststørrelse, utførelsestid, svarstørrelse, bibliotekstørrelse og logglagring. For nåværende begrensninger, se Tjenestedetaljer og begrensninger for Fabric-brukerdatafunksjoner.
• Parameternavn må bruke camelCase og inkludere typeannotasjoner. Funksjoner dekorert med @udf.function() må også spesifisere en returtype. For fullstendige syntaksregler, se Fabric user data function programming model overview.
• For innebygde teksttransformasjonsfunksjoner som ikke krever egendefinert Python-kode, se Bruk AI-funksjoner (forhåndsvisning).
• Brukerdatafunksjoner har tjenestebegrensninger for forespørslingslaststørrelse, utførelsestid, svarstørrelse, bibliotekstørrelse og logglagring. For nåværende begrensninger, se Tjenestedetaljer og begrensninger for Fabric-brukerdatafunksjoner.
• Parameternavn må bruke camelCase og inkludere typeannotasjoner. Funksjoner dekorert med @udf.function() må også spesifisere en returtype. For fullstendige syntaksregler, se Fabric user data function programming model overview.
• For innebygde teksttransformasjonsfunksjoner som ikke krever egendefinert Python-kode, se Bruk AI-funksjoner (forhåndsvisning).

Eksempler

Følgende scenarioer viser vanlige måter å utvide Fabric datalager med brukerdatafunksjoner.

A. Utvid T-SQL med IP-adresseparsing

Bruk en Python-user data-funksjon når lagerspørringen din trenger funksjonalitet som ikke er tilgjengelig som en innebygd T-SQL-funksjon. For eksempel kan du bruke en IP-adressepakke for å returnere subnettet for en IP-adresse. Du kan bruke denne funksjonen i batcher når en spørring behandler IP-adresser fra mange rader. For konfigurasjonstrinn, se Konfigurer batchmodus.

Definer og publiser Python-funksjonen i et element for brukerdatafunksjoner:

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)

Lag en T-SQL-proxy-funksjon i lageret som refererer til den publiserte Python-funksjonen:

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

Kall proxy-funksjonen fra en warehouse-spørring:

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

Forventet resultat:192.168.1.0/24

B. Kall et eksternt offentlig API

Bruk en user data-funksjon når en warehouse-forespørsel må kalle et eksternt API som en del av en databerikelsesarbeidsflyt.

I SQL database in Fabric, Azure SQL Database og Azure SQL Managed Instance, sys.sp_invoke_external_rest_endpoint kaller de et HTTPS REST-endepunkt. I Fabric datalager kan en user data-funksjon gi et alternativt mønster ved å pakke inn et HTTPS-kall i Python og eksponere det for T-SQL via en proxy-funksjon.

Definer og publiser Python-funksjonen i et element for brukerdatafunksjoner. Dette eksempelet bruker parameternavn som ligner på 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

Opprett en T-SQL-proxy-funksjon i lageret:

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

Kall proxy-funksjonen fra en warehouse-spørring:

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

C. Bruk en konfigurerbar oppbevaringstid

Bruk en user data-funksjon når warehouse-spørringer trenger sentralt administrerte konfigurasjonsverdier fra et Fabric-variabelbibliotek. For eksempel, lagre en oppbevaringsperiode i variabelbiblioteket, hent den gjennom en proxy-funksjon, og bruk den som tallargument for DATEADD T-SQL-funksjonen.

Før du publiserer funksjonen, legg til en tilkobling fra brukerdatafunksjonene i variabelbiblioteket og merk tilkoblingsaliaset. Variabelbiblioteket i dette eksempelet inneholder en RETENTION_DAYS verdi som 90.

Definer og publiser Python-funksjonen i et element for brukerdatafunksjoner:

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"])

Erstatt WarehouseConfig med aliaset til tilkoblingen til variabelbiblioteket ditt.

Opprett en T-SQL-proxy-funksjon i lageret:

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

På en vedvarende T-SQL-tilkobling, hent den konfigurerte verdien én gang og lagre den ved å bruke 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;

Verdien forblir tilgjengelig gjennom hele øktens levetid. Hente den med SESSION_CONTEXT og konverter den fra sql_variant til int før du bruker den med DATEADD og GETDATE. For eksempel, beregn en retensjonsgrense:

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

Gjenbruk samme sesjonsverdi i en annen setning for å filtrere en tabell:

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

Feilsøk brukerdatafunksjoner

Query Insights gir utførelses- og ytelsesinformasjonen du trenger for å feilsøke Fabric-funksjoner. Du kan identifisere spørringer som har startet en funksjon, avgjøre om funksjonen brukte batch- eller radkjøring, og undersøke ekstern tjenesteforsinkelse, reforsøk, mislykkede rader og nyttelaststørrelse. Bruk følgende to visninger for å gå fra en spørringsnivåoversikt til detaljerte statistikker for hver funksjon:

• Bruk queryinsights.exec_requests_history den til å identifisere spørringer som påkalte Fabric- eller AI-funksjoner. Visningen inkluderer spørringsteksten, status, innsendingstid og total forløpstid.
• Bruk queryinsights.external_api_call_stats for å få detaljerte statistikker for hver funksjon som aktiveres av en spørring. Visningen inkluderer funksjonstype, utførelsesmodus, antall anrop og gjenprøvinger, ventetid for eksterne tjenester, nyttelaststørrelse og radresultater.

Visningene brukes distributed_statement_id til å identifisere den samme spørringsutførelsen.

Finn spørringer som brukte Fabric-funksjoner

Bruk queryinsights.exec_requests_history det for å finne nylige utsagn som påkalte en Fabric- eller AI-funksjon:

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;

Kopier den distributed_statement_id for uttalelsen du ønsker å undersøke. Neste spørring filtrerer de detaljerte statistikkene til Fabric-funksjoner.

Se statistikk for hver funksjon i en setning

Erstatt <distributed_statement_id> med en identifikator som ble returnert av forrige spørring. Følgende spørring returnerer én rad for hver distinkt Fabric-funksjon som påkalles av setningen:

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;

Resultatene ligner følgende eksempel:

Feilsøkingstips

• En høy row_call_count eller en execution_mode verdi på row kan indikere at funksjonen ikke bruker batch-kjøring. Hvis du forventer batching, bekreft at batch-modus forhåndsvisning er aktivert og at funksjonen bruker argumentet max_batch_size .
• Bruk external_service_wait_time_ms og average_wait_time_ms_per_call for å identifisere langsomme ytre responser. Hvis disse verdiene er høye mens data_sent_bytes og data_received_bytes er lave, er responstiden for ekstern tjeneste sannsynligvis den primære forsinkelsen.
• Store data_sent_bytes eller data_received_bytes verdier kan også øke utførelsestiden. Reduser input- eller output-nyttelasten når funksjonen overfører mer data enn scenarioet krever.

Relatert innhold

• Opprett et element for brukerdatafunksjoner i Fabric
• Oversikt over Fabric user data function programmeringsmodell
• Tjenestedetaljer og begrensninger for Fabric-brukerdatafunksjoner