Gebruik gebruikersgegevensfuncties in Fabric Data Warehouse (preview)

Van toepassing op:✅ Warehouse in Microsoft Fabric

In Fabric Data Warehouse kunnen T-SQL-ontwikkelaars Fabric gebruikersgegevensfuncties aanroepen vanuit T-SQL-queries. Een T-SQL-proxyfunctie in een warehouse roept de verwezen Python-functie aan in een gepubliceerd user data functions item.

Gebruik deze integratie om T-SQL uit te breiden met herbruikbare Python-logica voor scenario's zoals:

• Gespecialiseerde PyPI-pakketten gebruiken voor ruimtelijke, numerieke of data science-workloads.
• Aangepaste bedrijfslogica implementeren in Python.
• Externe API's aanroepen.
• Interactie met andere Fabric-items en Azure-diensten, zoals magazijnen, lakehouses, SQL-databases of een Cosmos-database.

Dit artikel laat zien hoe je een gepubliceerde gebruikersgegevensfunctie uit Fabric Data Warehouse kunt refereren en deze kunt gebruiken in T-SQL-queries.

Prerequisites

Om gebruikersdatafuncties van Fabric Data Warehouse te gebruiken, heb je het volgende nodig:

• Een Fabric-magazijn.

• Een gepubliceerd user data functions item dat de Python-functie bevat die je wilt aanroepen.

• Leestoegang tot het item voor gebruikersgegevensfuncties en machtiging om de gepubliceerde functies aan te roepen.

• Toestemming om een functie aan te maken in het doeldatawarehouse.

• Een Python-functie die het programmeermodel van gebruikersdatafuncties volgt. Raadpleeg Overzicht van het programmeermodel voor Fabric-gebruikersgegevensfuncties voor syntaxisvereisten, ondersteunde invoer- en uitvoertypen en het gebruik van decorators.

• Als je een nieuw user data functions-item moet aanmaken, heb je ook een Fabric-capaciteit nodig in een ondersteunde regio en een Fabric-werkruimte toegewezen aan die capaciteit. Zie voor meer informatie Een item voor gebruikersgegevensfuncties maken in Fabric en Servicedetails en beperkingen van gebruikersgegevensfuncties in Fabric.

Maak een gebruikersgegevensfunctie aan en publiceer

Voordat je een user data-functie vanuit een warehouse kunt aanroepen, maak en publiceer je de functie in een user data functions item. Voor volledige stappen en voorbeeldfuncties van Python, zie Create a user data functions item in Fabric.

Een Python-gebruikersdatafunctie die je kunt maken wordt getoond in het volgende voorbeeld:

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Je gebruikt de user-datafunctie item name om een T-SQL-proxyfunctie aan de Python-functie te binden.

Maak een T-SQL proxyfunctie aan

Maak een T-SQL-functie aan in je warehouse en bind deze aan de gepubliceerde Python-functie door gebruik te maken van de AS EXTERNAL FUNCTION clausule.

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

Vervang FunctionSetName door de naam van je user data functions item en vervang hello_fabric door de naam van de gepubliceerde Python-functie.

Standaard leidt de CREATE FUNCTION-instructie de parameterlijst en het retourtype af uit de definitie van de externe Fabric User Data Function (UDF). Je kunt het afgeleide retourtype overschrijven door het expliciet te specificeren in de functiedefinitie. Het geven van het retourtype is handig wanneer je een preciezer retourtype wilt blootstellen dan het type dat uit de remote function metadata wordt afgeleid.

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

Bijvoorbeeld, een Python-retourwaarde str wordt doorgaans afgeleid als VARCHAR(MAX), maar als de functie altijd een waarde met een bekende maximale lengte teruggeeft, kun je het retourtype expliciet definiëren als VARCHAR(100) of een andere geschikte lengte om nauwkeurigere metadata en type-informatie te verkrijgen.

Gebruik proxyfuncties in T-SQL-queries

Nadat je de proxyfunctie hebt gemaakt, roep je deze aan vanuit T-SQL zoals elke andere door de gebruiker gedefinieerde functie.

Gebruik de proxyfunctie in query-expressies zoals:

• SELECT lijsten.
• WHERE clausules.
• GROUP BY clausules.
• Uitdrukkingen en UPDATEINSERT uitspraken.

Het volgende patroon toont hoe je een proxyfunctie aanroept vanuit een query:

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

Voor geavanceerde Python-patronen, ondersteunde typen, verbindingen en contextobjecten, zie Fabric user data function programming model overzicht.

Uitvoering in batchmodus configureren

Fabric Data Warehouse kan externe gebruikersgegevensfuncties uitvoeren in batchmodus.

Batch-modus uitvoering stuurt meerdere functie-aanroepen in één verzoek naar de externe Fabric User Data Function (UDF)-service, waardoor netwerkoverhead en verzoekvertraging worden verminderd. Een batch kan tot 900 functieaanroepen bevatten.

