Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
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, aDELETE. - 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/ELSEaBEGIN/ENDbloky - Místní proměnné
- Dostupná volání předdefinovaných funkcí SQL
- Volání jiných uživatelem definovaných funkcí
-
SELECTpříkazy a odkazy na tabulky, pohledy a řádkové tabulkové funkce - Příkazy řízení toku, včetně
IF/ELSE,WHILE,BREAK,CONTINUE, aRETURN
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
ALTERSCHEMABINDINGtuto 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 FUNCTIONmá 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ý,
CREATEpříkaz ORALTERby příkaz DDL odmítl s vlastní chybovou zprávou.Neinlineable funkci lze vytvořit zadáním
INLINE=AUTOmožnosti funkce. Funkce neinlineable nelze použít v dotazuSELECT ... FROMna uživatelskou tabulku.INLINE=AUTONedě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...CATCHaGOTOpříkazů. -
DECLAREpří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.parameterskatalogový 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.
- Expression Block inline nepodporuje AI funkce, agregační funkce, metadata anibezpečnostní funkce v těle funkce.
- Skalární UDF inline má vestavěná funkční omezení popsaná v požadavcích na skalární UDF inline.
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.
Související obsah
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 FUNCTIONmůž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 FUNCTIONale 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
SELECTV 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
ALTERSCHEMABINDINGtuto 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 FUNCTIONmá 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.