CREATE FUNCTION

Platí pro:SQL analytics endpoint v Microsoft Fabric a Warehouse v Microsoft Fabric

CREATE FUNCTION vytváří inline tabulkové funkce a skalární funkce.

Poznámka:

Externí UDF jsou v Fabric Data Warehouse funkcí náhledu.

Tento článek se týká Microsoft Fabric Data Warehouse a SQL analytického endpointu Fabric položek. Pro jiné platformy viz CREATE FUNCTION (Transact-SQL).

Uživatelem definovaná funkce je Transact-SQL rutina, která přijímá parametry, provádí akci, například komplexní výpočt, a vrací výsledek této akce jako hodnotu. Skalární funkce vrací skalární hodnotu, například číslo nebo řetězec. Uživatelem definované funkce s hodnotami tabulky (TVF) vracejí tabulku.

Použijte CREATE FUNCTION k vytvoření opakovaně použitelné T-SQL rutiny, kterou můžete využít těmito způsoby:

  • V Transact-SQL tvrzeních jako SELECT.
  • Ve Warehouse v Transact-SQL příkazy pro manipulaci s daty (DML) jako UPDATE, INSERT, a DELETE.
  • V aplikacích volá funkci.
  • V definici jiné uživatelsky definované funkce.
  • Nahrazení uloženého postupu.

Specifikujte CREATE OR ALTER FUNCTION vytvoření nové funkce, pokud pod tímto názvem neexistuje, nebo upravte existující funkci v jednom příkazu.

Transact-SQL syntaktické konvence

Syntaxe

Syntaxe skalárních funkcí

CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] parameter_data_type
    [ = default ] }
    [ ,...n ]
  ]
)
RETURNS return_data_type
    [ WITH <function_option> [ ,...n ] ]
    [ AS ]
    BEGIN
        function_body
        RETURN scalar_expression
    END
[ ; ]

<function_option>::=
{
    [ INLINE = AUTO ]
  | [ SCHEMABINDING ]
  | [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]
}

Syntaxe vložené funkce s hodnotou tabulky

CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] parameter_data_type
    [ = default ] }
    [ ,...n ]
  ]
)
RETURNS TABLE
    [ WITH SCHEMABINDING ]
    [ AS ]
    RETURN [ ( ] select_stmt [ ) ]
[ ; ]

Syntaxe externích funkcí

Externí UDF je funkce, která odkazuje na externí Fabric User Data Function.

CREATE FUNCTION [ schema_name. ] function_name
[ RETURNS return_data_type ]
AS EXTERNAL FUNCTION external_function_set_name.external_function_name
[ ; ]

Poznámka:

Externí UDF jsou v Fabric Data Warehouse funkcí náhledu.

Příkaz CREATE FUNCTION automaticky odvozuje typ návratu, parametry a typy parametrů z definice odkazované externí Fabric User Data Function. Pokud se změní podpis externí funkce Fabric User Data, musíte funkci znovu vytvořit tak, aby byla její definice synchronizována s aktualizovaným podpisem.

Argumenty

schema_name

Název schématu, do kterého patří uživatelem definovaná funkce.

function_name

Název uživatelem definované funkce. Názvy funkcí musí dodržovat pravidla identifikátorů a být jedinečné v databázi a jejím schématu.

Pro nativní T-SQL skalární a tabulkové definice funkcí zahrňte závorky za název funkce, i když nejsou žádné parametry. Definice externích funkcí používají samostatnou AS EXTERNAL FUNCTION syntaxi.

@ parameter_name

Parametr v uživatelem definované funkci. Můžete deklarovat jeden nebo více parametrů.

Funkce může mít až 2 100 parametrů. Když uživatel nebo aplikace volá funkci, musíte zadat hodnotu pro každý deklarovaný parametr, pokud nedefinujete výchozí hodnotu parametru.

Zadejte název parametru pomocí znaku at (@) jako prvního znaku. Název parametru musí dodržovat pravidla pro identifikátory. Parametry jsou lokální pro funkci. Stejné názvy parametrů můžete použít i v jiných funkcích. Parametry mohou nahradit pouze konstanty. Nelze je použít místo názvů tabulek, názvů sloupců nebo názvů jiných databázových objektů.

ANSI_WARNINGS není respektováno, když předáváte parametry v uložené procedurě, uživatelsky definované funkci nebo když deklarujete a nastavujete proměnné v dávkovém příkazu. Například pokud definujete proměnnou jako char(3) a pak ji nastavíte na hodnotu větší než tři znaky, data se zkrátí na definovanou velikost a SQL příkaz uspěje.

parameter_data_type

Datový typ parametru. Pro Transact-SQL funkce jsou povoleny všechny skalární datové typy .

[ = výchozí ]

Výchozí hodnota parametru. Pokud definujete výchozí hodnotu, můžete funkci spustit bez zadání hodnoty pro daný parametr.

Když má parametr funkce výchozí hodnotu, musíte při volání funkce zadat klíčové slovo DEFAULT , abyste získali výchozí hodnotu. Toto chování se liší od použití parametrů s výchozími hodnotami v uložených procedurách, ve kterých vynechání parametru znamená také výchozí hodnotu.

