Käytä käyttäjätietotoimintoja Fabric tietovarasto (esikatselu)

Sovellettavissa:✅ Varasto Microsoft Fabric

Vuonna Fabric tietovarasto T-SQL-kehittäjät voivat kutsua Fabric käyttäjädatan funktioita T-SQL-kyselyistä. Varaston T-SQL-välitysfunktio kutsuu viitattua Python-funktiota julkaistussa käyttäjätietofunktioissa.

Käytä tätä integraatiota laajentaaksesi T-SQL:ää uudelleenkäytettävällä Python-logiikalla esimerkiksi seuraavissa tilanteissa:

• Käytetään erikoistuneita PyPi-paketteja tilallisiin, numeerisiin tai data-analytiikan työkuormiin.
• Räätälöidyn liiketoimintalogiikan toteuttaminen Python-ohjelmassa.
• Ulkoisten rajapintojen kutsuminen.
• Vuorovaikutus muiden Fabric-elementtien ja Azure-palveluiden, kuten varastojen, järvitalojen, SQL-tietokantojen tai Cosmos-tietokannan kanssa.

Tässä artikkelissa näytetään, miten Fabric tietovarasto julkaistuun käyttäjätietofunktioon viitataan ja sitä käytetään T-SQL-kyselyissä.

Edellytykset

Käyttäjätietojen funktioiden käyttämiseksi Fabric tietovarasto:stä tarvitset:

• Fabric-varasto.

• Julkaistu käyttäjätietofunktioiden alkio, joka sisältää Python-funktion, jonka haluat kutsua.

• Lue käyttöoikeus käyttäjätietofunktioiden kohteeseen ja oikeus sen julkaistujen funktioiden kutsumiseen.

• Lupa luoda toiminto kohdevarastossa.

• Python-funktio, joka noudattaa käyttäjätietofunktioiden ohjelmointimallia. Syntaksivaatimukset, tuetut syöte- ja tulostustyypit sekä koristelijoiden käyttö löytyy Fabric-käyttäjädatan funktioohjelmointimallin yleiskatsauksesta.

• Jos tarvitset uuden käyttäjätietofunktioiden kohteen, tarvitset myös Fabric-kapasiteetin tuetulla alueella ja Fabric-työtilan sille ominaisena. Lisätietoja löytyy osoitteesta Create a user data functions -kohde Fabric and Service -osiossa Tiedot ja rajoitukset Fabric-käyttäjätietofunktioille.

Luo ja julkaise käyttäjätietofunktio

Ennen kuin voit kutsua käyttäjätietofunktiota varastosta, luo ja julkaise funktio käyttäjätietofunktioiden kohteessa. Täydelliset vaiheet ja esimerkki Python-funktioista löydät kohdasta Luo käyttäjätietofunktioiden kohde Fabric-tiedostossa.

Seuraavassa esimerkissä on esitetty Python-käyttäjätietofunktio, jonka voisit luoda:

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Käytät käyttäjätietofunktion nimeä sitomaan T-SQL-välitysfunktion Python-funktioon.

Luo T-SQL-proxy-funktio

Luo varastoosi T-SQL-funktio ja sido se julkaistuun Python-funktioon käyttämällä lausekettaAS EXTERNAL FUNCTION.

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

Korvaa FunctionSetName käyttäjätietofunktioiden nimi ja hello_fabric korvaa se julkaistun Python-funktion nimellä.

Oletuksena CREATE FUNCTION -lause päättelee parametrilistan ja palautustyypin etä-Fabric User Data Functionin (UDF) määritelmästä. Voit ohittaa päätellyn palautustyypin määrittämällä sen eksplisiittisesti funktiomääritelmässä. Palautustyypin tarjoaminen on hyödyllistä, kun haluat paljastaa tarkemman palautustyypin kuin etäfunktioiden metatiedoista päätelty tyyppi.

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

Esimerkiksi Python-palautusarvo str päätelletään tyypillisesti muodossa VARCHAR(MAX), mutta jos funktio aina palauttaa arvon, jonka suurin pituus on tunnettu, voit määritellä palautustyypin eksplisiittisesti tai VARCHAR(100) johonkin sopivaan pituuteen, jotta saadaan tarkempaa metatietoa ja tyyppitietoa.

