CREATE FUNCTION

A következőkre vonatkozik:Azure Synapse Analytics

Létrehoz egy felhasználó-definiált függvényt (UDF) az Azure Synapse Analytics-ben. A felhasználó által definiált függvények olyan Transact-SQL rutinok, amelyek paramétereket fogadnak el, végrehajtanak egy műveletet, például egy összetett számítást, és a művelet eredményét értékként adják vissza. A felhasználó által definiált táblaértékelt függvények (TVF-ek) táblaadattípust ad vissza.

Jótanács

A Fabric Data Warehouse-es szintaxisért lásd az for Fabric Data Warehouse verziójátCREATE FUNCTION.

• Az Azure Synapse Analyticsben CREATE FUNCTION a beágyazott táblaértékű függvények szintaxisával (előzetes verzió) adhat vissza egy táblát, vagy egyetlen értéket adhat vissza a skaláris függvények szintaxisával.

• Az Azure Synapse Analytics kiszolgáló nélküli SQL-készleteiben beágyazott táblaértékfüggvényeket hozhat létre, CREATE FUNCTION skaláris függvényeket azonban nem.

  Ezzel az utasítással készíts egy újrahasználható rutint, amelyet az alábbi módokon használhatsz:

• Az olyan Transact-SQL kijelentésekben, mint például SELECT

• A függvényt meghívó alkalmazásokban

• Egy másik felhasználó által definiált függvény definíciójában

• CHECK korlátozás definiálása egy oszlopon

• Tárolt eljárás cseréje

• Beágyazott függvény használata biztonsági házirend szűrőpredikátumaként

Transact-SQL szintaxis konvenciók

Szemantika

Skaláris függvény szintaxisa

-- 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 ]
}

Beágyazott táblaértékű függvény szintaxisa

-- 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 [ ) ]
[ ; ]

Érvek

schema_name

Annak a sémának a neve, amelyhez a felhasználó által definiált függvény tartozik.

function_name

A felhasználó által definiált függvény neve. A függvényneveknek követniük kell az azonosítók szabályait, és egyedinek kell lenniük az adatbázisban és annak sémájában.

Megjegyzés:

A függvénynév után zárójeleket kell beilleszteni, még akkor is, ha nem jelölsz meg paramétert.

@ parameter_name

A felhasználó által definiált függvény paramétere. Be lehet jelenteni egy vagy több paramétert.

Egy függvénynek legfeljebb 2100 paramétere lehet. Amikor egy felhasználó vagy alkalmazás függvényt hív, minden deklarált paraméterhez megadnod kell az értéket, hacsak nem definiálsz alapértelmezett értéket a paraméterhez.

Adjon meg egy paraméternevet úgy, hogy első karakterként egy at sign (@) karaktert használ. A paraméter nevének követnie kell az azonosítók szabályait. A paraméterek lokálisak a függvényre; Ugyanazokat a paraméterneveket más függvényekben is használhatod. A paraméterek csak az állandókat helyettesíthetik; nem használhatók táblanevek, oszlopnevek vagy más adatbázis-objektumok nevei helyett.

Megjegyzés:

ANSI_WARNINGS nem teljesül, ha paramétereket ad át egy tárolt eljárásban, felhasználó által definiált függvényben, vagy ha változókat deklarál és állít be egy batch utasításban. Például, ha egy változót char(3)-ként definiálsz, majd három karakternél nagyobb értékre állítod, az adat a megadott méretre rövidítik, és az INSERT or UPDATE utasítás sikerül.

parameter_data_type

A paraméter adattípusa. Transact-SQL függvények esetében az Azure Synapse Analyticsben támogatott összes skaláris adattípus engedélyezett. Az időbélyeg (sorverzió) adattípus nem támogatott típus.

[ = alapértelmezett ]

A paraméter alapértelmezett értéke. Ha alapértelmezett értéket definiálsz, akkor a függvényt úgy is végrehajthatod, hogy megadnád az adott paraméterhez szükséges értéket.