return_data_type

Návratová hodnota skalární uživatelem definované funkce.

Pro funkce v Fabric Data Warehouse můžete použít všechny datové typy kroměčasové značkyrowversion/. Neskalární typy jako tabulky nejsou povoleny.

U externích UDF (Náhled) je klauzule RETURNS volitelná. Pokud je vynechán, typ návratu je automaticky odvozen z typu návratu odkazované funkce Fabric User Data. Můžete specifikovat klauzuli, RETURNS která přepisuje odvozený typ return, když je to potřeba.

function_body

Řada příkazů Transact-SQL.

Ve skalárních funkcích je function_body řada příkazů Transact-SQL, které se společně vyhodnotí jako skalární hodnota, která může zahrnovat:

  • Výraz s jedním příkazem
  • Vícepříkazové výrazy (IF/ELSE a BEGIN/END bloky
  • Místní proměnné
  • Dostupná volání předdefinovaných funkcí SQL
  • Volání jiných uživatelem definovaných funkcí
  • SELECT příkazy a odkazy na tabulky, pohledy a řádkové tabulkové funkce
  • Příkazy řízení toku, včetně IF/ELSE, WHILE, BREAK, CONTINUE, a RETURN

U externích UDF (Preview) nelze specifikovat function_body, protože implementace funkce je definována externě v příslušné Fabric User Data Function. Databáze ukládá pouze metadata funkcí. Logika spustitelného souboru se nachází v definici externí funkce.

scalar_expression

Určuje skalární hodnotu, kterou skalární funkce vrátí.

select_stmt

Jediný SELECT příkaz, který definuje návratovou hodnotu vložené funkce s hodnotou tabulky. Pro tabulkovou funkci v řádku neexistuje tělo funkce. Tabulka je výsledná množina jednoho SELECT příkazu.

TABLE

Určuje, že návratová hodnota funkce hodnotící tabulku (TVF) je tabulka. Konstanty a @local_variables můžete předávat jen TVF.

V inline TVF (náhled) definujete TABLE návratovou hodnotu pomocí jednoho SELECT příkazu. Vložené funkce nemají přiřazené návratové proměnné.

<function_option>

V Fabric Data Warehouse ENCRYPTION nejsou klíčová slova a EXECUTE AS podporována.

Podporované možnosti funkcí zahrnují:

INLINE = AUTO

Specifikuje, zda lze vytvořit nebo změnit uživatelsky definovanou škálovací funkci bez ohledu na požadavky na inline. Klauzule INLINE je nepovinná. U inlineabilního skalárního UDF specifikace INLINE = AUTO nemění jeho inlineability ani chování při vykonávání.

Pro podporovaný samostatný volací vzor viz Vytvoření skalárního UDF pro samostatné vykonání.

SCHEMABINDING

Určuje, že funkce je svázána s databázovými objekty, na které odkazuje. Když určíte SCHEMABINDING, nemůžete upravovat podkladové objekty (například pohled nebo tabulku) tak, aby to ovlivnilo definici funkce. Nejprve musíte upravit nebo zrušit definici funkce, abyste odstranili závislosti na objektu, který chcete upravit.

Vazba funkce na objekty, na které odkazuje, je odstraněna pouze v případě, že dojde k jedné z následujících akcí:

  • Ty tu funkci necháš.

  • Použijete příkaz funkce a odstraníte ALTERSCHEMABINDING tuto možnost.

Funkci můžete schema vázat pouze tehdy, pokud jsou splněny následující podmínky:

  • Jakékoliv uživatelsky definované funkce, na které funkce odkazuje, jsou také vázané na schéma.

  • Funkce odkazuje na objekty pomocí dvoudílného názvu.

  • V těle UDF můžete odkazovat pouze na vestavěné funkce a další UDF ve stejné databázi.

  • Uživatel, který příkaz vykoná, CREATE FUNCTION má oprávnění ODKAZOVAT na databázové objekty, na které funkce odkazuje.

Chcete-li odebrat SCHEMABINDING, použijte ALTER.

VRÁTÍ HODNOTU NULL PŘI VSTUPU NULL | VOLÁNO NA VSTUPU NULL

Určuje OnNULLCall atribut skalární-hodnotné funkce. Pokud tento atribut nespecifikujete, CALLED ON NULL INPUT je automaticky implikován a tělo funkce se vykoná, i když NULL je předáno jako argument.

JAKO VNĚJŠÍ FUNCTION

Odkazuje na Fabric User Data Function (UDF). Když je funkce vyvolána, vykonání je delegováno na odkazovanou Fabric User Data Function, kde se logika vykoná a výsledek se vrátí volajícímu T-SQL.

Tato klauzule přijímá následující parametry:

  • Název sady funkcí: Název sady funkcí, která obsahuje Fabric User Data Function. Každá Fabric User Data Function musí patřit do sady funkcí.
  • Název funkce: Název Fabric User Data Function, na kterou se odkazuje.

Následující syntax ukazuje, jak jsou tyto parametry specifikovány:

CREATE FUNCTION [schema_name.]function_name
AS EXTERNAL FUNCTION <<functionset_name>>.<<python_function_name>>

Protože je funkce vykonávána na dálku, volání externí funkce obvykle způsobuje vyšší latenci než spuštění nativní uživatelsky definované T-SQL funkce. Používejte externí funkce, když je požadovaná obchodní logika implementována ve Fabric a nelze ji přímo vyjádřit v T-SQL.

Příkaz CREATE FUNCTION automaticky odvozuje typ návratu, parametry a typy parametrů z definice odkazované externí Fabric User Data Function. Pokud se změní podpis externí funkce Fabric User Data, musíte funkci znovu vytvořit tak, aby byla její definice synchronizována s aktualizovaným podpisem.

Osvědčené postupy

  • Napište uživatelsky definované funkce tak, aby byly inline-ovatelné. Pro více informací o konceptu inlining viz Inlining skalárního UDF. Pro příklady, jak udělat skalární UDF inlineable, viz Vytvořit skalární UDF v Microsoft Fabric Data Warehouse.

  • Pokud nevytvoříte uživatelsky definovanou funkci se schemabindingem, změny základních objektů mohou ovlivnit definici funkce a způsobit neočekávané výsledky při jejím vyvolání. Když určíte WITH SCHEMABINDING , kdy funkci vytvoříte, zajistíte, že pozdější změny základních objektů nemohou změnit ani narušit chování funkce.

  • Kdykoli je to možné, implementujte svou logiku jako uživatelsky definovanou funkci T-SQL (UDF). Používejte externí UDF pouze pro funkce, které nelze implementovat v jazyce T-SQL. Tento přístup pomáhá minimalizovat režijní režie vzdáleného vykonávání a obecně poskytuje lepší výkon dotazů.

Interoperabilita

Vložené funkce definované uživatelem s hodnotou tabulky

Funkce s tabulkovými hodnotami v textu přijímá pouze jeden SELECT příkaz.

Skalární uživatelem definované funkce

  • Pokud je skalární UDF neinlineovatelný, CREATE příkaz OR ALTER by příkaz DDL odmítl s vlastní chybovou zprávou.

  • Neinlineable funkci lze vytvořit zadáním INLINE=AUTO možnosti funkce. Funkce neinlineable nelze použít v dotazu SELECT ... FROM na uživatelskou tabulku. INLINE=AUTO Nedělá funkci inlineabilní.

  • Následující příkazy jsou platné ve skalární-hodnotové funkci:

    • Příkazy přiřazení.
    • Příkazy řízení toku kromě TRY...CATCH a GOTO příkazů.
    • DECLARE příkazy definující lokální datové proměnné.
    • Volání vestavěných funkcí.
    • Odkazy na tabulky/pohledy/iTVF/jiné skalární UDF.
  • DML příkazy nejsou povoleny v skalárních uživatelsky definovaných funkcích.

Metadatové informace

Tato část obsahuje seznam zobrazení systémového katalogu, která můžete použít k vrácení metadat o uživatelem definovaných funkcích.

  • sys.sql_modules: Zobrazuje definici Transact-SQL uživatelsky definovaných funkcí i informace o možnosti přímého řádkování. Například:

      SELECT 
          SCHEMA_NAME(o.schema_id) AS SchemaName,
          o.name AS FunctionName,
          m.definition AS FunctionDefinition,
          m.is_inlineable AS Inlineable,
          m.inline_eligibility_mask AS InlineEligibilityMask
      FROM sys.objects o
      JOIN sys.sql_modules m ON o.object_id = m.object_id
      WHERE o.type = 'FN';
    
  • sys.parameters: Zobrazuje informace o parametrech definovaných v uživatelsky definovaných funkcích. Následující příklad využívá sys.parameters katalogový pohled k zobrazení podpisů funkcí, včetně typů návratů a typů datových parametrů:

     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 o JOIN sys.parameters p ON p.object_id = o.object_id JOIN sys.types 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) 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;
    
  • sys.sql_výraz_závislostí: Zobrazuje základní objekty, na které se odkazuje funkce.