Käytä välityspalvelinfunktioita T-SQL-kyselyissä

Kun olet luonut proxy-funktion, kutsu se T-SQL:stä kuten mikä tahansa muu käyttäjän määrittelemä funktio.

Käytä proxy-funktiota kyselylausekkeissa, kuten:

• SELECT listoja.
• WHERE ehtoja.
• GROUP BY ehtoja.
• Ilmaisuja UPDATE ja INSERT lausuntoja.

Seuraava malli näyttää, miten proxy-funktio kutsutaan kyselystä:

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

Edistyneistä Python-kaavoista, tuetuista tyypeistä, yhteyksistä ja kontekstiobjekteista löytyy Fabric User Data -funktioohjelmointimallin yleiskatsauksesta.

Määritä eräajotilan suoritus

Fabric tietovarasto voivat suorittaa ulkoisia käyttäjätietotoimintoja eräajotilassa.

Eräajotilan suoritus lähettää useita funktioiden kutsuja yhdessä pyynnössä etä-Fabric User Data Function (UDF) -palvelulle, mikä vähentää verkon kuormitusta ja pyyntöjen viivettä. Erä voi sisältää jopa 900 funktiokutsua.

Eräajotilaa käytetään tyypillisesti, kun sama funktio sovelletaan arvoihin yhdestä tai useammasta taulukon sarakkeesta, jolloin kyselyprosessori voi arvioida useita rivejä yhdessä etäkutsussa sen sijaan, että jokaiselle riville olisi erillinen pyyntö. Tämä menetelmä voi merkittävästi parantaa kyselyjen suorituskykyä, erityisesti suurissa tietoaineistoissa ja korkean viiveen ulkoisissa funktiokutsuissa.

Esimerkiksi, kun kysely soveltaa käyttäjätietofunktiota jokaiseen sarakkeen arvoon, Fabric tietovarasto voi ryhmitellä syötearvot eriksi ja lähettää ne yhdessä etäkäsittelyä varten. Etäpalvelu palauttaa vastaavan erän tuloksia, jotka integroidaan kyselyn suoritusputkeen.

Eräajotilan käyttöönotto käyttäjätietotoiminnolle:

1. Avaa käyttäjätietofunktioiden kohta.
2. Mene Kirjastonhallinta-asetuksiin>.
3. Ota esikatseluominaisuudet päälle.

Aseta max_batch_size=900 koristeluun @udf.function() niin, että varasto voi lähettää jopa 900 syöttöriviä jokaisessa kutsussa:

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Kun luot T-SQL-välityspalvelimen, joka viittaa eräajoon perustuvaan käyttäjätietofunktioon (UDF), Fabric tietovarasto tunnistaa automaattisesti eräkonfiguraation, mukaan lukien etäfunktion määrittelemän maksimierän koon. Kun kyselymalli tukee eräajoa, kyselyprosessori ryhmittelee useita funktiokutsuja eriksi ja lähettää ne etäpalveluun suoritettavaksi sen sijaan, että lähettäisi yksittäisiä pyyntöjä jokaiselle riville.

Listaa käyttäjätietotoiminnot varastossa

Käyttäjätietofunktiot, joilla luot AS EXTERNAL FUNCTION , ilmestyvät sys.objects objektityypillä XF.

Käyttäjätietofunktioiden listaamiseen varastossa suodata sys.objects .type = 'XF'

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

Luetteloidaksesi sekä säännölliset skalaarifunktiot (FN) että käyttäjätietofunktiot (XF) sekä niiden parametrien ja palautustyyppien allekirjoitukset, käytä sys.parameters ja 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;

Huomautuksia