Batchmodus wordt doorgaans gebruikt wanneer dezelfde functie wordt toegepast op waarden uit een of meer tabelkolommen, waardoor de queryprocessor meerdere rijen in één externe oproep kan evalueren in plaats van voor elke rij een apart verzoek te doen. Deze methode kan de queryprestaties aanzienlijk verbeteren, vooral voor grote datasets en externe functieaanroepen met hoge latentie.

Wanneer een query bijvoorbeeld een gebruikersgegevensfunctie toepast op elke waarde in een kolom, kan Fabric Data Warehouse de invoerwaarden groeperen in batches en ze samen indienen voor externe verwerking. De externe service levert een overeenkomstige batch resultaten terug, die vervolgens worden geïntegreerd in de query-uitvoeringspijplijn.

Om batchmodus voor een gebruikersgegevensfunctie in te schakelen:

1. Open het onderdeel Gebruikersgegevensfuncties.
2. Ga naar Instellingen voor bibliotheekbeheer>.
3. Zet de Preview-functies aan.

Stel max_batch_size=900 in de @udf.function()-decorator in om de warehouse toe te staan bij elke aanroep maximaal 900 inputrijen te verzenden:

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Nadat je een T-SQL proxyfunctie hebt gemaakt die verwijst naar een batch-enabled user data function (UDF), detecteert Fabric Data Warehouse automatisch de batchconfiguratie, inclusief de maximale batchgrootte die door de externe functie is gedefinieerd. Wanneer het querypatroon batching ondersteunt, groepeert de queryprocessor meerdere functieaanroepen in batches en stuurt deze naar de externe service voor uitvoering in plaats van individuele verzoeken per rij te doen.

Functies voor gebruikersgegevens in een datawarehouse weergeven

Functies voor gebruikersgegevens die je maakt met AS EXTERNAL FUNCTION, verschijnen in sys.objects met het objecttype XF.

Om gebruikersgegevensfuncties in een warehouse te vermelden, filter sys.objects op type = 'XF'.

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

Om zowel reguliere scalaire functies (FN) als gebruikersgegevensfuncties (XF) te vermelden, samen met hun parameter- en retourtype-signaturen, gebruik sys.parameters en 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;

Remarks

• De T-SQL-proxyfunctie is afhankelijk van het item en de functienaam van de gepubliceerde gebruikersgegevensfuncties. Als je de Python-functie hernoemt of verwijdert, werk dan de warehouse-proxyfunctie dienovereenkomstig bij.
• Het programmeermodel voor gebruikersgegevensfuncties definieert de ondersteunde invoer- en uitvoertypen. Controleer of de Python-parameter en retourannotaties de waarden ondersteunen die je T-SQL-queries doorgeven.
• Gebruikersgegevensfuncties hebben servicelimieten voor de grootte van de aanvraaglading, uitvoeringstijd, responsgrootte, bibliotheekgrootte en logretentie. Voor huidige limieten, zie Servicedetails en beperkingen van Fabric-gebruikersgegevensfuncties.
• Parameternamen moeten camelCase gebruiken en type-annotaties bevatten. Functies die met @udf.function() worden versierd, moeten ook een retourtype specificeren. Voor de volledige syntaxisregels, zie Fabric user data function programming model overview.
• Voor ingebouwde teksttransformatiefuncties die geen aangepaste Python-code vereisen, zie Gebruik AI-functies (preview).
• Gebruikersgegevensfuncties hebben servicelimieten voor de grootte van de aanvraaglading, uitvoeringstijd, responsgrootte, bibliotheekgrootte en logretentie. Voor huidige limieten, zie Servicedetails en beperkingen van Fabric-gebruikersgegevensfuncties.
• Parameternamen moeten camelCase gebruiken en type-annotaties bevatten. Functies die met @udf.function() worden versierd, moeten ook een retourtype specificeren. Voor de volledige syntaxisregels, zie Fabric user data function programming model overview.
• Voor ingebouwde teksttransformatiefuncties die geen aangepaste Python-code vereisen, zie Gebruik AI-functies (preview).

Voorbeelden

De volgende scenario's tonen veelvoorkomende manieren om Fabric Data Warehouse uit te breiden met gebruikersgegevensfuncties.

Eén. Breid T-SQL uit met het parseren van IP-adressen

Gebruik een Python-gebruikersdatafunctie wanneer je warehouse-query functionaliteit nodig heeft die niet beschikbaar is als ingebouwde T-SQL-functie. Je kunt bijvoorbeeld een IP-adrespakket gebruiken om het subnet terug te geven voor een IP-adres. Je kunt deze functie in batches toepassen wanneer een query IP-adressen uit meerdere rijen verwerkt. Voor configuratiestappen, zie Batchmodus configureren.

Definieer en publiceer de Python-functie in een user data functions item:

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)

Maak een T-SQL proxyfunctie aan in het warehouse die verwijst naar de gepubliceerde Python-functie:

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

Roep de proxyfunctie aan vanuit een warehouse-query:

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

Verwacht resultaat:192.168.1.0/24

B. Roep een externe publieke API aan