Ha a függvény paraméterének alapértelmezett értéke van, DEFAULT akkor a kulcsszót kell megadnod, amikor a függvényt hívod az alapértelmezett érték eléréséhez. Ez a viselkedés eltér az alapértelmezett értékekkel rendelkező paraméterek tárolt eljárásokban való használatától, amelyekben a paraméter kihagyása az alapértelmezett értéket is magában foglalja.

return_data_type

Egy skaláris, felhasználó által definiált függvény visszatérési értéke. Transact-SQL függvények esetében az Azure Synapse Analyticsben támogatott összes skaláris adattípus engedélyezett. A sorverzió/időbélyeg adattípusa nem támogatott típus. A kurzor és a táblázat nonskaláris típusai nem engedélyezettek.

function_body

Transact-SQL utasítások sorozata. A function_body nem tartalmazhat állítást SELECT , és nem hivatkozhat adatbázis adatokra. A function_body nem tud táblázatokat vagy nézeteket használni. A függvénytest más determinisztikus függvényeket is hívhat, de nemdeterminisztikus függvényeket nem.

A skaláris függvényekben a function_body Transact-SQL utasítások sorozata, amelyek együttesen egy skaláris értéket értékelnek ki.

scalar_expression

Megadja a skaláris függvény által visszaadott skaláris értéket.

select_stmt

SELECT Egyetlen utasítás, amely egy beágyazott táblaértékű függvény visszatérési értékét határozza meg. Egy besoros táblázatértékű függvény esetén nincs függvénytest; a tábla egyetlen SELECT állítás eredményhalmaza.

TABLE

Megadja, hogy a táblaértékű függvény (TVF) visszatérési értéke tábla. Csak állandókat és @local_variables-t tudsz átadni TVF-eknek.

Az inline TVF-ekben (előnézet) egyetlen állítással definiáljuk a TABLE visszahozási értéket SELECT . A beágyazott függvények nem rendelkeznek társított visszatérési változókkal.

<function_option>

Megadja, hogy a függvény az alábbi lehetőségek közül egyet vagy többet tartalmazzon.

SÉMAKÖTÉS

Megadja, hogy a függvény az általa hivatkozott adatbázis-objektumokhoz legyen kötve. Ha megadod SCHEMABINDING, nem módosíthatod az alapul szolgáló objektumokat (például egy nézetet vagy táblát) úgy, hogy az befolyásolja a függvény definícióját. Először módosítani vagy el kell hagyni a függvénydefiníciót, hogy eltávolítsuk a függőségeket a módosítani kívánt objektumról.

A függvény hivatkozási objektumokhoz való kötése csak akkor törlődik, ha az alábbi műveletek valamelyike történik:

• Kihagyod a funkciót.

• Te ALTER add a függvényutasítást, és távolítod el az SCHEMABINDING opciót.

Csak akkor lehet sémához kötni egy függvényt, ha a következő feltételek érvényesek:

• Bármely felhasználó által definiált függvény, amelyre a függvény hivatkozik, szintén sémához kötött.

• A függvényhivatkozások egy- vagy kétrészes neveket használnak.

• Az UDF-ek testén belül csak a beépített függvényekre és más UDF-ekre lehet hivatkozni ugyanabban az adatbázisban.

• A felhasználó végrehajtja CREATE FUNCTION az utasítást REFERENCES jogosultsággal rendelkezik azokon az adatbázisobjektumoknál, amelyekre a függvény hivatkozik.

A SCHEMABINDING eltávolításához használja a következőt ALTER: .

NULL ÉRTÉKET AD VISSZA NULL ÉRTÉKEN | NULL ÉRTÉKŰ BEMENET MEGHÍVÁSA

OnNULLCall Egy skaláris értékű függvény attribútumát adja meg. Ha nem határozod meg ezt az attribútumot, CALLED ON NULL INPUT alapértelmezettként implicit van, és a függvénytest akkor is fut, ha NULL argumentumként adják át.

Ajánlott eljárások

