Delen via

MAAK FUNCTIE AAN

van toepassing op:SQL Analytics-eindpunt en -warehouse in Microsoft Fabric-

CREATE FUNCTION kan inline-tabelwaardefuncties en scalaire functies maken.

Opmerking

Scalaire UDF's zijn een preview-functie in Fabric Data Warehouse.

Belangrijk

In Fabric Data Warehouse moeten scalaire UDF's inlineable zijn voor gebruik met SELECT ... FROM query's in gebruikerstabellen, maar u kunt nog steeds functies maken die niet inlineable zijn. Scalaire UDF's die niet inlineable werken in een beperkt aantal scenario's. U kunt controleren of een UDF inline kan worden geplaatst.

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. 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 dit om een herbruikbare T-SQL-routine te maken die op deze manieren kan worden gebruikt:

  • 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

Aanbeveling

U kunt opgeven CREATE OR ALTER FUNCTION dat u een nieuwe functie maakt als deze niet bestaat op basis van die naam of een bestaande functie wijzigt in één 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 id's en moeten uniek zijn binnen de database en het bijbehorende schema.

Opmerking

Haakjes zijn vereist na de functienaam, zelfs als er geen parameter is opgegeven.

@ parameter_name

Een parameter in de door de gebruiker gedefinieerde functie. Een of meer parameters kunnen worden gedeclareerd.

Een functie kan maximaal 2.100 parameters hebben. De waarde van elke gedeclareerde parameter moet door de gebruiker worden opgegeven wanneer de functie wordt uitgevoerd, tenzij 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 voor de functie; Dezelfde parameternamen kunnen in andere functies worden gebruikt. Parameters kunnen alleen plaats vinden van constanten; ze kunnen niet worden gebruikt in plaats van tabelnamen, kolomnamen of de namen van andere databaseobjecten.

Opmerking

ANSI_WARNINGS wordt niet gehonoreerd wanneer u parameters doorgeeft in een opgeslagen procedure, door de gebruiker gedefinieerde functie of wanneer u variabelen declareert en instelt in een batch-instructie. Als een variabele bijvoorbeeld is gedefinieerd als char(3) en vervolgens is ingesteld op een waarde die groter is dan drie tekens, worden de gegevens afgekapt tot de gedefinieerde grootte en slaagt de instructie INSERT of UPDATE.

parameter_data_type

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

[ = standaard ]

Een standaardwaarde voor de parameter. Als er een standaardwaarde is gedefinieerd, kan de functie worden uitgevoerd zonder een waarde voor die parameter op te geven.

Wanneer een parameter van de functie een standaardwaarde heeft, moet het trefwoord DEFAULT worden opgegeven wanneer de functie wordt aangeroepen 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 rowversion/. Niet-schaaltypen, zoals 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

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 tabelwaardefunctie is er geen hoofdtekst van de functie; de tabel is de resultatenset van één SELECT instructie.

TAFEL

Hiermee geeft u aan dat de retourwaarde van de tabelwaardige functie (TVF) een tabel is. Alleen constanten en @local_variables kunnen worden doorgegeven aan TVF's.

In inline-TVF's (preview) wordt de retourwaarde TABLE gedefinieerd via één SELECT instructie. Inlinefuncties hebben geen gekoppelde retourvariabelen.

<function_option>

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

De ondersteunde functieopties zijn:

SCHEMABINDING

Hiermee geeft u aan dat de functie is gebonden aan de databaseobjecten waarnaar wordt verwezen. Wanneer SCHEMABINDING is opgegeven, kunnen de basisobjecten niet worden gewijzigd op een manier die van invloed is op de functiedefinitie. De functiedefinitie zelf moet eerst worden gewijzigd of verwijderd om afhankelijkheden van het te wijzigen object te verwijderen.

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

  • De functie komt te vervallen.

  • De functie wordt gewijzigd met behulp van de instructie ALTER met de optie SCHEMABINDING niet opgegeven.

Een functie kan alleen schemagebonden zijn als aan de volgende voorwaarden is voldaan:

  • Door de gebruiker gedefinieerde functies waarnaar wordt verwezen door de functie zijn ook schemagebonden.

  • Naar de objecten waarnaar de functie verwijst, wordt verwezen met behulp van een tweedelige naam.

  • Alleen ingebouwde functies en andere UDF's in dezelfde database kunnen worden verwezen in de hoofdtekst van UDF's.

  • De gebruiker die de CREATE FUNCTION instructie heeft uitgevoerd, heeft de machtiging VERWIJZINGEN voor de databaseobjecten waarnaar de functie 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 dit niet is opgegeven, CALLED ON NULL INPUT wordt deze standaard geïmpliceerd en wordt de hoofdtekst van de functie uitgevoerd, zelfs als NULL deze wordt doorgegeven als argument.