Gebruik een gebruikersdatafunctie wanneer een warehouse-query een externe API moet aanroepen als onderdeel van een dataverrijkingsworkflow.

In SQL Database in Fabric, Azure SQL Database en Azure SQL Managed Instance, sys.sp_invoke_external_rest_endpoint roept een HTTPS REST-eindpunt aan. In Fabric Data Warehouse kan een gebruikersdatafunctie een alternatief patroon bieden door een HTTPS-aanroep in Python te wrappen en deze via een proxyfunctie aan T-SQL bloot te stellen.

Definieer en publiceer de Python-functie in een user data functions item. Dit voorbeeld gebruikt parameternamen vergelijkbaar met 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

Maak een T-SQL proxyfunctie aan in het magazijn:

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

Roep de proxyfunctie aan vanuit een warehouse-query:

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

C. Gebruik een configureerbare retentieperiode

Gebruik een gebruikersdatafunctie wanneer warehouse-queries centraal beheerde configuratiewaarden uit een Fabric-variabelenbibliotheek nodig hebben. Bijvoorbeeld, sla een retentieperiode op in de variabelenbibliotheek, haal deze op via een proxyfunctie en gebruik deze als het getalargument van de DATEADD T-SQL-functie.

Voeg voordat je de functie publiceert, een verbinding toe vanuit het user data functions-item aan de variabelenbibliotheek en noteer de verbindingsalias. De variabelenbibliotheek in dit voorbeeld bevat een RETENTION_DAYS waarde zoals 90.

Definieer en publiceer de Python-functie in een user data functions item:

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

Vervang WarehouseConfig door de alias van je variabele bibliotheekverbinding.

Maak een T-SQL proxyfunctie aan in het magazijn:

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

Op een persistente T-SQL-verbinding haal je de geconfigureerde waarde één keer op en sla je deze op door te gebruiken 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;

De waarde blijft beschikbaar gedurende de levensduur van de sessie. Haal het op met SESSION_CONTEXT en zet het om van sql_variant naar int voordat je het gebruikt met DATEADD en GETDATE. Bereken bijvoorbeeld een retentiegrens:

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

Hergebruik dezelfde sessiewaarde in een andere instructie om een tabel te filteren:

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

Probleemoplossing van gebruikersgegevensfuncties

Query Insights biedt de uitvoerings- en prestatie-informatie die je nodig hebt om Fabric-functies op te lossen. Je kunt queries identificeren die een functie hebben aangeroepen, bepalen of de functie batch- of rijuitvoering gebruikte, en externe servicevertraging, herpogingen, mislukte rijen en payloadgrootte onderzoeken. Gebruik de volgende twee weergaven om van een overzicht op queryniveau naar gedetailleerde statistieken voor elke functie te gaan:

• Gebruik queryinsights.exec_requests_history om queries te identificeren die Fabric- of AI-functies oproepen. De weergave bevat de querytekst, status, verzendtijd en totale verstreken tijd.
• Gebruik queryinsights.external_api_call_stats om gedetailleerde statistieken te krijgen voor elke functie die door een query wordt aangeroepen. De weergave bevat het functietype, uitvoeringsmodus, aantalen van oproepen en herkansingen, wachttijd van externe diensten, payloadgrootte en rijresultaten.

De weergaven gebruiken distributed_statement_id om de uitvoering van dezelfde query te identificeren.

Zoek queries die Fabric-functies gebruikten

Gebruik queryinsights.exec_requests_history om recente statements te vinden die een Fabric- of AI-functie hebben opgeroepen:

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;

Kopieer het distributed_statement_id voor de verklaring die je wilt onderzoeken. De volgende query filtert de gedetailleerde statistieken naar Fabric-functies.

Bekijk statistieken voor elke functie in een statement

Vervang <distributed_statement_id> door een identifier die door de vorige query is teruggegeven. De volgende query geeft één rij terug voor elke verschillende Fabric-functie die door de instructie wordt aangeroepen:

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;

De resultaten lijken op het volgende voorbeeld:

Tips voor probleemoplossing

• Een hoge row_call_count of een execution_mode waarde van row kan aangeven dat de functie geen batchuitvoering gebruikt. Als je batching verwacht, bevestig dan dat de batch-modus preview is ingeschakeld en dat de functie het max_batch_size argument gebruikt.
• Gebruik external_service_wait_time_ms en average_wait_time_ms_per_call om langzame externe reacties te identificeren. Als deze waarden hoog zijn terwijl data_sent_bytes en data_received_bytes laag zijn, is de responstijd van de externe service waarschijnlijk de primaire vertraging.
• Grote data_sent_bytes of data_received_bytes waarden kunnen ook de uitvoeringstijd verlengen. Verminder de input- of outputpayload wanneer de functie meer data overdraagt dan het scenario vereist.

Verwante onderwerpen

• Maak een user data functions-item aan in Fabric
• Overzicht van het Fabric-gebruikersdata-functie programmeermodel
• Servicedetails en beperkingen van fabric-functies voor gebruikersgegevens