Używaj funkcji danych użytkownika w Fabric Data Warehouse (podgląd)

Dotyczy:✅ Magazyn w systemie Microsoft Fabric

Important

Ta funkcja jest dostępna w wersji zapoznawczej.

W Fabric Data Warehouse deweloperzy T-SQL mogą wywoływać Fabric funkcje danych użytkownika z zapytań T-SQL. Funkcja pośrednicząca T-SQL w magazynie danych wywołuje funkcję języka Python, do której się odwołuje, w opublikowanym elemencie funkcji danych użytkownika.

Wykorzystaj tę integrację, aby rozszerzyć T-SQL o wielokrotnego użytku logikę Python w takich sytuacjach jak:

Używam specjalistycznych pakietów PyPI do zadań przestrzennych, numerycznych lub data science.
Implementacja niestandardowej logiki biznesowej w Pythonie.
Wywoływanie zewnętrznych API.
Interakcja z innymi elementami Fabric i usługami Azure, takimi jak magazyny, domy nad jeziorem, bazy danych SQL czy baza danych Cosmos.

Ten artykuł pokazuje, jak odwołać się do opublikowanej funkcji danych użytkownika z Fabric Data Warehouse i wykorzystać ją w zapytaniach T-SQL.

Wymagania wstępne

Aby korzystać z funkcji danych użytkownika z Fabric Data Warehouse, potrzebujesz:

Magazyn tkanin.
Opublikowany element funkcji danych użytkownika, który zawiera funkcję Python, którą chcesz wywołać.
Odczyt dostępu do elementów funkcji danych użytkownika oraz uprawnień do wywołania opublikowanych funkcji.
Pozwolenie na utworzenie funkcji w docelowym magazynie.
Funkcja w Python, która opiera się na modelu programowania funkcji danych użytkownika. Informacje o wymaganiach dotyczących składni, obsługiwanych typach danych wejściowych i wyjściowych oraz sposobie użycia dekoratorów można znaleźć w artykule Omówienie modelu programowania funkcji danych użytkownika w Fabric.
Jeśli chcesz utworzyć nowy element funkcji danych użytkownika, potrzebujesz także pojemności Fabric w obsługiwanym regionie oraz przestrzeni roboczej Fabric przypisanej do tej pojemności. Szczegóły można znaleźć w artykule Utwórz element funkcji danych użytkownika w Fabric oraz szczegóły usługi oraz ograniczenia funkcji danych użytkownika Fabric.

Stwórz i publikuj funkcję danych użytkownika

Zanim będzie można wywołać funkcję danych zdefiniowaną przez użytkownika w magazynie danych, utwórz i opublikuj tę funkcję w elemencie funkcji danych zdefiniowanych przez użytkownika. Aby uzyskać pełne kroki i przykładowe funkcje Python, zobacz Utwórz element funkcji danych użytkownika w Fabric.

Funkcja danych użytkownika w Python, którą można stworzyć, jest pokazana w następującym przykładzie:

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Używasz funkcji danych użytkownika item name do powiązania funkcji proxy T-SQL z funkcją Python.

Utworzenie funkcji proxy T-SQL

Stwórz funkcję T-SQL w swoim magazynie i powiąż ją z opublikowaną funkcją Python, używając klauzuliAS EXTERNAL FUNCTION.

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

Zastąp FunctionSetName nazwą elementu funkcji danych użytkownika, a hello_fabric nazwą opublikowanej funkcji języka Python.

Wskazówka

Możesz wygenerować kod wywołania na podstawie doświadczenia funkcji danych użytkownika i użyć go jako punktu wyjścia dla funkcji proxy magazynu.

Domyślnie instrukcja CREATE FUNCTION wywodzi listę parametrów i typ return z definicji zdalnej funkcji Fabric User Data Function (UDF). Możesz nadpisać wywnioskowany typ return, określając go wyraźnie w definicji funkcji. Podawanie typu zwrotu jest przydatne, gdy chcesz uzyskać bardziej precyzyjny typ zwrotu niż ten, który wywnioskowano z metadanych funkcji zdalnych.

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

Na przykład wartość zwracana przez funkcję w Pythonie str jest zazwyczaj wnioskowana jako VARCHAR(MAX), ale jeśli funkcja zawsze zwraca wartość o znanej maksymalnej długości, można jawnie zdefiniować typ zwracany jako VARCHAR(100) lub o innej odpowiedniej długości, aby zapewnić dokładniejsze metadane i informacje o typie.

Używaj funkcji proxy w zapytaniach T-SQL

Po utworzeniu funkcji proxy wywołaj ją z T-SQL jak każdą inną funkcję zdefiniowaną przez użytkownika.

Użyj funkcji zastępczej w wyrażeniach zapytań takich jak:

