CREATE FUNCTION

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 konvence syntaxe

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 se nedodržuje při předávání parametrů v uložené proceduře, uživatelsky definované funkci nebo při deklaraci a nastavení proměnných 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: Zobrazí definici Transact-SQL uživatelem 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: Zobrazí informace o parametrech definovaných v uživatelem definovaných funkcích.

• sys.sql_expression_dependencies: Zobrazí základní objekty odkazované funkcí.

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

vytvoření uživatelem definovaných funkcí (databázový stroj)