Povolení

Funkce můžou vytvářet členové role správce pracovního prostoru Infrastruktury, člena a přispěvatele.

Inlining skalárního UDF

Microsoft Fabric Data Warehouse automaticky vkládá způsobilé skalární UDF během kompilace dotazů.

Inline bloku výrazu kompiluje příkazy funkce, včetně větví a smyček, do skalárního výrazu, který se vykonává jako součást volajícího dotazu. Skalární UDF inline transformuje tělo funkce na výrazy nebo poddotazy jako součást volajícího dotazu.

Funkce může splnit požadavky pro obě techniky, ale engine vybírá jednu podle její definice. Různé funkce v rámci jednoho dotazu mohou používat různé techniky.

Jak Microsoft Fabric Data Warehouse rozšiřuje své inline schopnosti, stávající funkce je automaticky získávají.

Podporované konstrukce funkcí

Následující tabulka porovnává podporované konstrukce funkcí-těla.

Konstrukce funkce a těla Inline bloku výrazu Vložení skalárních uživatelsky definovaných funkcí
Skalární výrazy, lokální proměnné a IF/ELSE Supported Supported
WHILE smyčky, včetně BREAK a CONTINUE Supported Nepodporováno
Více RETURN příkazů Supported Nepodporováno
NEWID() Supported Nepodporováno
Časově závislé funkce (například GETDATE() a SYSDATETIME()) Supported Nepodporováno
Přístup k tabulce, zobrazení nebo inline TVF Nepodporováno Supported
Volání skalárních UDF* Nepodporováno Supported

