Verwenden Sie Benutzerdatenfunktionen in Fabric Data Warehouse (Vorschau)

Gilt für:✅ Warehouse in Microsoft Fabric

In Fabric Data Warehouse können T-SQL-Entwickler Fabric Benutzerdatenfunktionen aus T-SQL-Abfragen aufrufen. Eine T-SQL-Proxyfunktion in einem Warehouse ruft die referenzierte Python-Funktion in einem veröffentlichten User Data Functions Item auf.

Nutzen Sie diese Integration, um T-SQL mit wiederverwendbarer Python-Logik für Szenarien wie:

• Verwendung spezieller PyPI-Pakete für räumliche, numerische oder Data-Science-Workloads.
• Implementierung von benutzerdefinierter Geschäftslogik in Python.
• Externe APIs aufrufen.
• Interaktion mit anderen Fabric-Elementen und Azure-Diensten wie Lagerhäusern, Seehäusern, SQL-Datenbanken oder einer Cosmos-Datenbank.

Dieser Artikel zeigt, wie man eine veröffentlichte Benutzerdatenfunktion aus Fabric Data Warehouse referenzieren und sie in T-SQL-Abfragen verwenden kann.

Voraussetzungen

Um Benutzerdatenfunktionen aus Fabric Data Warehouse zu verwenden, benötigen Sie:

• Ein Stofflager.

• Ein veröffentlichtes Element für Benutzerdatenfunktionen, das die Python-Funktion enthält, die du aufrufen möchtest.

• Lesezugriff auf das Funktionselement für Benutzerdaten und die Berechtigung, seine veröffentlichten Funktionen aufzurufen.

• Berechtigung, eine Funktion im Ziel-Warehouse zu erstellen.

• Eine Python-Funktion, die dem Programmiermodell der User Data Functions folgt. Informationen zu den Syntaxanforderungen, den unterstützten Eingabe- und Ausgabetypen sowie zur Verwendung von Dekoratoren finden Sie unter Übersicht über das Programmiermodell für Fabric-Benutzerdatenfunktionen.

• Wenn du einen neuen User Data Functions Item erstellen musst, brauchst du außerdem eine Fabric-Kapazität in einer unterstützten Region und einen Fabric-Arbeitsbereich, der dieser Kapazität zugewiesen ist. Weitere Informationen finden Sie unter Erstellen eines Elements für Benutzerdatenfunktionen in Fabric und Servicedetails und Einschränkungen von Fabric-Benutzerdatenfunktionen.

Erstellen und veröffentlichen Sie eine Benutzerdatenfunktion

Bevor Sie eine Benutzerdatenfunktion aus einem Warehouse aufrufen können, erstellen und veröffentlichen Sie die Funktion in einem User Data Functions Item. Eine vollständige Anleitung sowie Python-Beispielfunktionen finden Sie unter das Element „Benutzerdatenfunktionen erstellen“ in Fabric.

Eine Python-Benutzerdatenfunktion, die Sie erstellen könnten, ist im folgenden Beispiel gezeigt:

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Du verwendest den Namen der Benutzerdatenfunktion, um eine T-SQL-Proxyfunktion an die Python-Funktion zu binden.

Erstellen Sie eine T-SQL-Proxy-Funktion

Erstellen Sie eine T-SQL-Funktion in Ihrem Warehouse und binden Sie sie mit der AS EXTERNAL FUNCTION Klausel an die veröffentlichte Python-Funktion.

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

Ersetzen Sie FunctionSetName durch den Namen Ihres Benutzerdatenfunktionen-Elements, und hello_fabric durch den Namen der veröffentlichten Python-Funktion.

Standardmäßig leitet die CREATE FUNCTION-Anweisung die Parameterliste und den Rückgabetyp aus der Definition der entfernten Fabric User Data Function (UDF) ab. Du kannst den abgeleiteten Rückgabetyp überschreiben, indem du ihn explizit in der Funktionsdefinition spezifizierst. Die Angabe des Rückgabetyps ist nützlich, wenn man einen präziseren Rückgabetyp bereitstellen möchte als den Typ, der aus den Metadaten der entfernten Funktion abgeleitet wird.

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

Zum Beispiel wird ein Python-Rückgabewert str typischerweise als VARCHAR(MAX)abgeleitet, aber wenn die Funktion immer einen Wert mit bekannter maximaler Länge zurückgibt, kann man den Rückgabetyp explizit als VARCHAR(100) oder eine andere geeignete Länge definieren, um genauere Metadaten und Typinformationen bereitzustellen.

