Delen via


FUNCTIE MAKEN (Transact-SQL)

van toepassing op:SQL ServerAzure SQL DatabaseAzure SQL Managed Instance

Hiermee maakt u een door de gebruiker gedefinieerde functie (UDF), een Transact-SQL of Common Language Runtime (CLR)-routine. Een door de gebruiker gedefinieerde functie accepteert parameters, voert een actie uit, zoals een complexe berekening, en retourneert het resultaat van die actie als een waarde. De geretourneerde waarde kan een scalaire (enkele) waarde of een tabel zijn. 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 weergave parametriseren of de functionaliteit van een geïndexeerde weergave verbeteren
  • Een kolom in een tabel definiëren
  • Een beperking voor een kolom definiëren CHECK
  • Een opgeslagen procedure vervangen
  • Een inlinefunctie gebruiken als filterpredicaat voor een beveiligingsbeleid

De integratie van .NET Framework CLR in SQL Server wordt in dit artikel besproken. CLR-integratie is niet van toepassing op Azure SQL Database.

Zie CREATE FUNCTION (Azure Synapse Analytics en Microsoft Fabric) voor Azure Synapse Analytics of Microsoft Fabric.

Transact-SQL syntaxis-conventies

Syntaxis

Syntaxis voor Transact-SQL scalaire functies.

CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] [ type_schema_name. ] parameter_data_type [ NULL ]
 [ = default ] [ READONLY ] }
    [ , ...n ]
  ]
)
RETURNS return_data_type
    [ WITH <function_option> [ , ...n ] ]
    [ AS ]
    BEGIN
        function_body
        RETURN scalar_expression
    END
[ ; ]

Syntaxis voor Transact-SQL inline functies met tabelwaarden.

CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] [ type_schema_name. ] parameter_data_type [ NULL ]
    [ = default ] [ READONLY ] }
    [ , ...n ]
  ]
)
RETURNS TABLE
    [ WITH <function_option> [ , ...n ] ]
    [ AS ]
    RETURN [ ( ] select_stmt [ ) ]
[ ; ]

Syntaxis voor Transact-SQL functies met tabelwaarde meerdere instructies.

CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] [ type_schema_name. ] parameter_data_type [ NULL ]
    [ = default ] [ READONLY ] }
    [ , ...n ]
  ]
)
RETURNS @return_variable TABLE <table_type_definition>
    [ WITH <function_option> [ , ...n ] ]
    [ AS ]
    BEGIN
        function_body
        RETURN
    END
[ ; ]

Syntaxis voor Transact-SQL functiezinnen.

<function_option> ::=
{
    [ ENCRYPTION ]
  | [ SCHEMABINDING ]
  | [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]
  | [ EXECUTE_AS_Clause ]
  | [ INLINE = { ON | OFF } ]
}

<table_type_definition> ::=
( { <column_definition> <column_constraint>
  | <computed_column_definition> }
    [ <table_constraint> ] [ , ...n ]
)
<column_definition> ::=
{
    { column_name data_type }
    [ [ DEFAULT constant_expression ]
      [ COLLATE collation_name ] | [ ROWGUIDCOL ]
    ]
    | [ IDENTITY [ (seed , increment ) ] ]
    [ <column_constraint> [ ...n ] ]
}

<column_constraint> ::=
{
    [ NULL | NOT NULL ]
    { PRIMARY KEY | UNIQUE }
      [ CLUSTERED | NONCLUSTERED ]
      [ WITH FILLFACTOR = fillfactor
        | WITH ( <index_option> [ , ...n ] )
      [ ON { filegroup | "default" } ] ]
  | [ CHECK ( logical_expression ) ] [ , ...n ]
}

<computed_column_definition> ::=
column_name AS computed_column_expression