• T-SQL-välityspalvelinfunktio riippuu julkaistusta käyttäjätietofunktioiden alkiosta ja funktion nimestä. Jos nimeät tai poistat Python-funktion, päivitä varaston välityspalvelintoiminto sen mukaisesti.
• Käyttäjätietofunktioiden ohjelmointimalli määrittelee tuetut syöte- ja lähtötyypit. Varmista, että Python-parametri ja palautusmerkinnät tukevat T-SQL-kyselyjesi välittämiä arvoja.
• Käyttäjätietofunktioilla on palvelurajoituksia pyynnön hyötykuorman koon, suorituksen aikakatkaisun, vastekoon, kirjaston koon ja lokien säilyttämisen suhteen. Nykyiset rajoitukset löytyvät osoitteesta Service Details and Limitations of Fabric User Data Functions.
• Parametrien nimissä on käytettävä camelCasea ja niissä on oltava tyyppimerkinnät. Funktioilla @udf.function() koristeltujen funktioiden on myös määriteltävä palautustyyppi. Täydelliset syntaksisäännöt löytyvät Fabric-käyttäjädatan funktioohjelmointimallin yleiskatsauksesta.
• Sisäänrakennetut tekstimuunnosfunktiot, jotka eivät vaadi mukautettua Python-koodia, katso Käytä tekoälyfunktioita (esikatselu).
• Käyttäjätietofunktioilla on palvelurajoituksia pyynnön hyötykuorman koon, suorituksen aikakatkaisun, vastekoon, kirjaston koon ja lokien säilyttämisen suhteen. Nykyiset rajoitukset löytyvät osoitteesta Service Details and Limitations of Fabric User Data Functions.
• Parametrien nimissä on käytettävä camelCasea ja niissä on oltava tyyppimerkinnät. Funktioilla @udf.function() koristeltujen funktioiden on myös määriteltävä palautustyyppi. Täydelliset syntaksisäännöt löytyvät Fabric-käyttäjädatan funktioohjelmointimallin yleiskatsauksesta.
• Sisäänrakennetut tekstimuunnosfunktiot, jotka eivät vaadi mukautettua Python-koodia, katso Käytä tekoälyfunktioita (esikatselu).

Esimerkkejä

Seuraavat skenaariot osoittavat yleisiä tapoja laajentaa Fabric tietovarasto käyttäjätietofunktioilla.

V. Laajenna T-SQL:ää IP-osoitteiden jäsentämisellä

Käytä Python-käyttäjätietofunktiota, kun varastokyselysi tarvitsee toiminnallisuutta, jota ei ole saatavilla sisäänrakennettuna T-SQL-funktiona. Esimerkiksi voit käyttää IP-osoitepakettia palauttaaksesi aliverkon IP-osoitteeksi. Voit soveltaa tätä toimintoa erissä, kun kysely käsittelee IP-osoitteita useilta riveiltä. Konfigurointivaiheita varten katso Määritä eräajotila.

Määrittele ja julkaise Python-funktio käyttäjätietofunktioiden kohteessa:

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)

Luo varastoon T-SQL-välityspalvelinfunktio, joka viittaa julkaistuun Python-funktioon:

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

Kutsu välitysfunktio varastokyselystä:

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

Odotettu tulos:192.168.1.0/24

B. Käynnistä ulkoinen julkinen API

Käytä käyttäjätietofunktiota, kun varastokyselyn täytyy kutsua ulkoista API:ta osana datan rikastamisen työnkulkua.

SQL-tietokannassa Fabric:ssa, Azure SQL Database ja Azure SQL Managed Instance sys.sp_invoke_external_rest_endpoint kutsuvat HTTPS REST -päätepisteen. Vuonna Fabric tietovarasto käyttäjätietofunktio voi tarjota vaihtoehtoisen kuvion käärimällä HTTPS-kutsun Python:ään ja altistamalla sen T-SQL:lle välitysfunktion kautta.

Määrittele ja julkaise Python-funktio käyttäjätietofunktioiden kohteessa. Tässä esimerkissä käytetään parametrien nimiä, jotka ovat samankaltaisia kuin 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

Luo varastoon T-SQL-välityspalvelinfunktio:

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

Kutsu välitysfunktio varastokyselystä:

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

C. Käytä konfiguroitavaa säilytysaikaa

Käytä käyttäjätietotoimintoa, kun varastokyselyt tarvitsevat keskitetysti hallittavia konfiguraatioarvoja Fabric-muuttujakirjastosta. Esimerkiksi tallenna säilytysaika muuttujakirjastoon, hakee se välitysfunktion kautta ja käyttää sitä T-SQL-funktion lukuargumenttinaDATEADD.