SELECT listy.
WHERE klauzule.
GROUP BY klauzule.
Wyrażenia w instrukcjach UPDATE i INSERT.

Poniższy wzór pokazuje, jak wywołać funkcję zastępczą z zapytania:

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

Aby poznać zaawansowane wzorce Python, obsługiwane typy, połączenia i obiekty kontekstowe, zobacz przegląd modelu programowania funkcji użytkowej Fabric.

Konfiguruj wykonywanie w trybie wsadowym

Fabric Data Warehouse może wykonywać zewnętrzne funkcje danych zdefiniowane przez użytkownika w trybie wsadowym.

Uruchamianie w trybie wsadowym wysyła wiele wywołań funkcji w jednym żądaniu do zdalnej usługi Fabric User Data Function (UDF), co zmniejsza narzut sieciowy i opóźnienia żądań. Partia może zawierać do 900 wywołań funkcji.

Tryb wsadowy jest zazwyczaj stosowany, gdy ta sama funkcja jest stosowana do wartości z jednej lub więcej kolumn tabeli, co pozwala procesorowi zapytań na ocenę wielu wierszy w jednym zdalnym wywołaniu zamiast wysyłania osobnego żądania dla każdego wiersza. Ta metoda może znacząco poprawić wydajność zapytań, szczególnie dla dużych zbiorów danych i wywołań zewnętrznych funkcji o wysokim opóźnieniu.

Na przykład, gdy zapytanie stosuje funkcję danych użytkownika do każdej wartości w kolumnie, Fabric Data Warehouse może grupować wartości wejściowe w partie i przesyłać je razem do zdalnego przetwarzania. Usługa zdalna zwraca odpowiadającą partię wyników, które następnie są integrowane z potokiem wykonania zapytań.

Aby włączyć tryb wsadowy dla funkcji danych o użytkowniku:

Otwórz element funkcji danych użytkownika .
Przejdź doUstawieńzarządzania> biblioteką.
Włącz funkcje Podglądu.

Ustaw max_batch_size=900 w dekoratorze @udf.function(), aby hurtownia mogła wysyłać do 900 wierszy danych wejściowych w każdym wywołaniu:

Note

Argument max_batch_size jest dostępny tylko wtedy, gdy włączony jest podgląd trybu wsadowego.

import fabric.functions as fn

udf = fn.UserDataFunctions()

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

Po utworzeniu funkcji proxy T-SQL odwołującej się do funkcji danych użytkownika (UDF) z wsparciem wsadowym, Fabric Data Warehouse automatycznie wykrywa konfigurację wsadową, w tym maksymalny rozmiar partii zdefiniowany przez funkcję zdalną. Gdy wzorzec zapytań obsługuje grupowanie, procesor zapytań grupuje wiele wywołań funkcji w partie i wysyła je do zdalnej usługi do wykonania zamiast wysyłać pojedyncze żądania dla każdego wiersza.

Lista funkcji danych użytkownika w magazynie

Funkcje danych użytkownika, które tworzysz za pomocą AS EXTERNAL FUNCTION, pojawiają się w sys.objects z typem obiektu XF.

Aby wyświetlić funkcje danych użytkowników w magazynie, filtruj sys.objects według type = 'XF'.

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

Aby wymienić zarówno regularne funkcje skalarne (FN), jak i funkcje danych użytkownika (XF) wraz z ich sygnaturami parametrów i typów return, użyj sys.parameters i 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

Funkcja proxy T-SQL zależy od opublikowanego elementu funkcji danych użytkownika oraz nazwy funkcji. Jeśli zmienisz nazwę funkcji w języku Python lub ją usuniesz, odpowiednio zaktualizuj funkcję proxy magazynu danych.
Model programowania z funkcjami danych użytkownika definiuje obsługiwane typy wejścia i wyjścia. Sprawdź, czy adnotacje parametrów i wartości zwracanej w Pythonie obsługują wartości przekazywane przez zapytania T-SQL.
Funkcje danych użytkownika mają limity usług dotyczące wielkości ładunku żądań, czasu wykonania, wielkości odpowiedzi, rozmiaru biblioteki oraz przechowywania logów. Aktualne ograniczenia można znaleźć w szczegółach usług oraz ograniczeniach funkcji danych użytkownika Fabric.
Nazwy parametrów muszą być zapisane w formacie camelCase i zawierać adnotacje typu. Funkcje opatrzone elementem @udf.function() muszą również określać typ zwracany. Pełne reguły składni opisano w artykule Omówienie modelu programowania funkcji danych użytkownika usługi Fabric.
W przypadku wbudowanych funkcji transformacji tekstu, które nie wymagają niestandardowego kodu Python, zobacz Użyj funkcji AI (podgląd).
Funkcje danych użytkownika mają limity usług dotyczące wielkości ładunku żądań, czasu wykonania, wielkości odpowiedzi, rozmiaru biblioteki oraz przechowywania logów. Aktualne ograniczenia można znaleźć w szczegółach usług oraz ograniczeniach funkcji danych użytkownika Fabric.
Nazwy parametrów muszą być zapisane w stylu camelCase i zawierać adnotacje typu. Funkcje oznaczone symbolem @udf.function() muszą również określać typ zwracany. Pełne reguły składni opisano w artykule Omówienie modelu programowania funkcji danych użytkownika w usłudze Fabric.
W przypadku wbudowanych funkcji transformacji tekstu, które nie wymagają niestandardowego kodu Python, zobacz Użyj funkcji AI (podgląd).