Beste praktijken

  • Als een door de gebruiker gedefinieerde functie niet met schemabinding wordt gemaakt, kunnen wijzigingen die worden aangebracht in onderliggende objecten de definitie van de functie beïnvloeden en onverwachte resultaten opleveren wanneer deze wordt aangeroepen. Het wordt aanbevolen om de WITH SCHEMABINDING component op te geven wanneer u de functie maakt. Dit zorgt ervoor dat de objecten waarnaar wordt verwezen in de functiedefinitie niet kunnen worden gewijzigd, tenzij de functie ook wordt gewijzigd.

  • Schrijf uw door de gebruiker gedefinieerde functies om inlineable te zijn. Zie Scalar UDF inlining voor meer informatie.

Interoperabiliteit

Door de gebruiker gedefinieerde functies inlinetabelwaarden

In een inline tabelwaardefunctie is slechts één select-instructie toegestaan.

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:

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

  • Scalaire UDF's kunnen niet worden gebruikt in een query wanneer:

    • UDF wordt rechtstreeks aangeroepen in een GROUP BY component.
    • UDF wordt rechtstreeks aangeroepen in een ORDER BY component.
    • aanroepende query heeft een algemene tabelexpressie (CTE).

  • Recursieve scalaire UDF's worden niet ondersteund.

  • Een gebruikersquery kan mislukken als er meer dan 10 UDF-aanroepen worden uitgevoerd in één query.

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

  • 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

Opmerking

Tijdens de huidige preview kunnen beperkingen worden gewijzigd.

Door de gebruiker gedefinieerde functies kunnen niet worden gebruikt om acties uit te voeren die de databasestatus wijzigen.

Door de gebruiker gedefinieerde functies kunnen worden genest; Dat wil gezegd, één door de gebruiker gedefinieerde functie kan een andere aanroepen. Het nestniveau wordt verhoogd wanneer de aangeroepen functie wordt gestart en afneemt wanneer de aangeroepen functie de uitvoering voltooit. Door de gebruiker gedefinieerde functies in Fabric Data Warehouse kunnen maximaal vier niveaus worden genest wanneer een UDF-hoofdtekst verwijst naar een tabel-/weergave-/in-line tabelwaardefunctie, of maximaal 32 niveaus. Als u de maximumniveaus van nesten overschrijdt, mislukt 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: 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

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

Scalaire UDF-inlining

Microsoft Fabric Data Warehouse maakt gebruik van scalaire UDF-inlining om door de gebruiker gedefinieerde code op een gedistribueerde manier te compileren en uit te voeren. Scalaire UDF-inlining is standaard ingeschakeld.

Hoewel scalaire UDF-inlining een techniek voor prestatieoptimalisatie is die voor het eerst is geïntroduceerd in Microsoft SQL Server 2019 (15.0), wordt in Fabric Data Warehouse de ondersteunde set scenario's bepaald. In Fabric Data Warehouse worden scalaire UDF's automatisch omgezet in scalaire expressies of scalaire subquery's die worden vervangen door de aanroepende query in plaats van de UDF-operator.

Sommige T-SQL-syntaxis maakt een scalaire UDF niet-inlineable. Functies die een WHILE lus, meerdere RETURN instructies of een aanroep van een ingebouwde SQL-functie (zoals GETUTCDATE() of GETDATE()) bevatten, kunnen niet inline worden geplaatst. 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 is afgeleid van het controleren op syntaxis in de UDF-definitie. De scalaire UDF is niet inlined voordat de tijd wordt gecompileerd. Een waarde waarmee 1 wordt aangegeven dat de UDF inlineable is, terwijl een waarde 0 aangeeft dat deze niet inlineable is. Als een scalaire UDF inlineable is, garandeert dit niet dat deze altijd inline is wanneer de query wordt gecompileerd.

Fabric Data Warehouse bepaalt (per query) of een UDF inline moet worden geplaatst, afhankelijk van de algehele complexiteit van de query.

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 inlineable sys.sql_modules.is_inlineableis, kunt u de query nog steeds uitvoeren als een zelfstandige aanroep, bijvoorbeeld om een variabele in te stellen. Maar de scalaire functie 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 scalaire door de gebruiker gedefinieerde voorbeeldfunctie dbo.custom_SYSUTCDATETIME is niet inlineable vanwege het gebruik van een niet-determinant systeemfunctie, SYSUTCDATETIME(). Dit mislukt wanneer deze wordt gebruikt in een SELECT ... FROM query in een gebruikerstabel, maar slaagt als zelfstandige aanroep, bijvoorbeeld:

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