* Uživatelsky definované funkce mohou být vnořeny: jeden UDF může volat další. Úroveň vnoření se zvyšuje, když volaná funkce začne, a klesá po jejím dokončení. Microsoft Fabric Data Warehouse podporuje až čtyři úrovně vnoření, pokud tělo UDF odkazuje na tabulku, pohled nebo inline TVF, nebo až 32 úrovní jinak. Překročení limitu vnoření způsobí selhání řetězce volajících funkcí.

Integrované funkce

Podpora vestavěných funkcí, včetně systémových funkcí, se liší mezi oběma inline technikami.

Například vytvoření UDF, které používá @@ROWCOUNT bez INLINE = AUTO vrací chybu 19841. Chybová zpráva obsahuje následující text:

Function <function_name> cannot be inlined.
Expression block: Unsupported built-in @@ROWCOUNT found.
Scalar UDF inlining: Unsupported built-in @@ROWCOUNT found.

Pro konkrétní definici funkce viz Zkontrolujte, zda lze skalární UDF inlineovat.

Podporované dotazy na volání

Následující tabulka porovnává podporu calling-query pro inlineable scalar UDF.

Funkce dotazu Inline bloku výrazu Vložení skalárních uživatelsky definovaných funkcí
UDF volá v seznamu SELECT , WHERE, nebo JOIN ... ON Supported Supported
Přímé UDF volání do GROUP BY nebo HAVING Supported Nepodporováno
Přímé UDF volání ORDER BY Supported Nepodporováno
CTE v dotazu na volání Supported Nepodporováno
ROLLUP, CUBE, nebo GROUPING SETS Nepodporováno Nepodporováno

Pokud jakékoli UDF volání spoléhá na Scalar UDF inlineing, musí celý dotaz splňovat požadavky dané techniky na volání a dotaz.

S inline skalárním UDF promítejte výsledek UDF do SELECT seznamu a seřaďte podle aliasu sloupce nebo ordinálu místo přímého volání UDF v ORDER BY. Pro příklady přepisování dotazů viz Adaptace volajícího dotazu pro inline Scalar UDF. Další omezení provádění najdete v části Omezení.

Kontrola, jestli je možné inlinovat skalární uživatelem definovanou uživatelem

Katalogový sys.sql_modules pohled popisuje způsobilost na základě definice funkce. is_inlineable je 1 pro inlineable definici a 0 jinak. inline_eligibility_mask identifikuje způsobilé techniky:

inline_eligibility_mask Způsobilost definice
0 Ani jedna z těchto technik
1 Vložení skalárních uživatelsky definovaných funkcí
2 Inline bloku výrazu
3 Obě metody

Tyto hodnoty popisují definici funkce, nikoli plán vykonání konkrétního dotazu.

Použijte následující ukázkový dotaz k ověření, zda je skalární UDF inlineovatelný:

SELECT
    SCHEMA_NAME(b.schema_id) AS function_schema_name,
    b.name AS function_name,
    b.type_desc AS function_type,
    a.is_inlineable,
    a.inline_eligibility_mask
FROM sys.sql_modules AS a
     INNER JOIN sys.objects AS b
         ON a.object_id = b.object_id
WHERE b.type IN ('FN');

Omezení

  • Volání skalárního UDF v nepodporovaném dotazovacím kontextu může vrátit chybu Scalar UDF execution is currently unavailable in this context.
  • Dotaz, který spoléhá na Scalar UDF inline, může selhat, pokud obsahuje více než 10 UDF volání.

Příklady

A. Vytvoření vložené funkce s hodnotou tabulky

Následující příklad vytváří inline tabulkovou funkci, která vrací klíčové informace o modulech a filtruje podle parametru objectType . Obsahuje výchozí hodnotu, která vrací všechny moduly při volání funkce s parametrem DEFAULT . Tento příklad využívá některé pohledy z katalogu systému zmíněné v metadatech.

CREATE FUNCTION dbo.ModulesByType (@objectType CHAR(2) = '%%')
RETURNS TABLE
AS
RETURN (
        SELECT sm.object_id AS 'Object Id',
            o.create_date AS 'Date Created',
            OBJECT_NAME(sm.object_id) AS 'Name',
            o.type AS 'Type',
            o.type_desc AS 'Type Description',
            sm.DEFINITION AS 'Module Description',
            sm.is_inlineable AS 'Inlineable'
        FROM sys.sql_modules AS sm
        INNER JOIN sys.objects AS o ON sm.object_id = o.object_id
        WHERE o.type LIKE '%' + @objectType + '%'
        );
GO

Zavolejte funkci, která vrací všechny inline tabulkové funkce (IF):