<table_constraint> ::=
{
    { PRIMARY KEY | UNIQUE }
      [ CLUSTERED | NONCLUSTERED ]
      ( column_name [ ASC | DESC ] [ , ...n ]
        [ WITH FILLFACTOR = fillfactor
        | WITH ( <index_option> [ , ...n ] )
  | [ CHECK ( logical_expression ) ] [ , ...n ]
}

<index_option> ::=
{
    PAD_INDEX = { ON | OFF }
  | FILLFACTOR = fillfactor
  | IGNORE_DUP_KEY = { ON | OFF }
  | STATISTICS_NORECOMPUTE = { ON | OFF }
  | ALLOW_ROW_LOCKS = { ON | OFF }
  | ALLOW_PAGE_LOCKS = { ON | OFF }
}

Syntaxis voor scalaire CLR-functies.

CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name
( { @parameter_name [ AS ] [ type_schema_name. ] parameter_data_type [ NULL ]
    [ = default ] }
    [ , ...n ]
)
RETURNS { return_data_type }
    [ WITH <clr_function_option> [ , ...n ] ]
    [ AS ] EXTERNAL NAME <method_specifier>
[ ; ]

Syntaxis voor functies met tabelwaarde CLR.

CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name
( { @parameter_name [ AS ] [ type_schema_name. ] parameter_data_type [ NULL ]
    [ = default ] }
    [ , ...n ]
)
RETURNS TABLE <clr_table_type_definition>
    [ WITH <clr_function_option> [ , ...n ] ]
    [ ORDER ( <order_clause> ) ]
    [ AS ] EXTERNAL NAME <method_specifier>
[ ; ]

Syntaxis voor CLR-functieclausules.

<order_clause> ::=
{
   <column_name_in_clr_table_type_definition>
   [ ASC | DESC ]
} [ , ...n ]

<method_specifier> ::=
    assembly_name.class_name.method_name

<clr_function_option> ::=
{
    [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]
  | [ EXECUTE_AS_Clause ]
}

<clr_table_type_definition> ::=
( { column_name data_type } [ , ...n ] )

In-memory OLTP-syntaxis voor native gecompileerde, scalaire, door de gebruiker gedefinieerde functies.

CREATE [ OR ALTER ] FUNCTION [ schema_name. ] function_name
 ( [ { @parameter_name [ AS ] [ type_schema_name. ] parameter_data_type
    [ NULL | NOT NULL ] [ = default ] [ READONLY ] }
    [ , ...n ]
  ]
)
RETURNS return_data_type
     WITH <function_option> [ , ...n ]
    [ AS ]
    BEGIN ATOMIC WITH (set_option [ , ... n ] )
        function_body
        RETURN scalar_expression
    END

<function_option> ::=
{
  |  NATIVE_COMPILATION
  |  SCHEMABINDING
  | [ EXECUTE_AS_Clause ]
  | [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]
}

Argumenten

OF ALTER

Van toepassing op: SQL Server 2016 (13.x) SP 1 en latere versies en Azure SQL Database.

Wijzigt de functie alleen voorwaardelijk als deze al bestaat.

Er is een optionele OR ALTER syntaxis beschikbaar voor CLR, te beginnen met SQL Server 2016 (13.x) SP 1 CU 1.

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

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 door een apenstaartje (@) als eerste teken te gebruiken. 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 de plaats innemen van constanten; Ze kunnen niet worden gebruikt in plaats van tabelnamen, kolomnamen of de namen van andere databaseobjecten.

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 batchinstructie. Als een variabele bijvoorbeeld is gedefinieerd als teken(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.

[ type_schema_name. ] parameter_data_type

Het gegevenstype van de parameter, en eventueel het schema waartoe het behoort. Voor Transact-SQL functies zijn alle gegevenstypen, inclusief door de gebruiker gedefinieerde CLR-typen en door de gebruiker gedefinieerde tabeltypen, toegestaan, met uitzondering van het gegevenstype tijdstempel . Voor CLR-functies zijn alle gegevenstypen, inclusief door de gebruiker gedefinieerde CLR-typen, toegestaan, met uitzondering van tekst, ntext, afbeelding, door de gebruiker gedefinieerde tabeltypen en tijdstempelgegevenstypen . De niet-scalaire typen, cursor en tabel, kunnen niet worden opgegeven als parametergegevenstype in Transact-SQL- of CLR-functies.

Als type_schema_name niet is opgegeven, zoekt de database-engine in de volgende volgorde naar de scalar_parameter_data_type :

  • Het schema dat de namen van SQL Server-systeemgegevenstypen bevat.
  • Het standaardschema van de huidige gebruiker in de huidige database.
  • Het dbo-schema in de huidige database.

[ = 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.

Standaardparameterwaarden kunnen worden opgegeven voor CLR-functies, met uitzondering van de gegevenstypen varchar(max) en varbinary(max).

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. Het DEFAULT trefwoord is echter niet vereist bij het aanroepen van een scalaire functie met behulp van de EXECUTE instructie.

ALLEEN LEZEN

Geeft aan dat de parameter niet kan worden bijgewerkt of gewijzigd binnen de definitie van de functie. READONLY is vereist voor door de gebruiker gedefinieerde parameters voor tabeltypen (TVP's) en kan niet worden gebruikt voor andere parametertypen.

return_data_type

De retourwaarde van een scalaire, door de gebruiker gedefinieerde functie. Voor Transact-SQL functies zijn alle gegevenstypen, inclusief door de gebruiker gedefinieerde CLR-typen, toegestaan, behalve het gegevenstype tijdstempel . Voor CLR-functies zijn alle gegevenstypen, inclusief door de gebruiker gedefinieerde CLR-typen, toegestaan, met uitzondering van de gegevenstypen tekst, ntekst, afbeelding en tijdstempel . De niet-scalaire typen, cursor en tabel, kunnen niet worden opgegeven als een geretourneerd gegevenstype in Transact-SQL- of CLR-functies.

function_body

Hiermee geeft u aan dat een reeks Transact-SQL instructies, die samen geen neveneffect veroorzaken, zoals het wijzigen van een tabel, de waarde van de functie definiëren. function_body wordt alleen gebruikt in scalaire functies en multi-statement tabelwaardige functies (MSTVF's).

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

In MSTVF's is function_body een reeks Transact-SQL instructies die een TABLE retourvariabele vullen.

scalar_expression

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

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 wordt de TABLE retourwaarde gedefinieerd door middel van een enkele SELECT instructie. Inline-functies hebben geen gekoppelde retourvariabelen.

In MSTVF's is @return_variable een TABLE variabele die wordt gebruikt om de rijen op te slaan en te accumuleren die moeten worden geretourneerd als de waarde van de functie. @ return_variable kunnen alleen worden opgegeven voor Transact-SQL functies en niet voor CLR-functies.

select_stmt

De enkele SELECT instructie die de retourwaarde van een inline tabelwaardige functie (TVF) definieert.

BESTELLING (<order_clause>)

Hiermee geeft u de volgorde op waarin de resultaten worden geretourneerd door de functie met tabelwaarde. Zie voor meer informatie de sectie Sorteervolgorde gebruiken in CLR-tabelfuncties verderop in dit artikel.

EXTERNE NAAM <method_specifier>assembly_name.class_name. method_name

Van toepassing op: SQL Server 2008 (10.0.x) SP 1 en latere versies.

Hiermee geeft u de assembly en methode op waarnaar de gemaakte functienaam moet verwijzen.

  • assembly_name - moet overeenkomen met een waarde in de name kolom van SELECT * FROM sys.assemblies;.

    De naam die op de CREATE ASSEMBLY verklaring werd gebruikt.

  • class_name - moet overeenkomen met een waarde in de assembly_name kolom van SELECT * FROM sys.assembly_modules;.

    Vaak bevat de waarde een ingesloten punt of punt. In dergelijke gevallen vereist de syntaxis van het Transact-SQL dat de waarde wordt begrensd door een paar vierkante haken ([]), of door een paar dubbele aanhalingstekens ("").

  • method_name - moet overeenkomen met een waarde in de method_name kolom van SELECT * FROM sys.assembly_modules;.

    De methode moet statisch zijn.

In een typisch voorbeeld voor MyFood.dll, waarin alle typen zich in de MyFood naamruimte bevinden, zou de EXTERNAL NAME waarde kunnen zijn MyFood.[MyFood.MyClass].MyStaticMethod.

Standaard kan SQL Server geen CLR-code uitvoeren. U kunt databaseobjecten maken, wijzigen en neerzetten die verwijzen naar runtimemodules in veelgebruikte talen. U kunt deze verwijzingen echter pas uitvoeren in SQL Server als u de optie clr inschakelt. Gebruik sp_configure om deze optie in te schakelen. Deze optie is niet beschikbaar in een ingesloten database.

< > table_type_definition ( { <column_definition><column_constraint | <> computed_column_definition } [ <table_constraint> ] [ , ... n ] )

Definieert het tabelgegevenstype voor een Transact-SQL functie. De tabeldeclaratie bevat kolomdefinities en kolom- of tabelbeperkingen. De tabel wordt altijd in de primaire bestandsgroep geplaatst.

< > clr_table_type_definition ( { column_namedata_type } [ , ... n ] )

Van toepassing op: SQL Server 2008 (10.0.x) SP 1 en latere versies en Azure SQL Database (preview in sommige regio's).

Definieert de tabelgegevenstypen voor een CLR-functie. De tabeldeclaratie bevat alleen kolomnamen en gegevenstypen. De tabel wordt altijd in de primaire bestandsgroep geplaatst.

NULL | NIET NULL

Alleen ondersteund voor native gecompileerde, scalaire, door de gebruiker gedefinieerde functies. Zie Scalaire User-Defined functies voor In-Memory OLTP voor meer informatie.

NATIVE_COMPILATION

Geeft aan of een door de gebruiker gedefinieerde functie native is gecompileerd. Dit argument is vereist voor native gecompileerde, scalaire, door de gebruiker gedefinieerde functies.

BEGIN ATOMAIR MET

Vereist, en alleen ondersteund, voor native gecompileerde, scalaire, door de gebruiker gedefinieerde functies. Zie Atomaire blokken in native procedures voor meer informatie.

SCHEMABINDING

Het SCHEMABINDING argument is vereist voor native gecompileerde, scalaire, door de gebruiker gedefinieerde functies.

UITVOEREN ALS

EXECUTE AS is vereist voor native gecompileerde, scalaire, door de gebruiker gedefinieerde functies.

< > function_option ::= en <clr_function_option> ::=

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

CODERING

Van toepassing op: SQL Server 2008 (10.0.x) SP 1 en latere versies.

Geeft aan dat de database-engine de oorspronkelijke tekst van de CREATE FUNCTION instructie converteert naar een versluierde indeling. De uitvoer van de verduistering is niet direct zichtbaar in catalogusweergaven. Gebruikers die geen toegang hebben tot systeemtabellen of databasebestanden, kunnen de versluierde tekst niet ophalen. De tekst is echter beschikbaar voor bevoegde gebruikers die toegang hebben tot systeemtabellen via de diagnostische verbinding voor databasebeheerders of rechtstreeks toegang hebben tot databasebestanden. Gebruikers die een foutopsporingsprogramma aan het serverproces kunnen koppelen, kunnen ook de oorspronkelijke procedure tijdens runtime uit het geheugen ophalen. Zie Configuratie van zichtbaarheid van metagegevens van metagegevens voor meer informatie over toegang tot systeemmetagegevens.

Als u deze optie gebruikt, wordt voorkomen dat de functie wordt gepubliceerd als onderdeel van SQL Server-replicatie. Deze optie kan niet worden opgegeven voor CLR-functies.

SCHEMABINDING

Hiermee geeft u aan dat de functie is gebonden aan de databaseobjecten waarnaar wordt verwezen. Wanneer SCHEMABINDING dit 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 ALTER instructie met de SCHEMABINDING optie niet opgegeven.

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

  • De functie is een Transact-SQL functie.
  • De door de gebruiker gedefinieerde functies en weergaven waarnaar de functie verwijst, zijn ook schemagebonden.
  • Naar de objecten waarnaar de functie verwijst, wordt verwezen met behulp van een tweedelige naam.
  • De functie en de objecten waarnaar wordt verwezen, maken deel uit van dezelfde database.
  • De gebruiker die de CREATE FUNCTION instructie heeft uitgevoerd, heeft REFERENCES toestemming voor de databaseobjecten waarnaar de functie verwijst.

GEEFT ALS RESULTAAT NULL BIJ NULL-INVOER | OPGEROEPEN OP NULL-INVOER

Hiermee geeft u het OnNULLCall kenmerk van een scalaire functie op. Indien niet opgegeven, CALLED ON NULL INPUT wordt dit standaard geïmpliceerd. Met andere woorden, de functie body voert zelfs uit als NULL deze als argument wordt doorgegeven.

Als RETURNS NULL ON NULL INPUT is opgegeven in een CLR-functie, geeft dit aan dat SQL Server kan terugkeren NULL wanneer een van de ontvangen argumenten , NULLzonder dat de hoofdtekst van de functie daadwerkelijk wordt aangeroepen. Als de methode van een CLR-functie die is opgegeven in <method_specifier> al een aangepast kenmerk heeft dat aangeeft RETURNS NULL ON NULL INPUT, maar de CREATE FUNCTION instructie aangeeft CALLED ON NULL INPUT, heeft de CREATE FUNCTION instructie voorrang. Het OnNULLCall kenmerk kan niet worden opgegeven voor functies met een CLR-tabelwaarde.

UITVOEREN ALS

Hiermee geeft u de beveiligingscontext op waarin de door de gebruiker gedefinieerde functie wordt uitgevoerd. Daarom kunt u bepalen welk gebruikersaccount SQL Server gebruikt om machtigingen te valideren voor databaseobjecten waarnaar door de functie wordt verwezen.

EXECUTE AS Kan niet worden opgegeven voor functies met een inline-tabelwaarde.

Zie voor meer informatie EXECUTE AS-clausule (Transact-SQL).

INLINE = { AAN | UIT }

Van toepassing op: SQL Server 2019 (15.x) en latere versies, en Azure SQL Database.

Geeft aan of deze scalaire UDF al dan niet moet worden inlineged. Deze clausule is alleen van toepassing op scalaire, door de gebruiker gedefinieerde functies. De INLINE-component is niet verplicht. Als de INLINE clausule niet is opgegeven, wordt deze automatisch ingesteld op ON of OFF op basis van het feit of de UDF inlineeerbaar is. Als INLINE = ON is gespecificeerd, maar de UDF blijkt niet-inlineeerbaar te zijn, wordt er een fout gegenereerd. Zie Scalar UDF Inliningvoor meer informatie.

< > column_definition ::=

Definieert het gegevenstype van de tabel. De tabeldeclaratie bevat kolomdefinities en beperkingen. Voor CLR-functies kunnen alleen column_name en data_type worden opgegeven.

column_name

De naam van een kolom in de tabel. Kolomnamen moeten voldoen aan de regels voor ID's en moeten uniek zijn in de tabel. column_name kan bestaan uit 1 tot en met 128 tekens.

data_type

Hiermee geeft u het gegevenstype van de kolom op. Voor Transact-SQL functies zijn alle gegevenstypen, inclusief door de gebruiker gedefinieerde CLR-typen, toegestaan, met uitzondering van tijdstempels. Voor CLR-functies zijn alle gegevenstypen, inclusief door de gebruiker gedefinieerde CLR-typen, toegestaan, behalve tekst, ntext, afbeelding, char, varchar, varchar(max) en tijdstempel. De cursor van het niet-scalaire type kan niet worden opgegeven als een kolomgegevenstype in Transact-SQL- of CLR-functies.

STANDAARD constant_expression

Hiermee geeft u de opgegeven waarde voor de kolom op wanneer een waarde niet expliciet wordt opgegeven tijdens een invoeging. constant_expression is een constante, NULLof een systeemfunctiewaarde. DEFAULT Definities kunnen worden toegepast op elke kolom, behalve de kolommen die de IDENTITY eigenschap hebben. DEFAULT kan niet worden opgegeven voor functies met een CLR-tabelwaarde.

COLLATION_NAME

Hiermee geeft u de sortering voor de kolom. Als dit niet is opgegeven, wordt aan de kolom de standaardsortering van de database toegewezen. De sorteringsnaam kan een Windows-sorteringsnaam of een SQL-sorteringsnaam zijn. Zie Windows Sorteernaam (Transact-SQL) en SQL Server Sorteernaam (Transact-SQL) voor een lijst met en meer informatie over sortages.

De COLLATE clausule kan alleen worden gebruikt om de sorteringen van kolommen van de gegevenstypen char, varchar, nchar en nvarchar te wijzigen. COLLATE kan niet worden opgegeven voor functies met een CLR-tabelwaarde.

ROWGUIDCOL

Geeft aan dat de nieuwe kolom een kolom is met een wereldwijd unieke identificatie. Er kan slechts één unieke identificatiekolom per tabel worden aangewezen als de ROWGUIDCOL kolom. De ROWGUIDCOL eigenschap kan alleen worden toegewezen aan een uniqueidentifier-kolom .

De ROWGUIDCOL eigenschap dwingt de uniciteit van de waarden die in de kolom zijn opgeslagen niet af. Er worden ook niet automatisch waarden gegenereerd voor nieuwe rijen die in de tabel worden ingevoegd. Als u unieke waarden voor elke kolom wilt genereren, gebruikt u de NEWID functie op INSERT instructies. Er kan een standaardwaarde worden opgegeven; Kan NEWID echter niet worden opgegeven als de standaardinstelling.

IDENTITEIT

Geeft aan dat de nieuwe kolom een identiteitskolom is. Wanneer een nieuwe rij aan de tabel wordt toegevoegd, biedt SQL Server een unieke, incrementele waarde voor de kolom. Identiteitskolommen worden doorgaans gebruikt in combinatie met PRIMARY KEY beperkingen om te dienen als de unieke rij-id voor de tabel. De IDENTITY eigenschap kan worden toegewezen aan littleyint, smallint, int, bigint, decimale (p,0) of numerieke (p,0) kolommen. Er kan slechts één identiteitskolom per tabel worden gemaakt. Afhankelijke standaardinstellingen en DEFAULT beperkingen kunnen niet worden gebruikt met een identiteitskolom. U moet zowel de seed als de toename opgeven of geen van beide. Als geen van beide is opgegeven, is de standaardwaarde (1,1).

IDENTITY kan niet worden opgegeven voor functies met een CLR-tabelwaarde.

zaad

Het gehele getal dat moet worden toegewezen aan de eerste rij in de tabel.

incrementele

Het gehele getal dat moet worden toegevoegd aan de seed-waarde voor opeenvolgende rijen in de tabel.

< > column_constraint ::= en <table_constraint> ::=

Definieert de beperking voor een opgegeven kolom of tabel. Voor CLR-functies is NULLhet enige toegestane beperkingstype . Benoemde beperkingen zijn niet toegestaan.

NULL | NIET NULL

Hiermee bepaalt u of null-waarden zijn toegestaan in de kolom. NULL is niet strikt een beperking, maar kan net als NOT NULL. NOT NULL kan niet worden opgegeven voor functies met een CLR-tabelwaarde.

PRIMAIRE SLEUTEL

Een beperking die entiteitsintegriteit afdwingt voor een opgegeven kolom via een unieke index. In door de gebruiker gedefinieerde functies met tabelwaarde kan de PRIMARY KEY beperking worden gemaakt voor slechts één kolom per tabel. PRIMARY KEY kan niet worden opgegeven voor functies met een CLR-tabelwaarde.

UNIEK

Een beperking die entiteitsintegriteit biedt voor een opgegeven kolom of kolommen via een unieke index. Een tabel kan meerdere UNIQUE beperkingen hebben. UNIQUE kan niet worden opgegeven voor functies met een CLR-tabelwaarde.

GECLUSTERD | NIET-GECLUSTERD

Geef aan dat er een gegroepeerde of niet-geclusterde index is gemaakt voor de PRIMARY KEY beperking of UNIQUE . PRIMARY KEY Constraints gebruik CLUSTERED, en UNIQUE constraints gebruik NONCLUSTERED.

CLUSTERED Kan worden opgegeven voor slechts één beperking. Als CLUSTERED is opgegeven voor een UNIQUE beperking en er is ook een PRIMARY KEY beperking opgegeven, wordt het PRIMARY KEY gebruik NONCLUSTERED.

CLUSTERED en NONCLUSTERED kunnen niet worden opgegeven voor functies met een CLR-tabelwaarde.

CONTROLE

Een beperking waarmee domeinintegriteit wordt afgedwongen door de mogelijke waarden te beperken die kunnen worden ingevoerd in een kolom of kolommen. CHECK beperkingen kunnen niet worden opgegeven voor functies met een CLR-tabelwaarde.

logical_expression

Een logische uitdrukking die terugkomt TRUE op of FALSE.

< > computed_column_definition ::=

Hiermee geeft u een berekende kolom op. Zie TABEL MAKEN (Transact-SQL) voor meer informatie over berekende kolommen.

column_name

De naam van de berekende kolom.

computed_column_expression

Een expressie die de waarde van een berekende kolom definieert.

< > index_option ::=

Hiermee geeft u de indexopties voor de PRIMARY KEY of UNIQUE index op. Zie INDEX MAKEN (Transact-SQL) voor meer informatie over indexopties.

PAD_INDEX = { ON | UIT }

Hiermee geeft u indexopvulling. De standaardwaarde is OFF.

FILLFACTOR = fillfactor

Hiermee geeft u een percentage op dat aangeeft hoe vol de database-engine het bladniveau van elke indexpagina moet maken tijdens het maken of wijzigen van de index. fillfactor moet een geheel getal tussen 1 en 100 zijn. De standaardwaarde is 0.

IGNORE_DUP_KEY = { ON | UIT }

Hiermee geeft u het foutbericht op wanneer een invoegbewerking probeert dubbele sleutelwaarden in een unieke index in te voegen. De optie IGNORE_DUP_KEY is alleen van toepassing op het invoegen van bewerkingen nadat de index is gemaakt of opnieuw is opgebouwd. De standaardwaarde is OFF.

STATISTICS_NORECOMPUTE = { AAN | UIT }

Hiermee geeft u op of verdelingsstatistieken opnieuw worden berekend. De standaardwaarde is OFF.

ALLOW_ROW_LOCKS = { AAN | UIT }

Hiermee geeft u op of rijvergrendelingen zijn toegestaan. De standaardwaarde is ON.

ALLOW_PAGE_LOCKS = { AAN | UIT }

Hiermee geeft u op of paginavergrendelingen zijn toegestaan. De standaardwaarde is ON.

Beste praktijken

Als een door de gebruiker gedefinieerde functie niet wordt gemaakt met de SCHEMABINDING clausule, kunnen wijzigingen die worden aangebracht in onderliggende objecten van invloed zijn op de definitie van de functie en onverwachte resultaten opleveren wanneer deze wordt aangeroepen. U wordt aangeraden een van de volgende methoden te implementeren om ervoor te zorgen dat de functie niet verouderd raakt vanwege wijzigingen in de onderliggende objecten:

  • Geef de WITH SCHEMABINDING component op wanneer u de functie maakt. Deze optie zorgt ervoor dat de objecten waarnaar in de functiedefinitie wordt verwezen, niet kunnen worden gewijzigd, tenzij de functie ook wordt gewijzigd.

  • Voer de procedure voor het sp_refreshsqlmodule opgeslagen uit na het wijzigen van een object dat is opgegeven in de definitie van de functie.

Zie Door de gebruiker gedefinieerde functies maken (Database Engine) voor meer informatie en prestatieoverwegingen over functies met een tabelwaarde in de regel (inline TVF's) en functies met een tabelwaarde met meerdere instructies (MSTVF's).

Gegevenstypen

Als parameters zijn opgegeven in een CLR-functie, moeten dit SQL Server-typen zijn zoals eerder gedefinieerd voor scalar_parameter_data_type. Zie CLR-parametergegevens toewijzen voor meer informatie over het vergelijken van SQL Server-systeemgegevenstypen met CLR-integratiegegevenstypen of .NET Framework-runtimegegevens.

Als u wilt dat SQL Server naar de juiste methode verwijst wanneer deze in een klasse overbelast is, moet de methode die wordt aangegeven in <method_specifier> de volgende kenmerken hebben:

  • Ontvang hetzelfde aantal parameters als gespecificeerd in [ , ...n ].
  • Ontvang alle parameters op waarde, niet op referentie.
  • Gebruik parametertypen die compatibel zijn met typen die zijn opgegeven in de SQL Server-functie.

Als het geretourneerde gegevenstype van de CLR-functie een tabeltype ()RETURNS TABLE specificeert, moet het geretourneerde gegevenstype van de methode van <method_specifier> het type IEnumerator of IEnumerablezijn en wordt ervan uitgegaan dat de interface wordt geïmplementeerd door de maker van de functie. In tegenstelling tot Transact-SQL functies kunnen CLR-functies geen , UNIQUE, of CHECK beperkingen bevatten PRIMARY KEYin <table_type_definition>. De gegevenstypen van de kolommen waarin wordt opgegeven <table_type_definition> , moeten overeenkomen met de typen van de corresponderende kolommen van de resultatenset die door de methode wordt <method_specifier> geretourneerd op het tijdstip van uitvoering. Deze typecontrole wordt niet uitgevoerd op het moment dat de functie wordt gemaakt.

Zie CLR User-Defined functies voor meer informatie over het programmeren van CLR-functies.

Opmerkingen

Scalaire functies kunnen worden aangeroepen wanneer scalaire expressies worden gebruikt, waaronder berekende kolommen en CHECK beperkingsdefinities. Scalaire functies kunnen ook worden uitgevoerd met behulp van de instructie EXECUTE (Transact-SQL). Scalaire functies moeten worden aangeroepen met ten minste de tweedelige naam van de functie (<schema>.<function>). Zie Transact-SQL Syntaxisconventies (Transact-SQL) voor meer informatie over meerdelige namen. Functies met tabelwaarde kunnen worden aangeroepen wanneer tabelexpressies zijn toegestaan in de FROM clausule van SELECT, INSERT, UPDATE, of DELETE instructies. Zie Door de gebruiker gedefinieerde functies uitvoeren voor meer informatie.

Interoperabiliteit

De volgende uitspraken zijn geldig in een functie:

  • Opdracht verklaringen.
  • Control-of-Flow-overzichten, met uitzondering TRY...CATCH van afschriften.
  • DECLARE Statements die lokale gegevensvariabelen en lokale cursors definiëren.
  • SELECT Instructies die selectielijsten bevatten met expressies die waarden toewijzen aan lokale variabelen.
  • Cursorbewerkingen die verwijzen naar lokale cursors die in de functie worden gedeclareerd, geopend, gesloten en niet-toegewezen. Alleen FETCH instructies die waarden toewijzen aan lokale variabelen met behulp van de INTO component zijn toegestaan; FETCH instructies die gegevens naar de client sturen, zijn niet toegestaan.
  • INSERT, UPDATE, en instructies die lokale tabelvariabelen DELETE wijzigen.
  • EXECUTE verklaringen die uitgebreide opgeslagen procedures aanroepen.

Zie voor meer informatie Door de gebruiker gedefinieerde functies maken (database-engine).

Interoperabiliteit van berekende kolommen

Functies hebben de volgende eigenschappen. De waarden van deze eigenschappen bepalen of functies kunnen worden gebruikt in berekende kolommen die kunnen worden persistent of geïndexeerd.

Vastgoed Beschrijving Opmerkingen
IsDeterministic Functie is deterministisch of niet-deterministisch. Lokale gegevenstoegang is toegestaan in deterministische functies. Functies die bijvoorbeeld altijd hetzelfde resultaat retourneren wanneer ze worden aangeroepen met behulp van een specifieke set invoerwaarden en met dezelfde status van de database, worden als deterministisch bestempeld.
IsPrecise Functie is nauwkeurig of onnauwkeurig. Onnauwkeurige functies bevatten bewerkingen zoals drijvende-kommabewerkingen.
IsSystemVerified De precisie- en determinisme-eigenschappen van de functie kunnen worden geverifieerd door SQL Server.
SystemDataAccess De functie heeft toegang tot systeemgegevens (systeemcatalogi of virtuele systeemtabellen) in het lokale exemplaar van SQL Server.
UserDataAccess Functie heeft toegang tot gebruikersgegevens in het lokale exemplaar van SQL Server. Bevat door de gebruiker gedefinieerde tabellen en tijdelijke tabellen, maar geen tabelvariabelen.

De precisie- en determinisme-eigenschappen van Transact-SQL functies worden automatisch bepaald door SQL Server. De gegevenstoegang en determinisme-eigenschappen van CLR-functies kunnen door de gebruiker worden opgegeven. Zie CLR-integratie: aangepaste kenmerken voor CLR-routines voor meer informatie.

Als u de huidige waarden voor deze eigenschappen wilt weergeven, gebruikt u OBJECTPROPERTYEX (Transact-SQL).

Belangrijk

Functies moeten worden gemaakt om SCHEMABINDING deterministisch te zijn.

Een berekende kolom die een door de gebruiker gedefinieerde functie aanroept, kan in een index worden gebruikt wanneer de door de gebruiker gedefinieerde functie de volgende eigenschapswaarden heeft:

  • IsDeterministic is true
  • IsSystemVerified is true (tenzij de berekende kolom wordt aangehouden)
  • UserDataAccess is false
  • SystemDataAccess is false

Zie Indexen voor berekende kolommenvoor meer informatie.

Roep uitgebreide opgeslagen procedures op vanuit functies

Wanneer de uitgebreide opgeslagen procedure wordt aangeroepen vanuit een functie, kunnen geen resultatensets worden geretourneerd aan de client. Alle ODS-API's die resultatensets naar de client retourneren, retourneren FAIL. De uitgebreide opgeslagen procedure kan weer verbinding maken met een exemplaar van SQL Server; Het mag echter niet proberen deel te nemen aan dezelfde transactie als de functie die de procedure voor uitgebreid opslaan heeft aangeroepen.

Net als bij aanroepen van een batch of opgeslagen procedure, wordt de procedure voor uitgebreid opslaan uitgevoerd in de context van het Windows-beveiligingsaccount waaronder SQL Server wordt uitgevoerd. De eigenaar van de opgeslagen procedure moet rekening houden met dit scenario wanneer hij toestemming geeft EXECUTE aan gebruikers.

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 geen OUTPUT INTO-component bevatten die een tabel als doel heeft.

De volgende Service Broker-instructies kunnen niet worden opgenomen in de definitie van een Transact-SQL door de gebruiker gedefinieerde functie:

  • BEGIN DIALOG CONVERSATION
  • END CONVERSATION
  • GET CONVERSATION GROUP
  • MOVE CONVERSATION
  • RECEIVE
  • SEND

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. Gebruikersgedefinieerde functies kunnen tot maximaal 32 niveaus worden genest. Als u de maximumniveaus van nesten overschrijdt, mislukt de hele aanroepende functieketen. Elke verwijzing naar beheerde code van een gebruikergedefinieerde Transact-SQL-functie telt als één niveau ten opzichte van de nestlimiet van 32 niveaus. Methoden die vanuit beheerde code worden aangeroepen, tellen niet mee voor deze limiet.

Sorteervolgorde gebruiken in functies met tabelwaarden van CLR

Volg deze richtlijnen wanneer u de ORDER component gebruikt in functies met tabelwaarden van CLR:

  • U moet ervoor zorgen dat de resultaten altijd in de opgegeven volgorde worden gerangschikt. Als de resultaten niet in de opgegeven volgorde staan, genereert SQL Server een foutbericht wanneer de query wordt uitgevoerd.

  • Als een ORDER clausule is opgegeven, moet de uitvoer van de tabelwaardige functie worden gesorteerd op basis van de sortering van de kolom (expliciet of impliciet). Als de kolomsortering bijvoorbeeld Chinees is, moeten de geretourneerde resultaten worden gesorteerd volgens de Chinese sorteerregels. (Sortering wordt gespecificeerd in de DDL voor de tabelwaardige functie of verkregen uit de databasesortering.)

  • SQL Server controleert altijd de clausule indien opgegeven, terwijl de ORDER resultaten worden geretourneerd, ongeacht of de queryverwerker deze gebruikt om verdere optimalisaties uit te voeren. Gebruik de ORDER clausule alleen als u weet dat deze nuttig is voor de queryverwerker.

  • De SQL Server-queryprocessor maakt automatisch gebruik van de ORDER clausule in de volgende gevallen:

    • Query's invoegen waarbij de ORDER clausule compatibel is met een index.
    • ORDER BY clausules die verenigbaar zijn met de ORDER clausule.
    • Aggregaten, indien GROUP BY verenigbaar ORDER met clausule.
    • DISTINCT aggregaten waarvan de afzonderlijke kolommen verenigbaar zijn met de ORDER clausule.

De ORDER clausule garandeert geen geordende resultaten wanneer een SELECT query wordt uitgevoerd, tenzij ORDER BY dit ook in de query is gespecificeerd. Zie sys.function_order_columns (Transact-SQL) voor informatie over het opvragen van kolommen in de sorteervolgorde voor functies met tabelwaarden.

Metagegevens

De volgende tabel bevat de weergaven van de systeemcatalogus die u kunt gebruiken om metagegevens over door de gebruiker gedefinieerde functies te retourneren.

Systeemweergave Beschrijving
sys.sql_modules Zie voorbeeld E in de sectie Voorbeelden.
sys.assembly_modules Geeft informatie weer over door de gebruiker gedefinieerde CLR-functies.
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 door een functie wordt verwezen.

Machtigingen

Vereist CREATE FUNCTION machtiging in de database en ALTER machtiging voor het schema waarin de functie wordt gemaakt. Als de functie een door de gebruiker gedefinieerd type opgeeft, is EXECUTE machtiging voor het type vereist.

Voorbeelden

Zie Door de gebruiker gedefinieerde functies maken (database-engine) voor meer voorbeelden en prestatieoverwegingen over UDF's.

Eén. Gebruik een door de gebruiker gedefinieerde scalair-waardige functie die de ISO-week berekent

In het volgende voorbeeld wordt de door de gebruiker gedefinieerde functie ISOweekgemaakt. Deze functie neemt een datumargument en berekent het ISO-weeknummer. Om deze functie correct te berekenen, SET DATEFIRST 1 moet deze worden aangeroepen voordat de functie wordt aangeroepen.

In het voorbeeld wordt ook het gebruik van de EXECUTE AS-clausule (Transact-SQL) gebruikt om de beveiligingscontext op te geven waarin een opgeslagen procedure kan worden uitgevoerd. In het voorbeeld geeft de optie CALLER aan dat de procedure wordt uitgevoerd in de context van de gebruiker die de procedure aanroept. De andere opties die u kunt opgeven zijn SELF, OWNER, en user_name.

Hier is de functieaanroep. DATEFIRST is ingesteld op 1.

CREATE FUNCTION dbo.ISOweek (@DATE DATETIME)
RETURNS INT
WITH EXECUTE AS CALLER
AS
BEGIN
    DECLARE @ISOweek INT;

    SET @ISOweek = DATEPART(wk, @DATE) + 1 -
        DATEPART(wk, CAST(DATEPART(yy, @DATE) AS CHAR(4)) + '0104');

    --Special cases: Jan 1-3 may belong to the previous year
    IF (@ISOweek = 0)
        SET @ISOweek = dbo.ISOweek(CAST(DATEPART(yy, @DATE) - 1 AS CHAR(4))
           + '12' + CAST(24 + DATEPART(DAY, @DATE) AS CHAR(2))) + 1;

    --Special case: Dec 29-31 may belong to the next year
    IF ((DATEPART(mm, @DATE) = 12)
        AND ((DATEPART(dd, @DATE) - DATEPART(dw, @DATE)) >= 28))
    SET @ISOweek = 1;

    RETURN (@ISOweek);
END;
GO

SET DATEFIRST 1;

SELECT dbo.ISOweek(CONVERT(DATETIME, '12/26/2004', 101)) AS 'ISO Week';

Hier is het resultatenoverzicht.

ISO Week
----------------
52

B. Een functie met tabelwaarde inline maken

In het volgende voorbeeld wordt een functie met tabelwaarden in de regel geretourneerd in de database AdventureWorks2022. Het retourneert drie kolommen ProductID, Name, en het totaal van de totalen tot nu toe per winkel voor YTD Total elk product dat aan de winkel is verkocht.

CREATE FUNCTION Sales.ufn_SalesByStore (@storeid INT)
RETURNS TABLE
AS
RETURN (
    SELECT P.ProductID, P.Name, SUM(SD.LineTotal) AS 'Total'
    FROM Production.Product AS P
    INNER JOIN Sales.SalesOrderDetail AS SD ON SD.ProductID = P.ProductID
    INNER JOIN Sales.SalesOrderHeader AS SH ON SH.SalesOrderID = SD.SalesOrderID
    INNER JOIN Sales.Customer AS C ON SH.CustomerID = C.CustomerID
    WHERE C.StoreID = @storeid
    GROUP BY P.ProductID, P.Name
);
GO

Voer deze query uit om de functie aan te roepen.

SELECT * FROM Sales.ufn_SalesByStore (602);

C. Een functie met meerdere instructies maken

In het volgende voorbeeld wordt de functie fn_FindReports(InEmpID) met tabelwaarde in de AdventureWorks2022 database gemaakt. Wanneer de functie wordt voorzien van een geldige werknemers-ID, retourneert deze een tabel die overeenkomt met alle werknemers die direct of indirect aan de werknemer rapporteren. De functie maakt gebruik van een recursieve Common Table Expression (CTE) om de hiërarchische lijst van werknemers te produceren. Voor meer informatie over recursieve CTE's, zie MET common_table_expression (Transact-SQL).

CREATE FUNCTION dbo.ufn_FindReports (@InEmpID INT)
RETURNS @retFindReports TABLE (
    EmployeeID INT PRIMARY KEY NOT NULL,
    FirstName NVARCHAR(255) NOT NULL,
    LastName NVARCHAR(255) NOT NULL,
    JobTitle NVARCHAR(50) NOT NULL,
    RecursionLevel INT NOT NULL
    )
    --Returns a result set that lists all the employees who report to the
    --specific employee directly or indirectly.
AS
BEGIN
    WITH EMP_cte (
        EmployeeID,
        OrganizationNode,
        FirstName,
        LastName,
        JobTitle,
        RecursionLevel
        ) -- CTE name and columns
    AS (
        -- Get the initial list of Employees for Manager n
        SELECT e.BusinessEntityID,
            OrganizationNode = ISNULL(e.OrganizationNode, CAST('/' AS HIERARCHYID)),
            p.FirstName,
            p.LastName,
            e.JobTitle,
            0
        FROM HumanResources.Employee e
        INNER JOIN Person.Person p
            ON p.BusinessEntityID = e.BusinessEntityID
        WHERE e.BusinessEntityID = @InEmpID
        
        UNION ALL
        
        -- Join recursive member to anchor
        SELECT e.BusinessEntityID,
            e.OrganizationNode,
            p.FirstName,
            p.LastName,
            e.JobTitle,
            RecursionLevel + 1
        FROM HumanResources.Employee e
        INNER JOIN EMP_cte
            ON e.OrganizationNode.GetAncestor(1) = EMP_cte.OrganizationNode
        INNER JOIN Person.Person p
            ON p.BusinessEntityID = e.BusinessEntityID
        )
    -- Copy the required columns to the result of the function
    INSERT @retFindReports
    SELECT EmployeeID,
        FirstName,
        LastName,
        JobTitle,
        RecursionLevel
    FROM EMP_cte

    RETURN
END;
GO

-- Example invocation
SELECT EmployeeID,
    FirstName,
    LastName,
    JobTitle,
    RecursionLevel
FROM dbo.ufn_FindReports(1);
GO

D. Een CLR-functie maken

In het voorbeeld wordt de CLR-functie len_sgemaakt. Voordat de functie wordt aangemaakt, wordt de assembly SurrogateStringFunction.dll geregistreerd in de lokale database.

Van toepassing op: SQL Server 2008 (10.0.x) SP 1 en latere versies.

DECLARE @SamplesPath NVARCHAR(1024);

-- You may have to modify the value of this variable if you have
-- installed the sample in a location other than the default location.
SELECT @SamplesPath = REPLACE(physical_name,
    'Microsoft SQL Server\MSSQL13.MSSQLSERVER\MSSQL\DATA\master.mdf',
    'Microsoft SQL Server\130\Samples\Engine\Programmability\CLR\'
)
FROM master.sys.database_files
WHERE name = 'master';

CREATE ASSEMBLY [SurrogateStringFunction]
FROM @SamplesPath + 'StringManipulate\CS\StringManipulate\bin\debug\SurrogateStringFunction.dll'
    WITH PERMISSION_SET = EXTERNAL_ACCESS;
GO

CREATE FUNCTION [dbo].[len_s] (@str NVARCHAR(4000))
RETURNS BIGINT
AS
EXTERNAL NAME [SurrogateStringFunction].[Microsoft.Samples.SqlServer.SurrogateStringFunction].[LenS];
GO

Zie CLR Table-Valued functies voor een voorbeeld van het maken van een functie met een CLR-tabelwaarde.

E. Weergave van de definitie van door de gebruiker gedefinieerde functies

SELECT DEFINITION,
    type
FROM sys.sql_modules AS m
INNER JOIN sys.objects AS o
    ON m.object_id = o.object_id
    AND type IN ('FN', 'IF', 'TF');
GO

De definitie van functies die met de ENCRYPTION optie zijn gemaakt, kan niet worden weergegeven met behulp van sys.sql_modules; andere informatie over de versleutelde functies wordt echter wel weergegeven.