CREATE FUNCTION

Van toepassing op:SQL Analytics-eindpunt in Microsoft Fabric en Warehouse in Microsoft Fabric

CREATE FUNCTION maakt inline tabel-waardige functies en scalaire functies.

Een door de gebruiker gedefinieerde functie is een Transact-SQL routine die parameters accepteert, een actie uitvoert zoals een complexe berekening, en het resultaat van die actie als waarde teruggeeft. Scalaire functies retourneren een scalaire waarde, zoals een getal of tekenreeks. Door de gebruiker gedefinieerde functies met tabelwaarden (TVF's) retourneren een tabel.

Gebruik CREATE FUNCTION om een herbruikbare T-SQL-routine te maken die je op deze manieren kunt gebruiken:

• In Transact-SQL verklaringen zoals SELECT
• In Transact-SQL instructies voor gegevensmanipulatie (DML), zoals UPDATE, INSERTen DELETE
• In toepassingen die de functie aanroepen
• In de definitie van een andere door de gebruiker gedefinieerde functie
• Een opgeslagen procedure vervangen

Je kunt specificeren CREATE OR ALTER FUNCTION dat je een nieuwe functie wilt aanmaken als er geen bestaat onder die naam, of een bestaande functie wijzigen, in één enkele instructie.

Transact-SQL syntaxis-conventies

Syntaxis

Syntaxis van scalaire functie

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

Syntaxis van inline-tabelwaardefunctie

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

Argumenten

schema_name

De naam van het schema waartoe de door de gebruiker gedefinieerde functie behoort.

function_name

De naam van de door de gebruiker gedefinieerde functie. Functienamen moeten voldoen aan de regels voor identificaties en uniek zijn binnen de database en het schema daarvan.

@ parameter_name

Een parameter in de door de gebruiker gedefinieerde functie. Je kunt één of meer parameters declareren.

Een functie kan tot 2.100 parameters hebben. Wanneer een gebruiker of applicatie een functie aanroept, moet de waarde van elke gedeclareerde parameter worden opgegeven, tenzij er een standaard voor de parameter is gedefinieerd.

Geef een parameternaam op met behulp van een at-teken (@) als het eerste teken. De parameternaam moet voldoen aan de regels voor identifiers. Parameters zijn lokaal aan de functie; Je kunt dezelfde parameternamen in andere functies gebruiken. Parameters kunnen alleen constanten vervangen; ze kunnen niet worden gebruikt in plaats van tabelnamen, kolomnamen of de namen van andere databaseobjecten.

parameter_data_type

Het gegevenstype parameter. Voor Transact-SQL functies zijn alle ondersteunde scalaire gegevenstypen toegestaan.

[ = standaard ]

Een standaardwaarde voor de parameter. Als je een standaardwaarde definieert, kun je de functie uitvoeren zonder een waarde voor die parameter op te geven.

Wanneer een parameter van de functie een standaardwaarde heeft, moet je het trefwoord DEFAULT opgeven bij het aanroepen van de functie om de standaardwaarde op te halen. Dit gedrag verschilt van het gebruik van parameters met standaardwaarden in opgeslagen procedures, waarbij het weglaten van de parameter ook de standaardwaarde impliceert.

return_data_type

De retourwaarde van een scalaire, door de gebruiker gedefinieerde functie.

Voor functies in Fabric Data Warehouse zijn alle gegevenstypen toegestaan, met uitzondering vande tijdstempel van /. Niet-scalaire types zoals de tabel zijn niet toegestaan.

function_body

Een reeks Transact-SQL instructies.

In scalaire functies is function_body een reeks Transact-SQL instructies die samen een scalaire waarde evalueren, waaronder:

• Expressie met één instructie
• Expressies met meerdere instructies (IF/THEN/ELSE en BEGIN/END blokken)
• Lokale variabelen
• Aanroepen naar ingebouwde SQL-functies die beschikbaar zijn
• Aanroepen naar andere UDF's
• SELECT instructies en verwijzingen naar tabellen, weergaven en inline-tabelwaardefuncties
• Control flow-statements (WHILE lussen, RETURNS)

scalar_expression

Hiermee geeft u de scalaire waarde op die de scalaire functie retourneert.

select_stmt

De enkele SELECT instructie waarmee de retourwaarde van een inline-tabelwaardefunctie wordt gedefinieerd. Voor een inline tabel-waarde functie is er geen functielichaam; De tabel is de resultaatverzameling van één enkele SELECT uitspraak.

TABLE

Hiermee geeft u aan dat de retourwaarde van de tabelwaardige functie (TVF) een tabel is. Je kunt alleen constanten en @local_variables doorgeven aan TVF's.

In inline TVF's (preview) definieer je de TABLE retourwaarde via één enkele SELECT instructie. Inline-functies hebben geen gekoppelde retourvariabelen.

<function_option>

In Fabric Data Warehouse worden de INLINE, ENCRYPTION, en EXECUTE AS trefwoorden niet ondersteund.

De ondersteunde functieopties zijn onder andere:

SCHEMABINDING

Hiermee geeft u aan dat de functie is gebonden aan de databaseobjecten waarnaar wordt verwezen. Wanneer je specificeert SCHEMABINDING, kun je de onderliggende objecten (zoals bijvoorbeeld een weergave of een tabel) niet aanpassen op een manier die de functiedefinitie beïnvloedt. Je moet eerst de functiedefinitie aanpassen of verwijderen om afhankelijkheden van het object dat je wilt aanpassen te verwijderen.

De binding van de functie aan de objecten waarnaar wordt verwezen, wordt alleen verwijderd wanneer een van de volgende acties plaatsvindt:

• Je laat de functie vallen.

• Je doet ALTER de functie-statement en verwijdert de SCHEMABINDING optie.

Je kunt een functie alleen schema-binden als de volgende voorwaarden waar zijn:

• Alle door de gebruiker gedefinieerde functies waar de functie naar verwijst, zijn ook schema-gebonden.

• De functie verwijst naar objecten door gebruik te maken van een tweedelige naam.

• Binnen de body van UDF's kun je alleen naar ingebouwde functies en andere UDF's in dezelfde database verwijzen.

• De gebruiker die de CREATE FUNCTION instructie uitvoert heeft REFERENCES-rechten op de databaseobjecten waar de functie naar verwijst.

Als u SCHEMABINDING wilt verwijderen, gebruikt u ALTER.

RETOURNEERT NULL OP NULL-INVOER | AANGEROEPEN OP NULL-INVOER

Hiermee geeft u het OnNULLCall kenmerk van een scalaire-waardefunctie. Als je dit attribuut niet specificeert, CALLED ON NULL INPUT wordt standaard impliciet, en voert het functielichaam uit, zelfs als NULL het als argument wordt doorgegeven.

Beste praktijken

• Als je geen door de gebruiker gedefinieerde functie met schemabinding maakt, kunnen wijzigingen aan onderliggende objecten de definitie van de functie beïnvloeden en onverwachte resultaten veroorzaken wanneer je de functie aanroept. Wanneer je aangeeft WITH SCHEMABINDING wanneer je de functie aanmaakt, zorg je ervoor dat latere wijzigingen aan onderliggende objecten het gedrag van de functie niet kunnen veranderen of breken.

• Schrijf je door de gebruiker gedefinieerde functies zo dat ze inlineable zijn. Zie Scalar UDF inlining voor meer informatie.

Interoperabiliteit

Door de gebruiker gedefinieerde functies inlinetabelwaarden

Een inline tabel-waarde functie accepteert slechts één enkele SELECT stelling.

Scalaire door de gebruiker gedefinieerde functies

• De volgende instructies zijn geldig in een scalaire functie:

  • Toewijzingsopdrachten
  • Control-of-Flow-instructies behalve TRY...CATCH instructies
  • DECLARE instructies voor het definiëren van lokale gegevensvariabelen

• De volgende ingebouwde functies worden niet ondersteund in de hoofdtekst van een scalaire functie:

  • NEWID()
  • RAND()
  • Configuratiefuncties
  • DATABASEPROPERTYEX
  • OBJECTPROPERTYEX
  • SERVERPROPERTY
  • VOLGENDE WAARDE VOOR
  • SORTERINGSPROPERTY
  • HAS_PERMS_BY_NAME
  • HAS_DBACCESS

• Scalaire UDF's kunnen niet worden gebruikt in een SELECT ... FROM query in een gebruikerstabel wanneer:

  • Het UDF-lichaam bevat een aanroep naar een niet-deterministische ingebouwde functie (zoals GETDATE()), zie Deterministische en niet-deterministische functies.
  • Het UDF-lichaam bevat BREAK een CONTINUE statement.
  • Er is een recursieve scalaire UDF-aanroep.

• Een scalair UDF kan niet in alle queryvormen worden gebruikt, zoals CTE's en GROUP BY, als:

  • De scalair UDF bevat al deze datatypen als invoerparameter, lokale variabele of retourdatatype: varchar(max),nvarchar(max),varbinary(max), varbinary(max),binary(max).
  • Het scalair UDF-lichaam bevat aanroepen naar andere scalaire UDF's.
  • Het scalaire UDF-lichaam bevat verwijzingen naar tabellen/views/iTVF.

Zie Scalar UDF inlining requirements voor meer informatie.

• Als een scalair UDF een van de volgende elementen bevat, kan een gebruikersquery falen als er meer dan 10 UDF-aanroepen in één query worden gedaan. In sommige edge-gevallen voorkomt de complexiteit van de gebruikersquery en de UDF-hoofdtekst het inlijnen, in welk geval de scalaire UDF niet inline is en de gebruikersquery mislukt.

  • De scalair UDF bevat al deze datatypen als invoerparameter, lokale variabele of retourdatatype: varchar(max),nvarchar(max),varbinary(max), varbinary(max),binary(max).
  • Het scalair UDF-lichaam bevat aanroepen naar andere scalaire UDF's.
  • Het scalaire UDF-lichaam bevat verwijzingen naar tabellen/views/iTVF.

• Wanneer een scalaire UDF wordt gebruikt in een niet-ondersteund scenario, ziet u een foutbericht 'Scalar UDF execution is currently unavailable in this context.'

Beperkingen

Je kunt geen door de gebruiker gedefinieerde functies gebruiken om acties uit te voeren die de status van de database wijzigen.

Je kunt door de gebruiker gedefinieerde functies nesten. Dat wil gezegd, één door de gebruiker gedefinieerde functie kan een andere aanroepen. Het genestingsniveau neemt toe wanneer de aangeroepen functie begint met uitvoeren, en neemt af wanneer de aangeroepen functie is uitgevoerd. In Fabric Data Warehouse kun je door gebruikers gedefinieerde functies tot vier niveaus nesten wanneer een UDF-lichaam verwijst naar een tabel, view of inline tabel-waardige functie, of tot 32 niveaus anders. Als je de maximale niveaus van genesing overschrijdt, faalt de aanroepende functieketen.

Metagegevens

Deze sectie bevat de systeemcatalogusweergaven die u kunt gebruiken om metagegevens over door de gebruiker gedefinieerde functies te retourneren.

• sys.sql_modules: Toont de definitie van Transact-SQL door de gebruiker gedefinieerde functies, evenals informatie over inlineability. Voorbeeld:

   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: geeft informatie weer over de parameters die zijn gedefinieerd in door de gebruiker gedefinieerde functies.

• sys.sql_expression_afhankelijkheden: geeft de onderliggende objecten weer waarnaar wordt verwezen door een functie.

Machtigingen

Leden van de rollen Fabric-werkruimteBeheerder, Lid en Inzender kunnen functies maken.

Scalaire UDF-inlining

Microsoft Fabric Data Warehouse gebruikt verschillende inline-technieken om door de gebruiker gedefinieerde code op een gedistribueerde manier te compileren en uit te voeren.

Inlining van scalar UDF is standaard ingeschakeld.

Sommige T-SQL-syntaxis maakt een scalaire UDF niet-inlineable. Functies die bijvoorbeeld een combinatie van een WHILE lus en een referentie van een tabel binnen het UDF-lichaam bevatten, kunnen niet worden inlined. Zie Scalar UDF inlining requirements voor meer informatie.

Controleren of een scalaire UDF inline kan zijn

De sys.sql_modules catalogusweergave bevat de kolom is_inlineable, die aangeeft of een UDF inlineable is. De is_inlineable eigenschap komt voort uit het controleren van de syntaxis binnen de UDF-definitie. De scalar UDF is niet geïnlineerd vóór de compilatietijd.

De inline_eligibility_mask eigenschap legt uit welk type inlining van toepassing is op een UDF.

• Een waarde van 0 betekent dat de UDF niet inline-baar is.
• Een waarde van 1 geeft aan dat de UDF in aanmerking komt voor scalar UDF-inlinering.
• Een waarde van 2 betekent dat de UDF in aanmerking komt voor inlining via expression-blok.
• Een waarde van 3 betekent dat UDF in aanmerking komt voor beide inline-technieken.

Als een scalair UDF inlineerbaar is, garandeert dat niet dat deze altijd inline is wanneer de query wordt gecompileerd.

Fabric Data Warehouse bepaalt (per query) welke inline-techniek wordt toegepast.

Gebruik de volgende voorbeeldquery om te controleren of een scalaire UDF inlineable is:

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

Als een scalaire functie niet inlineerbaar is in sys.sql_modules.is_inlineable, kun je de query bijvoorbeeld nog steeds als een zelfstandige aanroep uitvoeren om een variabele in te stellen. Maar de scalairfunctie kan geen deel uitmaken van een SELECT ... FROM query in een gebruikerstabel. Voorbeeld:

CREATE FUNCTION [dbo].[custom_SYSUTCDATETIME]()
  RETURNS datetime2(6)
  AS
  BEGIN
   RETURN SYSUTCDATETIME();
  END

De voorbeeld-scalaire dbo.custom_SYSUTCDATETIME , door de gebruiker gedefinieerde functie is niet inlineable vanwege het gebruik van een niet-determinante systeemfunctie, SYSUTCDATETIME(). Het faalt wanneer het wordt gebruikt in een SELECT ... FROM query op een gebruikerstabel, maar slaagt als een zelfstandige aanroep. Voorbeeld:

DECLARE @utcdate datetime2(7);
SET @utcdate = dbo.custom_SYSUTCDATETIME();
SELECT @utcdate as 'utc_date';

Voorbeelden

Eén. Een functie met tabelwaarde inline maken

Het volgende voorbeeld creëert een inline tabel-waarde functie die belangrijke informatie over modules teruggeeft, gefilterd op de objectType parameter. Het bevat een standaardwaarde om alle modules terug te geven wanneer je de functie met de DEFAULT parameter aanroept. Dit voorbeeld gebruikt enkele van de systeemcatalogusweergaven die in Metadata worden genoemd.

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

Roep de functie aan om alle inline tabel-waarde functies terug te geven (IF):

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

Of zoek alle scalaire functies (FN):

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

B. Resultaten van een inline tabelwaardefunctie combineren

Dit eenvoudige voorbeeld gebruikt de eerder gemaakte inline TVF om te laten zien hoe je de resultaten kunt combineren met andere tabellen door gebruik te maken van CROSS APPLY. Hier selecteer je alle kolommen uit beide sys.objects en de resultaten van ModulesByType voor alle rijen die overeenkomen in de type kolom. Voor meer informatie over het gebruik van APPLY, zie FROM-clausule plus JOIN, APPLY, PIVOT (Transact-SQL).

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

C. Een scalaire UDF-functie maken

In het volgende voorbeeld wordt een inlineerbare scalaire UDF gemaakt waarmee een invoertekst wordt gemaskeerd.

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

U kunt de functie als volgt aanroepen:

DECLARE @input varchar(100) = '123456789'

SELECT dbo.cleanInput (@input) AS function_output;

Meer voorbeelden van hoe u scalaire UDF's in Fabric Data Warehouse kunt gebruiken:

In een SELECT instructie:

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

In een WHERE component:

 SELECT t.id, t.name, dbo.cleanInput(t.name) AS function_output
FROM dbo.MyTable AS t
WHERE dbo.cleanInput(t.name)='myvalue'

In een JOIN component:

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

In een ORDER BY component:

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

In DML-instructies (Data Manipulat Language), zoals INSERT, UPDATEof DELETE:

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) ='myvalue';