SELECT * FROM dbo.ModulesByType('IF'); -- SQL_INLINE_TABLE_VALUED_FUNCTION

Nebo vyhledejte všechny skalární funkce (FN):

SELECT * FROM dbo.ModulesByType('FN'); -- SQL_SCALAR_FUNCTION

B. Kombinování výsledků vložené funkce s hodnotou tabulky

Tento jednoduchý příklad využívá dříve vytvořený inline TVF k demonstraci, jak lze jeho výsledky kombinovat s dalšími tabulkami pomocí .CROSS APPLY Zde vyberete všechny sloupce z obou sys.objects a výsledky pro ModulesByType všechny řádky, které se shodují ve sloupci type . Pro více informací o použití APPLYviz klauzule FROM plus JOIN, APPLY, PIVOT (Transact-SQL).

SELECT * 
FROM sys.objects AS o
CROSS APPLY dbo.ModulesByType(o.type);
GO

C. Vytvoření skalární funkce definované uživatelem

Následující příklad vytvoří vložený skalární UDF, který maskuje vstupní text.

CREATE OR ALTER FUNCTION [dbo].[cleanInput] (@InputString VARCHAR(100))
    RETURNS VARCHAR(50)
    AS
    BEGIN
        DECLARE @Result VARCHAR(50);
        DECLARE @CleanedInput VARCHAR(50);

        -- Trim whitespace
        SET @CleanedInput = LTRIM(RTRIM(@InputString));

        -- Handle empty or null input
        IF @CleanedInput = '' OR @CleanedInput IS NULL
        BEGIN
            SET @Result = '';
        END
        ELSE IF LEN(@CleanedInput) <= 2
        BEGIN
            -- If string length is 1 or 2, just return the cleaned string
            SET @Result = @CleanedInput;
        END
        ELSE
        BEGIN
            -- Construct the masked string
            SET @Result = 
                LEFT(@CleanedInput, 1) +
                REPLICATE('*', LEN(@CleanedInput) - 2) +
                RIGHT(@CleanedInput, 1);
        END

        RETURN @Result
    END

Funkci můžete volat takto:

DECLARE @input varchar(100) = '123456789';

SELECT dbo.cleanInput (@input) AS function_output;

Další příklady použití skalárních funkcí v datovém skladu Fabric:

SELECT V příkazu:

SELECT TOP 10 
t.id, t.name, 
dbo.cleanInput (t.name) AS function_output
FROM dbo.MyTable AS t;

V klauzuli WHERE :

 SELECT t.id, t.name, dbo.cleanInput(t.name) AS function_output
FROM dbo.MyTable AS t
WHERE dbo.cleanInput(t.name) = '1*******9';

V klauzuli JOIN :

SELECT t1.id, t1.name, 
     dbo.cleanInput (t1.name) AS function_output, 
     dbo.cleanInput (t2.name) AS function_output_2
FROM dbo.MyTable1 AS t1
    INNER JOIN dbo.MyTable2 AS t2 
        ON dbo.cleanInput(t1.name)=dbo.cleanInput(t2.name);

V klauzuli ORDER BY :

SELECT  t.id, t.name, dbo.cleanInput (t.name) AS function_output
FROM dbo.MyTable AS t
ORDER BY function_output;

Ve Warehouse můžete také volat skalární UDF z příkazů pro manipulaci s daty, jako INSERTjsou , UPDATE, nebo DELETE. Tyto příklady úprav dat se nevztahují na SQL analytics endpoint.

SELECT t.id, t.name, dbo.cleanInput (t.name) AS function_output 
INTO dbo.MyTable_new
FROM dbo.MyTable AS t;

UPDATE t
SET t.mycolumn_new = dbo.cleanInput (t.name)
FROM dbo.MyTable AS t;

DELETE t
FROM dbo.MyTable AS t
WHERE dbo.cleanInput(t.name) = '1*******9';

D. Vytvořte externí funkci

Následující příklad vytváří externí funkci pojmenovanou geohash ve schématu, dbo která odkazuje geohash na Fabric User Data Function v sadě spatial_functions funkcí. Protože definice parametrů a typ návratu jsou odvozeny z odkazované Fabric User Data Function, nemusí být explicitně specifikovány ve příkazuCREATE FUNCTION.

CREATE FUNCTION dbo.geohash
AS EXTERNAL FUNCTION spatial_functions.geohash;

Po vytvoření lze externí funkci použít v T-SQL dotazech stejně jako jakoukoli jinou uživatelsky definovanou nebo vestavěnou funkci. Lze na něj odkazovat všude tam, kde jsou podporována volání funkcí, což umožňuje bezproblémovou integraci Fabric User Data Functions do T-SQL kódu.

E. Vytvořte skalární UDF pro samostatné provádění

Následující nastavení pro vytváření tabulek a načítání dat vyžaduje Warehouse. Na SQL analytics endpointu použijte existující tabulku podloženou zdrojem s požadovanými sloupci a daty.