Przykłady

Poniższe scenariusze pokazują powszechne sposoby rozszerzania Fabric Data Warehouse za pomocą funkcji danych użytkownika.

Odp. Rozszerzenie T-SQL za pomocą parsowania adresów IP

Używaj funkcji danych użytkownika w Python, gdy zapytanie magazynowe potrzebuje funkcji, która nie jest dostępna jako wbudowana funkcja T-SQL. Na przykład możesz użyć pakietu adresowego IP, aby zwrócić podsieć jako adres IP. Możesz stosować tę funkcję w partiach, gdy zapytanie przetwarza adresy IP z wielu wierszy. Instrukcje konfiguracji znajdują się w sekcji Konfigurowanie trybu wsadowego.

Note

Jeśli funkcja korzysta z pakietu, który nie jest częścią standardowej biblioteki Python, dodaj pakiet w Zarządzaniu biblioteką przed publikacją elementu funkcji danych użytkownika. Ten przykład wykorzystuje pakiet netaddr .

Zdefiniuj i publikuj funkcję Python w elementie funkcji danych użytkownika:

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)

Utwórz pośredniczącą funkcję T-SQL w magazynie, która odwołuje się do opublikowanej funkcji w języku Python:

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

Wywołaj funkcję proxy z zapytania hurtowni danych:

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

Oczekiwany wynik:192.168.1.0/24

B. Wywołaj zewnętrzne publiczne API

Używaj funkcji danych użytkownika, gdy zapytanie magazynowe musi wywołać zewnętrzne API w ramach workflow wzbogacania danych.

W bazie danych SQL w usłudze Fabric, Azure SQL Database oraz Azure SQL Managed Instance, sys.sp_invoke_external_rest_endpoint wywołuje punkt końcowy REST HTTPS. W Fabric Data Warehouse funkcja danych użytkownika może dostarczyć alternatywny wzorzec, opakowując wywołanie HTTPS w Python i udostępniając je T-SQL za pomocą funkcji proxy.

Caution

Wezwanie zewnętrznego punktu końcowego może przenieść dane poza magazyn. Korzystaj z zatwierdzonych punktów końcowych, unikaj wysyłania wrażliwych danych bez autoryzacji i przestrzegaj wymogów bezpieczeństwa i zgodności organizacji.

Note

Dodaj wymagane biblioteki firm trzecich, takie jak requests, w Zarządzaniu Biblioteką przed publikacją funkcji.

Zdefiniuj i opublikuj funkcję w języku Python w elemencie funkcji danych użytkownika. Ten przykład używa nazw parametrów podobnych do 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

Stwórz funkcję proxy T-SQL w magazynie:

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

Wywołaj funkcję proxy z poziomu zapytania hurtowni danych:

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

C. Użyj konfigurowalnego okresu retencji

Używaj funkcji danych użytkownika, gdy zapytania magazynowe wymagają centralnie zarządzanych wartości konfiguracyjnych z biblioteki zmiennych Fabric. Na przykład zapisz okres retencji w bibliotece zmiennych, pobierz go za pomocą funkcji proxy i użyj go jako argumentu DATEADD funkcji T-SQL.

Przed opublikowaniem funkcji dodaj połączenie z elementem funkcji danych użytkownika do biblioteki zmiennych i zanotuj alias połączenia. Biblioteka zmiennych w tym przykładzie zawiera wartość RETENTION_DAYS, taką jak 90.

Zdefiniuj i publikuj funkcję Python w elementie funkcji danych użytkownika:

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

Zastąp WarehouseConfig aliasem połączenia z biblioteką zmiennych.

Stwórz funkcję proxy T-SQL w magazynie:

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

Przy trwałym połączeniu T-SQL pobierz skonfigurowaną wartość raz i zapisz ją za pomocą 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;

Wartość ta pozostaje dostępna przez cały okres trwania sesji. Pobierz to za pomocą SESSION_CONTEXT i przekonwertuj z sql_variant na int przed użyciem z DATEADD i GETDATE. Na przykład, oblicz próg retencji:

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