Verwante inhoud

• Scalaire UDF-inlining
• Migratieassistent infrastructuurdatawarehouse

van toepassing op:Azure Synapse AnalyticsAnalytics Platform System (PDW)

Hiermee maakt u een door de gebruiker gedefinieerde functie (UDF) in Azure Synapse Analytics of Analytics Platform System (PDW). Een door de gebruiker gedefinieerde functie is een Transact-SQL routine die parameters accepteert, een actie uitvoert, zoals een complexe berekening, en het resultaat van die actie als een waarde retourneert. Door de gebruiker gedefinieerde functies met tabelwaarden (TVF's) retourneren een tabelgegevenstype.

• In Analytics Platform System (PDW) moet de retourwaarde een scalaire waarde (één) zijn.

• In Azure Synapse Analytics CREATE FUNCTION kan een tabel worden geretourneerd met behulp van de syntaxis voor inline-tabelwaardefuncties (preview) of kan er één waarde worden geretourneerd met behulp van de syntaxis voor scalaire functies.

• In serverloze SQL-pools in Azure Synapse Analytics kunt u inline-tabelwaardefuncties maken, CREATE FUNCTION maar niet scalaire functies.

  Gebruik deze verklaring om een herbruikbare routine te creëren die je op deze manieren kunt gebruiken:

• In Transact-SQL verklaringen zoals SELECT

• In toepassingen die de functie aanroepen

• In de definitie van een andere door de gebruiker gedefinieerde functie

• Een CHECK-beperking voor een kolom definiëren

• Een opgeslagen procedure vervangen

• Een inlinefunctie gebruiken als filterpredicaat voor een beveiligingsbeleid

Transact-SQL syntaxis-conventies

Syntaxis

Syntaxis van scalaire functie

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

Syntaxis van inline-tabelwaardefunctie

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

Argumenten

schema_name

De naam van het schema waartoe de door de gebruiker gedefinieerde functie behoort.

function_name

De naam van de door de gebruiker gedefinieerde functie. Functienamen moeten voldoen aan de regels voor identificaties en uniek zijn binnen de database en het schema daarvan.

@ parameter_name

Een parameter in de door de gebruiker gedefinieerde functie. Je kunt één of meer parameters declareren.

Een functie kan tot 2.100 parameters hebben. Wanneer een gebruiker of applicatie een functie aanroept, moet de waarde van elke gedeclareerde parameter worden opgegeven, tenzij er een standaard voor de parameter is gedefinieerd.

Geef een parameternaam op met behulp van een at-teken (@) als het eerste teken. De parameternaam moet voldoen aan de regels voor identifiers. Parameters zijn lokaal aan de functie; Je kunt dezelfde parameternamen in andere functies gebruiken. Parameters kunnen alleen constanten vervangen; ze kunnen niet worden gebruikt in plaats van tabelnamen, kolomnamen of de namen van andere databaseobjecten.

parameter_data_type

Het gegevenstype parameter. Voor Transact-SQL functies zijn alle scalaire gegevenstypen die worden ondersteund in Azure Synapse Analytics toegestaan. Het tijdstempel (rijversie) datatype wordt niet ondersteund.

[ = standaard ]

Een standaardwaarde voor de parameter. Als je een standaardwaarde definieert, kun je de functie uitvoeren zonder een waarde voor die parameter op te geven.

Wanneer een parameter van de functie een standaardwaarde heeft, moet je het trefwoord DEFAULT opgeven bij het aanroepen van de functie om de standaardwaarde op te halen. Dit gedrag verschilt van het gebruik van parameters met standaardwaarden in opgeslagen procedures, waarbij het weglaten van de parameter ook de standaardwaarde impliceert.

return_data_type

De retourwaarde van een scalaire, door de gebruiker gedefinieerde functie. Voor Transact-SQL functies zijn alle scalaire gegevenstypen die worden ondersteund in Azure Synapse Analytics toegestaan. Het typerowversie-timestamp/ data wordt niet ondersteund. De cursor- en tabel niet-scalaire types zijn niet toegestaan.

function_body

Reeks Transact-SQL instructies. De function_body kan geen SELECT statement bevatten en geen databasegegevens verwijzen. De function_body kan geen tabellen of weergaven refereren. Het functielichaam kan andere deterministische functies aanroepen, maar kan niet-deterministische functies niet aanroepen.

In scalaire functies is function_body een reeks Transact-SQL instructies die samen tot een scalaire waarde leiden.

scalar_expression

Hiermee geeft u de scalaire waarde op die de scalaire functie retourneert.

select_stmt

De enkele SELECT instructie waarmee de retourwaarde van een inline-tabelwaardefunctie wordt gedefinieerd. Voor een inline tabel-waarde functie is er geen functielichaam; De tabel is de resultaatverzameling van één enkele SELECT uitspraak.

TABLE

Hiermee geeft u aan dat de retourwaarde van de tabelwaardige functie (TVF) een tabel is. Je kunt alleen constanten en @local_variables doorgeven aan TVF's.

In inline TVF's (preview) definieer je de TABLE retourwaarde via één enkele SELECT instructie. Inline-functies hebben geen gekoppelde retourvariabelen.

<function_option>

Geeft aan dat de functie een of meer van de volgende opties heeft.

SCHEMABINDING

Hiermee geeft u aan dat de functie is gebonden aan de databaseobjecten waarnaar wordt verwezen. Wanneer je specificeert SCHEMABINDING, kun je de onderliggende objecten (zoals bijvoorbeeld een weergave of een tabel) niet aanpassen op een manier die de functiedefinitie beïnvloedt. Je moet eerst de functiedefinitie aanpassen of verwijderen om afhankelijkheden van het object dat je wilt aanpassen te verwijderen.

De binding van de functie aan de objecten waarnaar wordt verwezen, wordt alleen verwijderd wanneer een van de volgende acties plaatsvindt:

• Je laat de functie vallen.

• Je doet ALTER de functie-statement en verwijdert de SCHEMABINDING optie.

Je kunt een functie alleen schema-binden als de volgende voorwaarden waar zijn:

• Alle door de gebruiker gedefinieerde functies waar de functie naar verwijst, zijn ook schema-gebonden.

• De functiereferenties gebruiken namen die één of twee delen bevatten.

• Binnen de body van UDF's kun je alleen naar ingebouwde functies en andere UDF's in dezelfde database verwijzen.

• De gebruiker die de CREATE FUNCTION instructie uitvoert heeft REFERENCES-rechten op de databaseobjecten waar de functie naar verwijst.

Als u SCHEMABINDING wilt verwijderen, gebruikt u ALTER.

RETOURNEERT NULL OP NULL-INVOER | AANGEROEPEN OP NULL-INVOER

Hiermee geeft u het OnNULLCall kenmerk van een scalaire-waardefunctie. Als je dit attribuut niet specificeert, CALLED ON NULL INPUT wordt standaard impliciet, en voert het functielichaam uit, zelfs als NULL het als argument wordt doorgegeven.

Beste praktijken

Als je geen door de gebruiker gedefinieerde functie maakt met de SCHEMABINDING-clausule, kunnen wijzigingen in onderliggende objecten de definitie van de functie beïnvloeden en onverwachte resultaten veroorzaken wanneer je deze aanroept. Specificeer de WITH SCHEMABINDING clausule wanneer je de functie maakt. Deze clausule zorgt ervoor dat je de objecten die in de functiedefinitie worden genoemd niet kunt wijzigen, tenzij je ook de functie aanpast.

Interoperabiliteit

De volgende instructies zijn geldig in een scalaire functie:

• Opdracht verklaringen.

• Control-of-Flow statements, behalve TRY... CATCH-verklaringen.

• DECLARE-statements die lokale datavariabelen definiëren.

In een inline tabel-gewaardeerde functie (preview) kun je slechts één select-instructie gebruiken.

Beperkingen

Je kunt geen door de gebruiker gedefinieerde functies gebruiken om acties uit te voeren die de status van de database wijzigen.

Je kunt door de gebruiker gedefinieerde functies nesten. Een door de gebruiker gedefinieerde functie kan een andere aanroepen. Het genestingsniveau neemt toe wanneer de aangeroepen functie begint met uitvoeren, en neemt af wanneer de aangeroepen functie is uitgevoerd. Als je de maximale niveaus van genesing overschrijdt, faalt de hele aanroepende functieketen.

Je kunt geen objecten, inclusief functies, aanmaken in de master database van je serverless SQL-pool in Azure Synapse Analytics.

Metagegevens

Deze sectie bevat de systeemcatalogusweergaven die u kunt gebruiken om metagegevens over door de gebruiker gedefinieerde functies te retourneren.

• sys.sql_modules: geeft de definitie weer van Transact-SQL door de gebruiker gedefinieerde functies. Voorbeeld:

  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: geeft informatie weer over de parameters die zijn gedefinieerd in door de gebruiker gedefinieerde functies.

• sys.sql_expression_afhankelijkheden: geeft de onderliggende objecten weer waarnaar wordt verwezen door een functie.

Machtigingen

Vereist CREATE FUNCTION toestemming in de database en ALTER-toestemming voor het schema waarin de functie wordt gemaakt.

Voorbeelden

Eén. Een door de gebruiker gedefinieerde scalaire functie gebruiken om een gegevenstype te wijzigen

Deze eenvoudige functie neemt een int-datatype als invoer en geeft een decimaal(10,2) datatype terug als uitvoer.

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

B. Een functie met tabelwaarde inline maken

Het volgende voorbeeld creëert een inline tabel-waarde functie die belangrijke informatie over modules teruggeeft, gefilterd op de objectType parameter. Het bevat een standaardwaarde om alle modules terug te geven wanneer je de functie met de DEFAULT parameter aanroept. Dit voorbeeld gebruikt enkele van de systeemcatalogusweergaven die in Metadata worden genoemd.

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

Je kunt de functie aanroepen om alle view (V) objecten terug te geven met:

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

C. Resultaten van een inline tabelwaardefunctie combineren

Dit eenvoudige voorbeeld gebruikt de eerder gemaakte inline TVF om te laten zien hoe je de resultaten kunt combineren met andere tabellen door gebruik te maken van CROSS APPLY. In dit voorbeeld selecteer je alle kolommen uit beide sys.objects en de resultaten van ModulesByType voor alle rijen die overeenkomen in de type kolom. Voor meer informatie over het gebruik van APPLY, zie FROM-clausule plus JOIN, APPLY, PIVOT (Transact-SQL).

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

Volgende stap