CREATE TABLE dbo.Customer
(
    CustomerID INT NOT NULL,
    CustomerName VARCHAR(100) NOT NULL,
    CustomerType VARCHAR(20) NOT NULL,
    MemberSince DATE NOT NULL,
    YearToDateRevenue DECIMAL(18, 2) NOT NULL
);
GO

INSERT INTO dbo.Customer
(
    CustomerID,
    CustomerName,
    CustomerType,
    MemberSince,
    YearToDateRevenue
)
VALUES
    (1, 'Customer 1', 'Regular', '2020-01-15', 12000.00),
    (2, 'Customer 2', 'Premium', '2022-06-01', 24000.00),
    (3, 'Customer 3', 'VIP',     '2024-03-10', 36000.00);
GO

Funkce níže kombinuje přístup k tabulce s GETUTCDATE(). Přístup k tabulce zabraňuje inlineování Expression Block a GETUTCDATE() zabraňuje inlineování Scalar UDF.

Bez WITH INLINE = AUTO, definice je při vytvoření nebo změně odmítnuta. Chyba hlásí, že funkce nemůže být vložena do řádku, a uvádí důvody odmítnutí pro obě techniky. Určete, WITH INLINE = AUTO chcete-li povolit vytvoření:

CREATE OR ALTER FUNCTION dbo.GetCustomerTenureDays (@CustomerID INT)
RETURNS INT
WITH INLINE = AUTO
AS
BEGIN
    DECLARE @MemberSince DATE;

    SELECT @MemberSince = MemberSince
    FROM dbo.Customer
    WHERE CustomerID = @CustomerID;

    RETURN DATEDIFF(DAY, @MemberSince, GETUTCDATE());
END;
GO

Funkce je vytvořena, ale zůstává neřádkovatelná: is_inlineable a inline_eligibility_mask jsou obě 0. Samostatný hovor uspěje:

DECLARE @udf_output int;
SET @udf_output = dbo.GetCustomerTenureDays(1);
SELECT @udf_output as 'udf_output';

Volání funkce v dotazu přes tabulku uživatelů není podporováno:

SELECT
    CustomerID,
    dbo.GetCustomerTenureDays(CustomerID) AS TenureDays
FROM dbo.Customer;

Tento dotaz vrací Scalar UDF execution is currently unavailable in this context.

Návod

Pro použití této logiky v dotazu nad uživatelskými tabulkami vyhodnoťte hodnotu aktuálního času v volajícím a předejte ji jako parametr. Pro přepsanou funkci a volací dotaz viz Předání časově závislé hodnoty do UDF pro přístup k datům.

Platí pro:Azure Synapse Analytics

Vytváří uživatelsky definovanou funkci (UDF) v Azure Synapse Analytics. Uživatelem definovaná funkce je rutina Transact-SQL, která přijímá parametry, provádí akci, například složitý výpočet, a vrací výsledek této akce jako hodnotu. Uživatelem definované funkce s hodnotami tabulky (TVF) vracejí datový typ tabulky.

Návod

Pro syntaxi v Fabric Data Warehouse viz verze for CREATE FUNCTION Fabric Data Warehouse.

  • Ve službě Azure Synapse Analytics CREATE FUNCTION může vrátit tabulku pomocí syntaxe pro vložené funkce s hodnotami tabulky (Preview) nebo může vrátit jednu hodnotu pomocí syntaxe skalárních funkcí.

  • V bezserverových fondech SQL ve službě Azure Synapse Analytics můžete vytvářet vložené funkce pro hodnoty tabulky, CREATE FUNCTION ale ne skalární funkce.

    Použijte toto tvrzení k vytvoření opakovaně použitelné rutiny, kterou můžete využít těmito způsoby:

  • V Transact-SQL příkazy, jako je SELECT

  • V aplikacích, které volají funkci

  • V definici další uživatelem definované funkce

  • Definování omezení CHECK u sloupce

  • Nahrazení uložené procedury

  • Použití vložené funkce jako predikátu filtru pro zásadu zabezpečení

Transact-SQL syntaktické konvence

Syntaxe

Syntaxe skalárních funkcí

-- Transact-SQL Scalar Function Syntax (in dedicated pools in Azure Synapse Analytics)
-- Not available in the serverless SQL pools in Azure Synapse Analytics

CREATE FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] parameter_data_type
    [ = default ] }
    [ ,...n ]
  ]
)
RETURNS return_data_type
    [ WITH <function_option> [ ,...n ] ]
    [ AS ]
    BEGIN
        function_body
        RETURN scalar_expression
    END
[ ; ]

<function_option>::=
{
    [ SCHEMABINDING ]
  | [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]
}

Syntaxe vložené funkce s hodnotou tabulky

-- Transact-SQL Inline Table-Valued Function Syntax
-- Preview in dedicated SQL pools in Azure Synapse Analytics
-- Available in the serverless SQL pools in Azure Synapse Analytics
CREATE FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] parameter_data_type
    [ = default ] }
    [ ,...n ]
  ]
)
RETURNS TABLE
    [ WITH SCHEMABINDING ]
    [ AS ]
    RETURN [ ( ] select_stmt [ ) ]
[ ; ]

Argumenty

schema_name

Název schématu, do kterého patří uživatelem definovaná funkce.