Użyj ponownie tej samej wartości sesji w innej instrukcji, aby filtrować tabelę:

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

Important

Użyj tego wzorca z klienta, który utrzymuje trwałe połączenie T-SQL, takiego jak SQL Server Management Studio lub rozszerzenie MSSQL dla Visual Studio Code. Edytor zapytań SQL w portalu Fabric nie obsługuje sp_set_session_context, a każde uruchomienie korzysta z osobnej sesji. Więcej informacji można znaleźć w artykule o ograniczeniach edytora zapytań SQL.

Rozwiązywanie problemów z funkcjami danych użytkownika

Query Insights dostarcza informacji o wykonaniu i wydajności potrzebnych do rozwiązywania problemów z funkcjami Fabric. Możesz zidentyfikować zapytania, które wywołały funkcję, określić, czy funkcja wykonała wykonanie wsadowe czy wierszowe, oraz zbadać opóźnienia usług, powtórzenia, nieudane wiersze i rozmiar ładunku. Użyj następujących dwóch widoków, aby przejść od przeglądu na poziomie zapytania do szczegółowych statystyk dla każdej funkcji:

Użyj queryinsights.exec_requests_history, aby zidentyfikować zapytania, które wywołały funkcje Fabric lub AI. Widok zawiera tekst zapytania, status, czas przesłania oraz całkowity upływ czasu.
Użyj queryinsights.external_api_call_stats, aby uzyskać szczegółowe statystyki dla każdej funkcji wywoływanej przez zapytanie. Widok obejmuje typ funkcji, tryb wykonywania, liczbę wywołań i ponowień, czas oczekiwania na usługi zewnętrzne, rozmiar ładunku danych oraz wyniki dla wierszy.

Widoki używają distributed_statement_id, aby zidentyfikować to samo wykonanie zapytania.

Znajdź zapytania wykorzystujące funkcje Fabric

Użyj queryinsights.exec_requests_history, aby znaleźć ostatnie instrukcje, które wywołały funkcję Fabric lub 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;

Skopiuj oświadczenie distributed_statement_id , które chcesz zbadać. Następne zapytanie filtruje szczegółowe statystyki tak, aby obejmowały wyłącznie funkcje Fabric.

Wyświetl statystyki dla każdej funkcji w instrukcji

Zastąp <distributed_statement_id> identyfikatorem zwróconym przez poprzednie zapytanie. Następujące zapytanie zwraca jeden wiersz dla każdej odrębnej funkcji Fabric wywołanej przez to zdanie:

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;

Wyniki przypominają następujący przykład:

function_name	tryb_wykonania	call_count	batch_call_count	row_call_count	call_retry_count	external_service_wait_time_ms	średni_czas_oczekiwania_ms_na_wywołanie	rows_total	rows_succeeded	nieudane_wiersze	bajty_wysłanych_danych	data_received_bytes
`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

Wskazówki dotyczące rozwiązywania problemów

Wysoka wartość row_call_count lub wartość execution_mode wynosząca row może wskazywać, że funkcja nie korzysta z przetwarzania wsadowego. Jeśli oczekujesz przetwarzania wsadowego, sprawdź, czy podgląd trybu wsadowego jest włączony i czy funkcja używa argumentu max_batch_size.
Używaj external_service_wait_time_ms i average_wait_time_ms_per_call do identyfikowania powolnych reakcji zewnętrznych. Jeśli wartości te są wysokie, podczas gdy data_sent_bytes i data_received_bytes są niskie, czas odpowiedzi usługi zewnętrznej jest prawdopodobnie główną przyczyną opóźnienia.
Duże data_sent_bytes wartości lub data_received_bytes mogą również wydłużyć czas wykonania. Zmniejsz ładunek wejściowy lub wyjściowy, gdy funkcja przesyła więcej danych niż wymaga scenariusz.

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-09-29

Używaj funkcji danych użytkownika w Fabric Data Warehouse (podgląd)

Wymagania wstępne

Stwórz i publikuj funkcję danych użytkownika

Utworzenie funkcji proxy T-SQL

Używaj funkcji proxy w zapytaniach T-SQL

Konfiguruj wykonywanie w trybie wsadowym

Lista funkcji danych użytkownika w magazynie

Remarks

Przykłady

Odp. Rozszerzenie T-SQL za pomocą parsowania adresów IP

B. Wywołaj zewnętrzne publiczne API

C. Użyj konfigurowalnego okresu retencji

Rozwiązywanie problemów z funkcjami danych użytkownika

Znajdź zapytania wykorzystujące funkcje Fabric

Wyświetl statystyki dla każdej funkcji w instrukcji

Wskazówki dotyczące rozwiązywania problemów

Treści powiązane

Opinia

Dodatkowe zasoby