Ennen kuin julkaiset funktion, lisää yhteys käyttäjätietofunktioiden alkiosta muuttujakirjastoon ja merkitse yhteysalias. Tämän esimerkin muuttujakirjasto sisältää RETENTION_DAYS arvon, kuten 90.

Määrittele ja julkaise Python-funktio käyttäjätietofunktioiden kohteessa:

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

Korvaa WarehouseConfig se muuttuvan kirjaston yhteyden aliaksella.

Luo varastoon T-SQL-välityspalvelinfunktio:

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

Pysyvässä T-SQL-yhteydessä hae konfiguroitu arvo kerran ja tallenna se käyttämällä 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;

Arvo pysyy saatavilla koko istunnon eliniän ajan. Hae se ja SESSION_CONTEXT muunna siitä sql_variant ennen int kuin käytät sitä ja GETDATEkanssaDATEADD. Esimerkiksi lasketaan säilytysraja:

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

Käytä samaa istuntoarvoa toisessa lauseessa taulun suodattamiseen:

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

Vianmääritys käyttäjätietojen toiminnoista

Query Insights tarjoaa suoritus- ja suorituskykytiedot, joita tarvitset Fabric-toimintojen vianmääritykseen. Voit tunnistaa kyselyt, jotka kutsuivat funktion, selvittää, käyttikö funktio erä- vai rivisuoritusta, sekä tutkia ulkoisen palvelun viivettä, kokeiluja, epäonnistuneita rivejä ja hyötykuorman kokoa. Käytä seuraavia kahta näkymää siirtyäksesi kyselytason yleiskatsauksesta yksityiskohtaisiin tilastoihin kummallekin funktiolle:

• Käytetään queryinsights.exec_requests_history tunnistamaan kyselyt, jotka kutsuvat Fabric- tai AI-toimintoja. Näkymä sisältää kyselyn tekstin, tilan, lähetysajan ja kokonaisajan.
• Käytä queryinsights.external_api_call_stats saadaksesi yksityiskohtaisia tilastoja jokaisesta kyselyn käynnistämästä funktiosta. Näkymä sisältää funktiotyypin, suoritustilan, kutsujen ja uudelleenyritysten määrän, ulkoisen palvelun odotusajan, hyötykuorman koon ja rivitulokset.

Näkymät tunnistavat distributed_statement_id saman kyselyn suorituksen.

Etsi kyselyitä, jotka käyttivät Fabric-funktioita

Käytä queryinsights.exec_requests_history etsimään viimeaikaisia lauseita, jotka kutsuivat Fabric- tai AI-funktion:

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;

Kopioi distributed_statement_id lausunto, jota haluat tutkia. Seuraava kysely suodattaa yksityiskohtaiset tilastot Fabric-funktioihin.

Katso tilastot jokaisesta funktiosta lauseessa

Korvaa <distributed_statement_id> tunnisteella, jonka edellisen kyselyn palauttama. Seuraava kysely palauttaa yhden rivin jokaiselle erilliselle Fabric-funktiolle, jonka lause kutsuu:

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;

Tulokset muistuttavat seuraavaa esimerkkiä:

Vianmääritysvihjeitä

• Korkea row_call_count tai execution_mode arvo voi row tarkoittaa, että funktio ei käytä eräajoa. Jos odotat eräajoa, varmista, että eräajotilan esikatselu on käytössä ja että funktio käyttää argumenttia max_batch_size .
• Käytä external_service_wait_time_ms ja average_wait_time_ms_per_call tunnistaaksesi hitaat ulkoiset reaktiot. Jos nämä arvot ovat korkeita ja data_sent_bytesdata_received_bytes matalia, ulkoisen palvelun vasteaika on todennäköisesti ensisijainen viive.
• Suuret data_sent_bytes arvot data_received_bytes voivat myös pidentää suoritusaikaa. Vähennä syöte- tai lähtökuormaa, kun funktio siirtää enemmän dataa kuin skenaario vaatii.

Liittyvä sisältö

• Luo käyttäjätietofunktioiden kohde Fabric-ohjelmassa
• Fabric-käyttäjädatan funktioohjelmointimallin yleiskatsaus
• Fabric-käyttäjätietofunktioiden palvelutiedot ja rajoitukset