function_name

Název uživatelem definované funkce. Názvy funkcí musí dodržovat pravidla identifikátorů a být jedinečné v databázi a jejím schématu.

Poznámka:

Musíte zahrnout závorky za název funkce, i když parametr nespecifikujete.

@ parameter_name

Parametr v uživatelem definované funkci. Můžete deklarovat jeden nebo více parametrů.

Funkce může mít až 2 100 parametrů. Když uživatel nebo aplikace volá funkci, musíte zadat hodnotu pro každý deklarovaný parametr, pokud nedefinujete výchozí hodnotu parametru.

Zadejte název parametru pomocí znaku at (@) jako prvního znaku. Název parametru musí dodržovat pravidla pro identifikátory. Parametry jsou lokální pro funkci; Stejné názvy parametrů můžete použít i v jiných funkcích. Parametry mohou nahradit pouze konstanty; Nelze je použít místo názvů tabulek, sloupců nebo jiných databázových objektů.

Poznámka:

ANSI_WARNINGS není respektováno, když předáváte parametry v uložené procedurě, uživatelsky definované funkci nebo když deklarujete a nastavujete proměnné v dávkovém příkazu. Například pokud definujete proměnnou jako char(3) a pak ji nastavíte na hodnotu větší než tři znaky, data se zkrátí na definovanou velikost a INSERT příkaz or UPDATE uspěje.

parameter_data_type

Datový typ parametru. Pro Transact-SQL funkce jsou povolené všechny skalární datové typy podporované ve službě Azure Synapse Analytics. Datový typ s časovým razítkem (verze řádku) není podporovaným typem.

[ = výchozí ]

Výchozí hodnota parametru. Pokud definujete výchozí hodnotu, můžete funkci spustit bez zadání hodnoty pro daný parametr.

Když má parametr funkce výchozí hodnotu, musíte při volání funkce zadat klíčové slovo DEFAULT , abyste získali výchozí hodnotu. Toto chování se liší od použití parametrů s výchozími hodnotami v uložených procedurách, ve kterých vynechání parametru znamená také výchozí hodnotu.

return_data_type

Návratová hodnota skalární uživatelem definované funkce. Pro Transact-SQL funkce jsou povolené všechny skalární datové typy podporované ve službě Azure Synapse Analytics. Datový typ datovéhorazítka/ není podporovaným typem. Kurzor a tabulka typu bez skaláru nejsou povoleny.

function_body

Řada příkazů Transact-SQL function_body nemůže obsahovat SELECT příkaz a nemůže odkazovat na databázová data. function_body nemůže odkazovat na tabulky ani pohledy. Těleso funkce může volat jiné deterministické funkce, ale nemůže volat nedeterministické funkce.

Ve skalárních funkcích je function_body řada Transact-SQL příkazů, které jsou společně vyhodnoceny jako skalární hodnota.

scalar_expression

Určuje skalární hodnotu, kterou skalární funkce vrátí.

select_stmt

Jediný SELECT příkaz, který definuje návratovou hodnotu vložené funkce s hodnotou tabulky. Pro inline tabulkově hodnotovou funkci neexistuje tělo funkce; tabulka je výsledná množina jednoho SELECT příkazu.

TABLE

Určuje, že návratová hodnota funkce hodnotící tabulku (TVF) je tabulka. Konstanty a @local_variables můžete předávat jen TVF.

V inline TVF (náhled) definujete TABLE návratovou hodnotu pomocí jednoho SELECT příkazu. Vložené funkce nemají přiřazené návratové proměnné.

<function_option>

Určuje, že funkce má jednu nebo více z následujících možností.

SCHEMABINDING

Určuje, že funkce je svázána s databázovými objekty, na které odkazuje. Když určíte SCHEMABINDING, nemůžete upravovat podkladové objekty (například pohled nebo tabulku) tak, aby to ovlivnilo definici funkce. Nejprve musíte upravit nebo zrušit definici funkce, abyste odstranili závislosti na objektu, který chcete upravit.

Vazba funkce na objekty, na které odkazuje, je odstraněna pouze v případě, že dojde k jedné z následujících akcí:

  • Ty tu funkci necháš.

  • Použijete příkaz funkce a odstraníte ALTERSCHEMABINDING tuto možnost.

Funkci můžete schema vázat pouze tehdy, pokud jsou splněny následující podmínky:

  • Jakékoliv uživatelsky definované funkce, na které funkce odkazuje, jsou také vázané na schéma.

  • Reference funkcí používají názvy jednodílné nebo dvoudílné.

  • V těle UDF můžete odkazovat pouze na vestavěné funkce a další UDF ve stejné databázi.

  • Uživatel, který příkaz vykoná, CREATE FUNCTION má oprávnění ODKAZOVAT na databázové objekty, na které funkce odkazuje.

Chcete-li odebrat SCHEMABINDING, použijte ALTER.

VRÁTÍ HODNOTU NULL PRO VSTUP NULL | VOLÁNA PŘI VSTUPU S HODNOTOU NULL