Verwenden Sie Proxy-Funktionen in T-SQL-Abfragen

Nachdem du die Proxy-Funktion erstellt hast, rufe sie aus T-SQL wie jede andere benutzerdefinierte Funktion auf.

Verwenden Sie die Proxy-Funktion in Abfrageausdrücken wie:

• SELECT Listen.
• WHERE Klauseln.
• GROUP BY Klauseln.
• Ausdrücke in UPDATE und INSERT Aussagen.

Das folgende Muster zeigt, wie man eine Proxy-Funktion aus einer Abfrage aufruft:

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

Für fortgeschrittene Python-Muster, unterstützte Typen, Verbindungen und Kontextobjekte siehe Fabric User Data Function Programmierungsmodell Übersicht.

Konfiguration der Batch-Modus-Ausführung

Fabric Data Warehouse kann externe Benutzerdatenfunktionen im Batch-Modus ausführen.

Die Batch-Ausführung sendet mehrere Funktionsaufrufe in einer einzigen Anfrage an den entfernten Fabric User Data Function (UDF)-Dienst, wodurch der Netzwerkaufwand und die Anfragelatenz reduziert werden. Ein Batch kann bis zu 900 Funktionsaufrufe enthalten.

Der Batch-Modus wird typischerweise verwendet, wenn dieselbe Funktion auf Werte aus einer oder mehreren Tabellenspalten angewendet wird, sodass der Abfrageprozessor viele Zeilen in einem einzigen entfernten Aufruf auswerten kann, anstatt für jede Zeile eine separate Anfrage zu stellen. Diese Methode kann die Abfrageleistung erheblich verbessern, insbesondere bei großen Datensätzen und hochverzögerten externen Funktionsaufrufen.

Wenn beispielsweise eine Abfrage auf jeden Wert in einer Spalte eine Benutzerdatenfunktion anwendet, kann Fabric Data Warehouse die Eingabewerte in Chargen gruppieren und gemeinsam zur Fernverarbeitung einreichen. Der entfernte Service liefert eine entsprechende Menge von Ergebnissen, die dann in die Pipeline zur Abfrageausführung integriert werden.

Um den Batch-Modus für eine Benutzerdatenfunktion zu aktivieren:

1. Öffnen Sie den Eintrag Benutzerdatenfunktionen.
2. Gehe zu den Einstellungen für Bibliotheksverwaltung>.
3. Aktivieren Sie die Vorschaufunktionen.

Legen Sie max_batch_size=900 im @udf.function()-Decorator fest, damit das Warehouse bei jedem Aufruf bis zu 900 Eingabezeilen senden kann:

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Nachdem Sie eine T-SQL-Proxy-Funktion erstellt haben, die auf eine batch-fähige Benutzerdatenfunktion (UDF) referenziert, erkennt Fabric Data Warehouse automatisch die Batch-Konfiguration, einschließlich der maximalen Batchgröße, die von der entfernten Funktion definiert ist. Wenn das Abfragemuster Batching unterstützt, gruppiert der Abfrageprozessor mehrere Funktionsaufrufe in Batches und sendet sie zur Ausführung an den entfernten Dienst, anstatt für jede Zeile einzelne Anfragen zu stellen.

Listen Sie Benutzerdatenfunktionen in einem Warehouse auf

Benutzerdatenfunktionen, die du mit AS EXTERNAL FUNCTION erstellst, werden in sys.objects mit dem Objekttyp XF angezeigt.

Um Benutzerdatenfunktionen in einem Data Warehouse aufzulisten, filtern Sie sys.objects nach type = 'XF'.

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

Um sowohl reguläre skalare Funktionen (FN) als auch Benutzerdatenfunktionen (XF) zusammen mit ihren Parameter- und Rückgabetyp-Signaturen aufzulisten, verwenden Sie sys.parameters und 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;

Hinweise