Ha nem hozol létre felhasználó által definiált függvényt a SCHEMABINDING záradékkal, az alapul szolgáló objektumok változásai befolyásolhatják a függvény definícióját, és váratlan eredményeket okozhatnak, amikor meghívod. Határozd meg a WITH SCHEMABINDING záradékot, amikor létrehozod a függvényt. Ez a záradék biztosítja, hogy a függvénydefinícióban hivatkozott objektumokat ne módosítsd, hacsak nem módosítod a függvényt is.

Interoperabilitás

A következő utasítások érvényesek egy skaláris értékű függvényben:

• Hozzárendelési utasítások.

• Áramlásirányítási utasítások, kivéve a TRY-t... CATCH nyilatkozatok.

• DECLARE utasításokat definiálnak, amelyek helyi adatváltozókat definiálnak.

Egy besorbeli táblázatértékű függvényben (előnézet) csak egyetlen select utasítást használhatsz.

Korlátozások

Felhasználó-definiált függvényeket nem használhatsz olyan műveletekhez, amelyek módosítják az adatbázis állapotát.

Be lehet ágyazni a felhasználó által definiált függvényeket. Egy felhasználó által definiált függvény meghívhat egy másikat. A beágyazási szint akkor nő, amikor a hívott függvény elindul, és csökken, amikor a hívott függvény befejezi a végrehajtást. Ha túlléped a maximális fészkelési szintet, az egész hívó függvénylánc meghibásodik.

Nem lehet objektumokat, beleértve funkciókat is, létrehozni a master szerver nélküli SQL poolod adatbázisában az Azure Synapse Analytics-ben.

Metadaták

Ez a szakasz felsorolja azokat a rendszerkatalógus-nézeteket, amelyekkel metaadatokat adhat vissza a felhasználó által definiált függvényekről.

• sys.sql_modules: Megjeleníti Transact-SQL felhasználó által definiált függvények definícióját. Például:

  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: A felhasználó által definiált függvényekben definiált paraméterekkel kapcsolatos információkat jeleníti meg.

• sys.sql_expression_dependencies: Megjeleníti a függvény által hivatkozott mögöttes objektumokat.

Engedélyek

Engedélyt CREATE FUNCTION kell megadni az adatbázisban, és ALTER engedélyt kell adni azon a sémán, amelyben a függvényt létrehozják.

Példák

Egy. Skaláris értékű, felhasználó által definiált függvény használata adattípus módosításához

Ez az egyszerű függvény int adattípust vesz bemenetként, és egy tizedes (10,2) adattípust ad vissza kimenetként.

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';  

Megjegyzés:

Skaláris függvények nem elérhetők szerver nélküli SQL poolokban.

B. Beágyazott táblaértékű függvény létrehozása

Az alábbi példa egy sorbeli táblázatértékű függvényt hoz létre, amely kulcsfontosságú információkat ad vissza a modulokról, paraméter objectType szerint szűrve. Tartalmaz egy alapértelmezett értéket, amely minden modult visszaad, amikor a paraméterrel rendelkező függvényt DEFAULT hívod. Ez a példa a Metadata-ban említett rendszerkatalógus nézeteket használja.

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

A függvényt az összes view (V) objektum visszaadására hívhatod a következőket:

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

Megjegyzés:

Az inline táblázat-érték függvények elérhetők szerver nélküli SQL poolokban, de előnézetben a dedikált SQL poolokban.

C. Beágyazott táblaértékű függvény eredményeinek kombinálása

Ez az egyszerű példa a korábban létrehozott inline TVF-et használja arra, hogyan lehet az eredményeit más táblázatokkal kombinálni a használatával CROSS APPLY. Ebben a példában mindkettőből sys.objects kiválasztod az összes oszlopot, valamint az ModulesByType összes sor, amely egyezik az type oszlopban. További információért APPLYa használatról lásd a FROM klaud plusz A JOIN, APPLY, PIVOT (Transact-SQL).

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

Megjegyzés:

Az inline táblázat-érték függvények elérhetők szerver nélküli SQL poolokban, de előnézetben a dedikált SQL poolokban.

Következő lépés

Felhasználó által definiált függvények (adatbázismotor) létrehozása