Určuje OnNULLCall atribut skalární-hodnotné funkce. Pokud tento atribut nespecifikujete, CALLED ON NULL INPUT je automaticky implikován a tělo funkce se vykoná, i když NULL je předáno jako argument.

Osvědčené postupy

Pokud nevytvoříte uživatelsky definovanou funkci s klauzulí SCHEMABINDING, změny základních objektů mohou ovlivnit definici funkce a způsobit neočekávané výsledky při jejím vyvolání. Specifikujte klauzuli WITH SCHEMABINDING při vytváření funkce. Tato klauzule zajišťuje, že objekty odkazované v definici funkce nemůžete upravovat, pokud nezměníte i funkci.

Interoperabilita

Následující příkazy jsou platné ve skalární-hodnotové funkci:

  • Příkazy přiřazení.

  • Příkazy pro řízení toku, kromě TRY... CATCH výroky.

  • Příkazy DECLARE, které definují lokální datové proměnné.

V inline tabulové funkci (náhledu) můžete použít pouze jeden příkaz select.

Omezení

Nemůžete použít uživatelsky definované funkce k provádění akcí, které mění stav databáze.

Můžete vnořit uživatelem definované funkce. Jedna uživatelsky definovaná funkce může volat jinou. Úroveň vnoření se zvyšuje při zahájení vykonávání volané funkce a snižuje se, když volaná funkce dokončí vykonání. Pokud překročíte maximální úrovně vnoření, celý řetězec volacích funkcí selže.

Nemůžete vytvářet objekty, včetně funkcí, v databázi master vašeho serverless SQL poolu v Azure Synapse Analytics.

Metadatové informace

Tato část obsahuje seznam zobrazení systémového katalogu, která můžete použít k vrácení metadat o uživatelem definovaných funkcích.

  • sys.sql_modules: Zobrazuje definici Transact-SQL uživatelsky definovaných funkcí. Například:

    SELECT definition, type   
    FROM sys.sql_modules AS m  
    JOIN sys.objects AS o   
        ON m.object_id = o.object_id   
        AND type = ('FN');
    
  • sys.parameters: Zobrazuje informace o parametrech definovaných v uživatelsky definovaných funkcích.

  • sys.sql_výraz_závislostí: Zobrazuje základní objekty, na které se odkazuje funkce.

Povolení

Vyžaduje CREATE FUNCTION oprávnění v databázi a ALTER povolení ke schématu, ve kterém je funkce vytvářena.

Příklady

A. Změna datového typu pomocí skalární funkce definované uživatelem

Tato jednoduchá funkce přijímá int datový typ jako vstup a vrací desetinný (10,2) datový typ jako výstup.

CREATE FUNCTION dbo.ConvertInput (@MyValueIn int)  
RETURNS decimal(10,2)  
AS  
BEGIN
    DECLARE @MyValueOut int;  
    SET @MyValueOut= CAST( @MyValueIn AS decimal(10,2));  
    RETURN(@MyValueOut);  
END;  
GO  

SELECT dbo.ConvertInput(15) AS 'ConvertedValue';  

Poznámka:

Skalární funkce nejsou dostupné v serverless SQL poolech.

B. Vytvoření vložené funkce s hodnotou tabulky

Následující příklad vytváří inline tabulkovou funkci, která vrací klíčové informace o modulech a filtruje podle parametru objectType . Obsahuje výchozí hodnotu, která vrací všechny moduly při volání funkce s parametrem DEFAULT . Tento příklad využívá některé pohledy z katalogu systému zmíněné v metadatech.

CREATE FUNCTION dbo.ModulesByType(@objectType CHAR(2) = '%%')
RETURNS TABLE
AS
RETURN
(
    SELECT 
        sm.object_id AS 'Object Id',
        o.create_date AS 'Date Created',
        OBJECT_NAME(sm.object_id) AS 'Name',
        o.type AS 'Type',
        o.type_desc AS 'Type Description', 
        sm.definition AS 'Module Description'
    FROM sys.sql_modules AS sm  
    JOIN sys.objects AS o ON sm.object_id = o.object_id
    WHERE o.type like '%' + @objectType + '%'
);
GO

Můžete volat funkci, která vrací všechny objekty view (V) s:

select * from dbo.ModulesByType('V');

Poznámka:

Funkce s tabulkovou hodnotou jsou dostupné v serverless SQL poolech, ale v náhledu v dedikovaných SQL poolech.

C. Kombinování výsledků vložené funkce s hodnotou tabulky

Tento jednoduchý příklad využívá dříve vytvořený inline TVF k demonstraci, jak lze jeho výsledky kombinovat s dalšími tabulkami pomocí .CROSS APPLY V tomto příkladu vyberete všechny sloupce z obou sys.objects a výsledky pro ModulesByType všechny řádky, které odpovídají sloupci type . Pro více informací o použití APPLYviz klauzule FROM plus JOIN, APPLY, PIVOT (Transact-SQL).

SELECT * 
FROM sys.objects o
CROSS APPLY dbo.ModulesByType(o.type);
GO

Poznámka:

Funkce s tabulkovou hodnotou jsou dostupné v serverless SQL poolech, ale v náhledu v dedikovaných SQL poolech.

Další krok