• Die T-SQL-Proxyfunktion hängt vom veröffentlichten Benutzerdaten-Funktionselement und Funktionsnamen ab. Wenn du die Python-Funktion umbenennst oder löschst, aktualisiere die Warehouse-Proxy-Funktion entsprechend.
• Das Programmiermodell der Benutzerdatenfunktionen definiert die unterstützten Ein- und Ausgabetypen. Stellen Sie sicher, dass die Python-Parameter- und Rückgabeannotationen die Werte unterstützen, die von Ihren T-SQL-Abfragen übergeben werden.
• Benutzer-Datenfunktionen haben Servicelimits für die Größe der Anfragenutzlast, Ausführungszeit, Antwortgröße, Bibliotheksgröße und Logaufbewahrung. Für aktuelle Grenzen siehe Servicedetails und Einschränkungen der Fabric-Benutzerdatenfunktionen.
• Parameternamen müssen camelCase verwenden und Typannotationen enthalten. Funktionen, die mit @udf.function() verziert sind, müssen ebenfalls einen Rückgabetyp angeben. Für die vollständigen Syntaxregeln siehe Fabric User Data Function Programmierungsmodell Übersicht.
• Für integrierte Texttransformationsfunktionen, die keinen benutzerdefinierten Python-Code erfordern, siehe Verwenden von KI-Funktionen (Vorschau).
• Benutzer-Datenfunktionen haben Servicelimits für die Größe der Anfragenutzlast, Ausführungszeit, Antwortgröße, Bibliotheksgröße und Logaufbewahrung. Für aktuelle Grenzen siehe Servicedetails und Einschränkungen der Fabric-Benutzerdatenfunktionen.
• Parameternamen müssen camelCase verwenden und Typannotationen enthalten. Funktionen, die mit @udf.function() verziert sind, müssen ebenfalls einen Rückgabetyp angeben. Für die vollständigen Syntaxregeln siehe Fabric User Data Function Programmierungsmodell Übersicht.
• Für integrierte Texttransformationsfunktionen, die keinen benutzerdefinierten Python-Code erfordern, siehe Verwenden von KI-Funktionen (Vorschau).

Beispiele

Die folgenden Szenarien zeigen gängige Möglichkeiten, Fabric Data Warehouse mit Benutzerdatenfunktionen zu erweitern.

A. Erweitere T-SQL mit IP-Adressparsing

Verwenden Sie eine Python-Benutzerdatenfunktion, wenn Ihre Warehouse-Abfrage Funktionen benötigt, die als integrierte T-SQL-Funktion nicht verfügbar sind. Zum Beispiel kann man ein IP-Adresspaket verwenden, um das Subnetz für eine IP-Adresse zurückzugeben. Sie können diese Funktion in Batches anwenden, wenn eine Abfrage IP-Adressen aus vielen Zeilen verarbeitet. Für Konfigurationsschritte siehe Batch-Modus konfigurieren.

Definieren und veröffentlichen Sie die Python-Funktion in einem User Data Functions Element:

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)

Erstelle eine T-SQL-Proxy-Funktion im Warehouse, die auf die veröffentlichte Python-Funktion verweisen:

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

Rufen Sie die Proxy-Funktion aus einer Warehouse-Abfrage auf:

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

Erwartetes Ergebnis:192.168.1.0/24

B. Aufrufe eine externe öffentliche API

Verwenden Sie eine Benutzerdatenfunktion, wenn eine Warehouse-Abfrage im Rahmen eines Datenanreicherungs-Workflows eine externe API aufrufen muss.

In SQL Database in Fabric, Azure SQL-Datenbank und Azure SQL Managed Instance wird sys.sp_invoke_external_rest_endpoint ein HTTPS-REST-Endpunkt aufgerufen. In Fabric Data Warehouse kann eine Benutzerdatenfunktion ein alternatives Muster bereitstellen, indem sie einen HTTPS-Aufruf in Python umwickelt und ihn über eine Proxy-Funktion T-SQL zugänglich macht.

Definiere und veröffentliche die Python-Funktion in einem User Data Functions Item. Dieses Beispiel verwendet Parameternamen ähnlich :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

Erstelle eine T-SQL-Proxy-Funktion im Lager:

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

Rufen Sie die Proxy-Funktion aus einer Warehouse-Abfrage auf:

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

C. Verwenden Sie eine konfigurierbare Aufbewahrungszeit

Verwenden Sie eine Benutzerdatenfunktion, wenn Warehouse-Abfragen zentral verwaltete Konfigurationswerte aus einer Fabric-Variablenbibliothek benötigen. Zum Beispiel speichern Sie eine Aufbewahrungsperiode in der Variablenbibliothek, rufen sie über eine Proxyfunktion ab und verwenden Sie sie als Zahlenargument der DATEADD T-SQL-Funktion.

Bevor du die Funktion veröffentlichst, füge eine Verbindung vom User Data Functions Item in die Variablenbibliothek hinzu und notiere das Verbindungsalias. Die Variablenbibliothek in diesem Beispiel enthält einen RETENTION_DAYS Wert wie 90.

