VYTVOŘIT FUNKCI

platí pro: Azure Synapse AnalyticsAnalytics Platform System (PDW)

Vytvoří uživatelem definovanou funkci (UDF) ve službě Azure Synapse Analytics nebo PdW (Analytics Platform System). 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.

• V systému PDW (Analytics Platform System) musí být návratová hodnota skalární (jednoduchá).

• 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.

  Tento příkaz slouží k vytvoření opakovaně použitelné rutiny, kterou lze použít těmito způsoby:

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

• V aplikacích, které funkci volají

• 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í

Návod

Syntaxi ve službě Fabric Data Warehouse najdete ve verzi CREATE FUNCTION pro Microsoft Fabric Data Warehouse.

Transact-SQL konvence syntaxe

Syntaxe

Syntaxe skalárních funkcí

-- Transact-SQL Scalar Function Syntax (in dedicated pools in Azure Synapse Analytics and Parallel Data Warehouse)
-- 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í splňovat pravidla pro identifikátory a musí být jedinečné v rámci databáze a pro jeho schéma.

Poznámka:

Za názvem funkce se vyžadují závorky, i když není zadaný parametr.

@ parameter_name

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

Funkce může mít maximálně 2 100 parametrů. Hodnota každého deklarovaného parametru musí být zadána uživatelem při provádění funkce, pokud není pro parametr definováno výchozí nastavení.

Zadejte název parametru pomocí znaku at (@) jako prvního znaku. Název parametru musí být v souladu s pravidly pro identifikátory. Parametry jsou pro funkci lokální; Stejné názvy parametrů lze použít i v jiných funkcích. Parametry mohou probíhat pouze konstanty; Nelze je použít místo názvů tabulek, názvů sloupců ani názvů jiných databázových objektů.

Poznámka:

ANSI_WARNINGS při předávání parametrů v uložené procedury, uživatelem definované funkci nebo při deklaraci a nastavení proměnných v dávkovém příkazu. Pokud je například proměnná definována jako char(3) a pak je nastavená na hodnotu větší než tři znaky, data se zkrátí na definovanou velikost a příkaz INSERT nebo UPDATE bude úspěšný.

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 časového razítka (rowversion) není podporovaným typem.

[ = výchozí ]

Výchozí hodnota parametru. Pokud je definována výchozí hodnota, lze funkci provést bez určení hodnoty tohoto parametru.

Pokud má parametr funkce výchozí hodnotu, musí být klíčové slovo DEFAULT zadáno při zavolání funkce pro načtení výchozí hodnoty. 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časového razítkarowversion/ není podporovaným typem. Typy kurzoru a tabulky nejsou povoleny.

function_body

Řada příkazů Transact-SQL Function_body nemůže obsahovat SELECT příkaz a nemůže odkazovat na data databáze. Function_body nemůže odkazovat na tabulky ani zobrazení. Tělo 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 vloženou funkci s hodnotou tabulky neexistuje tělo funkce; tabulka je sada výsledků jednoho SELECT příkazu.

STŮL

Určuje, že návratová hodnota funkce hodnotící tabulku (TVF) je tabulka. Do TVF lze předat pouze konstanty a @local_variables .

Ve vložených TVF (Preview) je návratová hodnota TABLE definována pomocí jediného SELECT příkazu. Vložené funkce nemají přidružené 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. Pokud je zadána funkce SCHEMABINDING, základní objekty nelze upravit způsobem, který by ovlivnil definici funkce. Samotná definice funkce musí být nejprve upravena nebo zrušena, aby se odstranily závislosti na objektu, který má být změněn.

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

• Funkce je zrušena.

• Funkce je upravena pomocí příkazu ALTER s parametrem SCHEMABINDING, který není zadán.

Funkce může být svázána se schématem pouze tehdy, jsou-li splněny následující podmínky:

• Všechny uživatelem definované funkce odkazované funkcí jsou také vázané na schéma.

• Funkce a další funkce definované uživatelem, na které funkce odkazuje, se odkazují pomocí názvu jedné nebo dvoudílné části.

• V textu funkcí definovaných uživatelem lze odkazovat pouze na předdefinované funkce a jiné funkce definované uživatelem ve stejné databázi.

• Uživatel, který příkaz spustil CREATE FUNCTION , má oprávnění REFERENCES k databázovým objektům, 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 není zadán, CALLED ON NULL INPUT implicitně se předpokládá a tělo funkce se spustí i v případě, že NULL je předán jako argument.

Osvědčené postupy

Pokud uživatelem definovaná funkce není vytvořena s klauzulí SCHEMABINDING, změny provedené v podkladových objektech mohou ovlivnit definici funkce a při vyvolání způsobit neočekávané výsledky. Při vytváření funkce se doporučuje zadat WITH SCHEMABINDING klauzuli. Tím se zajistí, že objekty odkazované v definici funkce nelze upravit, pokud není také změněna.

Interoperabilita

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

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

• Příkazy control-of-Flow s výjimkou TRY... Příkazy CATCH.

• Příkazy DECLARE definující místní datové proměnné.

Ve vložené funkci s hodnotou tabulky (Preview) je povolen pouze jeden příkaz select.

Omezení

Uživatelem definované funkce nelze použít k provádění akcí, které upravují stav databáze.

Uživatelem definované funkce lze vnořit; to znamená, že jedna uživatelem definovaná funkce může volat jinou. Úroveň vnoření se zvýší při spuštění vykonávání volané funkce a sníží se při dokončení provádění volané funkce. Překročení maximální úrovně vnoření způsobí selhání celého řetězce volaných funkcí. V Microsoft Fabric Data Warehouse je možné uživatelem definované funkce vnořit až pět úrovní.

Objekty, včetně funkcí, nelze vytvořit v master databázi bezserverového fondu SQL ve službě 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 oprávnění CREATE FUNCTION v databázi a alter oprávnění ke schématu, ve kterém se funkce vytváří.

Příklady

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

Tato jednoduchá funkce přebírá jako vstup datový typ int a jako výstup vrátí datový typ decimal(10;2 ).

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 bezserverových fondech SQL.

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

Následující příklad vytvoří vloženou funkci s hodnotou tabulky, která vrátí některé klíčové informace o modulech, filtrování podle parametru objectType . Obsahuje výchozí hodnotu pro vrácení všech modulů při zavolání funkce s parametrem DEFAULT . Tento příklad používá některá zobrazení katalogu systému uvedená 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

Funkci pak můžete volat, aby se vrátily všechny objekty zobrazení (V) s:

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

Poznámka:

Vložené funkce pro hodnotu tabulky jsou k dispozici v bezserverových fondech SQL, ale ve verzi Preview ve vyhrazených fondech SQL.

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

Tento jednoduchý příklad používá dříve vytvořenou vloženou tvF k předvedení, jak lze výsledky kombinovat s jinými tabulkami pomocí křížového použití. Tady vybereme všechny sloupce z obou sys.objects sloupců a výsledky ModulesByType všech řádků odpovídajících sloupci type . Další informace o použití naleznete v tématu KLAUZULE FROM plus JOIN, APPLY, PIVOT (Transact-SQL).

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

Poznámka:

Vložené funkce pro hodnotu tabulky jsou k dispozici v bezserverových fondech SQL, ale ve verzi Preview ve vyhrazených fondech SQL.

Další krok

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