Voorbeelden

Eén. Een functie met tabelwaarde inline maken

In het volgende voorbeeld wordt een inline-tabelwaardefunctie gemaakt om belangrijke informatie over modules te retourneren, waarbij de objectType parameter wordt gefilterd. Het bevat een standaardwaarde om alle modules te retourneren wanneer de functie wordt aangeroepen met de DEFAULT parameter. In dit voorbeeld worden enkele van de systeemcatalogusweergaven gebruikt die worden vermeld in Metagegevens.

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

De functie kan vervolgens worden aangeroepen om alle inline tabelwaardefuncties (IF) te retourneren met:

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

In dit eenvoudige voorbeeld wordt de eerder gemaakte inline TVF gebruikt om te laten zien hoe de resultaten kunnen worden gecombineerd met andere tabellen met kruislingse toepassing. Hier selecteren we alle kolommen uit beide sys.objects en de resultaten van ModulesByType alle rijen die overeenkomen met de type kolom. Zie FROM-component plus JOIN, APPLY, PIVOT (Transact-SQL) voor meer informatie over het gebruik van apply.

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

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 maken die op de volgende manieren kan worden gebruikt:

  • 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

Aanbeveling

Zie de versie van CREATE FUNCTION voor Microsoft Fabric Data Warehouse voor syntaxis in Fabric Data Warehouse.

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 id's en moeten uniek zijn binnen de database en het bijbehorende schema.

Opmerking

Haakjes zijn vereist na de functienaam, zelfs als er geen parameter is opgegeven.

@ parameter_name

Een parameter in de door de gebruiker gedefinieerde functie. Een of meer parameters kunnen worden gedeclareerd.

Een functie kan maximaal 2.100 parameters hebben. De waarde van elke gedeclareerde parameter moet door de gebruiker worden opgegeven wanneer de functie wordt uitgevoerd, tenzij 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 voor de functie; Dezelfde parameternamen kunnen in andere functies worden gebruikt. Parameters kunnen alleen plaats vinden van constanten; ze kunnen niet worden gebruikt in plaats van tabelnamen, kolomnamen of de namen van andere databaseobjecten.

Opmerking

ANSI_WARNINGS wordt niet gehonoreerd wanneer u parameters doorgeeft in een opgeslagen procedure, door de gebruiker gedefinieerde functie of wanneer u variabelen declareert en instelt in een batch-instructie. Als een variabele bijvoorbeeld is gedefinieerd als char(3) en vervolgens is ingesteld op een waarde die groter is dan drie tekens, worden de gegevens afgekapt tot de gedefinieerde grootte en slaagt de instructie INSERT of UPDATE.

parameter_data_type

Het gegevenstype parameter. Voor Transact-SQL functies zijn alle scalaire gegevenstypen die worden ondersteund in Azure Synapse Analytics toegestaan. Het gegevenstype timestamp (rowversion) is geen ondersteund type.

[ = standaard ]

Een standaardwaarde voor de parameter. Als er een standaardwaarde is gedefinieerd, kan de functie worden uitgevoerd zonder een waarde voor die parameter op te geven.

Wanneer een parameter van de functie een standaardwaarde heeft, moet het sleutelwoord DEFAULT worden opgegeven wanneer de functie wordt aangeroepen 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 gegevenstype rowversion/timestamp is geen ondersteund type. De niet-calaire typen cursor en tabel zijn niet toegestaan.

function_body

Reeks Transact-SQL instructies. De function_body kan geen instructie bevatten SELECT en kan niet verwijzen naar databasegegevens. De function_body kan niet verwijzen naar tabellen of weergaven. De hoofdtekst van de functie kan andere deterministische functies aanroepen, maar kan geen niet-deterministische functies 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 tabelwaardefunctie is er geen hoofdtekst van de functie; de tabel is de resultatenset van één SELECT instructie.

TAFEL

Hiermee geeft u aan dat de retourwaarde van de tabelwaardige functie (TVF) een tabel is. Alleen constanten en @local_variables kunnen worden doorgegeven aan TVF's.

In inline-TVF's (preview) wordt de retourwaarde TABLE gedefinieerd via één SELECT instructie. Inlinefuncties 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 SCHEMABINDING is opgegeven, kunnen de basisobjecten niet worden gewijzigd op een manier die van invloed is op de functiedefinitie. De functiedefinitie zelf moet eerst worden gewijzigd of verwijderd om afhankelijkheden van het te wijzigen object te verwijderen.

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

  • De functie komt te vervallen.

  • De functie wordt gewijzigd met behulp van de instructie ALTER met de optie SCHEMABINDING niet opgegeven.