Definieren und veröffentlichen Sie die Python-Funktion in einem User Data Functions Element:

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

Ersetzen Sie WarehouseConfig durch das Alias Ihrer variablen Bibliotheksverbindung.

Erstelle eine T-SQL-Proxy-Funktion im Lager:

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

Bei einer persistenten T-SQL-Verbindung rufen Sie den konfigurierten Wert einmal ab und speichern Sie ihn mit 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;

Der Wert bleibt für die gesamte Lebensdauer der Sitzung verfügbar. Rufen Sie es mit SESSION_CONTEXT ab und konvertieren Sie es von sql_variant in int, bevor Sie es mit DATEADD und GETDATE verwenden. Berechnen Sie zum Beispiel eine Bindungsgrenze:

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

Verwenden Sie denselben Sitzungswert in einer anderen Anweisung wieder, um eine Tabelle zu filtern:

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

Fehlerbehebung von Nutzerdatenfunktionen

Query Insights liefert die Ausführungs- und Leistungsinformationen, die Sie benötigen, um Fabric-Funktionen zu beheben. Man kann Abfragen identifizieren, die eine Funktion aufgerufen haben, feststellen, ob die Funktion Batch- oder Zeilenausführung verwendet hat, und externe Servicelatenz, Wiederholungen, fehlgeschlagene Zeilen und die Nutzlastgröße untersuchen. Verwenden Sie die folgenden beiden Ansichten, um von einer Abfrageübersicht zu detaillierten Statistiken für jede Funktion überzugehen:

• Verwenden Sie queryinsights.exec_requests_history, um die Abfragen zu identifizieren, die Fabric- oder KI-Funktionen verwendet haben. Die Ansicht enthält den Anfragetext, den Status, die Abgabezeit und die gesamte vergangene Zeit.
• Nutze es queryinsights.external_api_call_stats , um detaillierte Statistiken für jede von einer Abfrage aufgerufene Funktion zu erhalten. Die Ansicht enthält den Funktionstyp, den Ausführungsmodus, die Anzahl der Aufrufe und Wiederholungen, die Wartezeit des externen Dienstes, die Größe der Nutzlast und die Zeilenergebnisse.

Die Views verwenden distributed_statement_id, um dieselbe Abfrageausführung zu identifizieren.

Finde Abfragen, die Fabric-Funktionen verwendet haben

Verwenden Sie queryinsights.exec_requests_history, um aktuelle Anweisungen zu finden, die eine Fabric- oder KI-Funktion aufgerufen haben:

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;

Kopieren Sie das distributed_statement_id für die Aussage, die Sie untersuchen möchten. Die nächste Abfrage filtert die detaillierten Statistiken auf Fabric-Funktionen.

Sehen Sie Statistiken für jede Funktion in einer Aussage an

Ersetzen Sie <distributed_statement_id> durch eine Kennung, die von der vorherigen Abfrage zurückgegeben wurde. Die folgende Abfrage liefert für jede unterschiedliche Fabric-Funktion, die von der Anweisung aufgerufen wird, eine Zeile:

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;

Die Ergebnisse ähneln folgendem Beispiel:

Tipps zur Problembehandlung

• Ein hoher row_call_count Wert oder ein execution_mode Wert von row kann anzeigen, dass die Funktion keine Batch-Ausführung verwendet. Wenn Sie Batching erwarten, bestätigen Sie, dass die Batch-Mode-Vorschau aktiviert ist und die Funktion das Argument max_batch_size verwendet.
• Verwenden Sie external_service_wait_time_ms und average_wait_time_ms_per_call, um langsame externe Antworten zu identifizieren. Wenn diese Werte hoch sind, während data_sent_bytes und data_received_bytes niedrig sind, ist die Antwortzeit des externen Dienstes wahrscheinlich die Hauptursache für die Verzögerung.
• Große data_sent_bytes oder data_received_bytes Werte können ebenfalls die Ausführungszeit erhöhen. Reduziere die Eingabe- oder Ausgabenutzlast, wenn die Funktion mehr Daten überträgt, als das Szenario erfordert.

Verwandte Inhalte

• Erstellen Sie ein Benutzerdatenfunktionselement in Fabric
• Überblick über das Fabric User Data Function Programmierungsmodell
• Dienstdetails und Einschränkungen von Fabric-Benutzerdatenfunktionen