Een functie kan alleen schemagebonden zijn als aan de volgende voorwaarden is voldaan:

  • Door de gebruiker gedefinieerde functies waarnaar wordt verwezen door de functie zijn ook schemagebonden.

  • Naar de functies en andere UDF's waarnaar wordt verwezen door de functie, wordt verwezen met behulp van een of tweedelige naam.

  • Alleen ingebouwde functies en andere UDF's in dezelfde database kunnen worden verwezen in de hoofdtekst van UDF's.

  • De gebruiker die de CREATE FUNCTION instructie heeft uitgevoerd, heeft de machtiging VERWIJZINGEN voor de databaseobjecten waarnaar de functie 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 dit niet is opgegeven, CALLED ON NULL INPUT wordt deze standaard geïmpliceerd en wordt de hoofdtekst van de functie uitgevoerd, zelfs als NULL deze wordt doorgegeven als argument.

Beste praktijken

Als een door de gebruiker gedefinieerde functie niet wordt gemaakt met de COMPONENT SCHEMABINDING, kunnen wijzigingen die worden aangebracht in onderliggende objecten de definitie van de functie beïnvloeden en onverwachte resultaten opleveren wanneer deze wordt aangeroepen. Het wordt aanbevolen om de WITH SCHEMABINDING component op te geven wanneer u de functie maakt. Dit zorgt ervoor dat de objecten waarnaar wordt verwezen in de functiedefinitie niet kunnen worden gewijzigd, tenzij de functie ook wordt gewijzigd.

Interoperabiliteit

De volgende instructies zijn geldig in een scalaire functie:

  • Opdracht verklaringen.

  • Control-of-Flow-instructies behalve TRY... CATCH-instructies.

  • DECLARE-instructies voor het definiëren van lokale gegevensvariabelen.

In een inline-tabelwaardefunctie (preview) is slechts één select-instructie toegestaan.

Beperkingen

Door de gebruiker gedefinieerde functies kunnen niet worden gebruikt om acties uit te voeren die de databasestatus wijzigen.

Door de gebruiker gedefinieerde functies kunnen worden genest; Dat wil gezegd, één door de gebruiker gedefinieerde functie kan een andere aanroepen. Het nestniveau wordt verhoogd wanneer de aangeroepen functie wordt gestart en afneemt wanneer de aangeroepen functie de uitvoering voltooit. Als u de maximumniveaus van nesten overschrijdt, mislukt de hele aanroepende functieketen. In Microsoft Fabric Data Warehouse kunnen door de gebruiker gedefinieerde functies maximaal vijf niveaus worden genest.

Objecten, inclusief functies, kunnen niet worden gemaakt in de master database van uw serverloze 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 de machtiging CREATE FUNCTION in de database en ALTER-machtiging 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 gebruikt een gegevenstype int als invoer en retourneert een decimaal gegevenstype (10,2) 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';

Opmerking

Scalaire functies zijn niet beschikbaar in de serverloze SQL-pools.

B. Een functie met tabelwaarde inline maken

In het volgende voorbeeld wordt een inline-tabelwaardefunctie gemaakt om belangrijke informatie over modules te retourneren, waarbij de objectType parameter wordt gefilterd. Het bevat een standaardwaarde om alle modules te retourneren wanneer de functie wordt aangeroepen met de DEFAULT parameter. In dit voorbeeld worden enkele van de systeemcatalogusweergaven gebruikt die worden vermeld in Metagegevens.

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

De functie kan vervolgens worden aangeroepen om alle weergaveobjecten (V) te retourneren met:

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

Opmerking

Inline-tabelwaardefuncties zijn beschikbaar in de serverloze SQL-pools, maar in preview in de toegewezen SQL-pools.

C. Resultaten van een inline tabelwaardefunctie combineren

In dit eenvoudige voorbeeld wordt de eerder gemaakte inline TVF gebruikt om te laten zien hoe de resultaten kunnen worden gecombineerd met andere tabellen met kruislingse toepassing. Hier selecteren we alle kolommen uit beide sys.objects en de resultaten van ModulesByType alle rijen die overeenkomen met de type kolom. Zie FROM-component plus JOIN, APPLY, PIVOT (Transact-SQL) voor meer informatie over het gebruik van apply.

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

Opmerking

Inline-tabelwaardefuncties zijn beschikbaar in de serverloze SQL-pools, maar in preview in de toegewezen SQL-pools.

Volgende stap

door de gebruiker gedefinieerde functies (Database Engine) maken