Créer une fonction scalaire définie par l'utilisateur dans SQL Server

Dans SQL Server, vous pouvez créer une fonction scalaire définie par l'utilisateur à l'aide de CREATE FUNCTION déclaration. Une fonction scalaire définie par l'utilisateur, également appelée UDF scalaire, est une fonction définie par l'utilisateur qui renvoie une valeur unique.

Cet article contient des exemples de création de certaines UDF scalaires T-SQL de base.

Syntaxe

Examinons d'abord la syntaxe pour créer des UDF scalaires.

La syntaxe des UDF scalaires T-SQL ressemble à ceci :

 CREATE [ OR ALTER ] FUNCTION [ nom_schéma. ] nom_fonction ( [ { @nom_paramètre [ AS ][ nom_schéma_type. ] type_données_paramètre [ =défaut ] [ LECTURE SEULE ] } [ ,...n ] ] ) RETURNS type_données_retour [ WITH  [ ,...n ] ] [ AS ] BEGIN corps_fonction RETURN expression_scalaire END [; ]

Et la syntaxe des UDF scalaires CLR :

 CREATE [ OR ALTER ] FUNCTION [ nom_schéma. ] nom_fonction ( { @nom_paramètre [AS] [ nom_schéma_type. ] type_données_paramètre [ =défaut ] } [ ,...n ] ) RETURNS { type_données_retour } [ WITH  [ ,...n ] ] [ AS ] NOM EXTERNE  [ ; ] 

Les pièces à <function_option> pour les fonctions T-SQL et <clr_function_option> pour les fonctions CLR vous permettent de spécifier des options pour l'UDF. Les options de fonction incluent l'ajout de chiffrement, la liaison de schéma, un EXECUTE AS clause, ainsi que de spécifier ce qu'il faut faire lorsqu'une valeur NULL est passée en argument.

Une liste complète des arguments et des options de fonction est disponible sur le site Web de Microsoft.

La documentation de Microsoft contient beaucoup de détails, donc les exemples suivants visent à fournir un aperçu rapide de certains concepts et options courants lors de la création de FDU scalaires.

Exemple 1 - UDF scalaire de base

Voici un exemple de code utilisé pour créer une UDF scalaire T-SQL de base.

CREATE FUNCTION dbo.ufn_discountPrice( @price DECIMAL(12,2), @discount DECIMAL(12,2) ) RENVOIE DECIMAL (12,2)ASBEGIN RETURN @price * (1 - @discount);END; 

 Cette UDF scalaire accepte deux paramètres ; @price et @discount . Ceux-ci sont transmis à la fonction en tant qu'arguments chaque fois que la fonction est invoquée. La fonction prend la valeur de ces arguments, effectue un calcul à l'aide de ces valeurs, puis renvoie la valeur résultante. Dans ce cas, le prix réduit est retourné.
 
Exemple 2 - Invoquer l'UDF
 

 Une fois l'UDF créée, elle peut être invoquée dans le code T-SQL à tout moment.
 

 Voici un exemple d'invocation de l'UDF :
 
SELECT dbo.ufn_discountPrice(100, .2) AS Result ;
 

 Résultat
 
+----------+| Résultat ||----------|| 80.00 |+----------+
 
Exemple 3 – Interroger une table
 

 Les UDF scalaires peuvent également faire des choses comme interroger des tables de base de données.
 

 En voici un qui renvoie le nombre d'albums dans la base de données pour un artiste donné. 
 
CREATE FUNCTION dbo.ufn_CountAlbums (@ArtistId int) RETURNS smallintAS BEGIN DECLARE @AlbumCount int; SELECT @AlbumCount =COUNT(AlbumId) FROM Albums WHERE ArtistId =@ArtistId ; RETURN @AlbumCount;END;
 

 Il s'agit d'une fonction scalaire car elle ne renvoie qu'une seule valeur. Si nous voulions renvoyer une liste d'albums, nous aurions besoin d'utiliser une fonction table, car les fonctions table renvoient leurs résultats sous la forme d'un ensemble de lignes.
 
Exemple 4 – Liaison de schéma
 

 Lorsque vous créez une fonction définie par l'utilisateur qui dépend d'autres objets de la base de données, il est généralement judicieux de lier le schéma à l'UDF. Le schéma de liaison de l'UDF garantit qu'aucune modification ne peut être apportée aux objets sous-jacents qui pourraient potentiellement avoir un impact sur la fonction. 
 

 Par exemple, vous ne pourriez pas supprimer une table qu'une UDF liée au schéma utilise dans sa définition. 
 

 Pour lier un schéma UDF, utilisez WITH SCHEMABINDING dans sa définition. Vous devez également utiliser des noms en deux parties pour tous les objets référencés dans la FDU.
 

 Voici l'exemple précédent réécrit afin qu'il soit lié au schéma :
 
CREATE FUNCTION dbo.ufn_CountAlbums (@ArtistId int) RETURNS smallintWITH SCHEMABINDINGAS BEGIN DECLARE @AlbumCount int ; SELECT @AlbumCount =COUNT(AlbumId) FROM dbo.Albums WHERE ArtistId =@ArtistId; RETURN @AlbumCount;END;
 

 Donc, j'ai changé deux choses par rapport au premier exemple. J'ai ajouté WITH SCHEMABINDING , et j'ai changé Albums vers dbo.Albums .
 

 Maintenant, si quelqu'un essaie de supprimer cette table ou d'y apporter d'autres modifications, il obtiendra une erreur. 
 
Exemple 5 – Chiffrement
 

 Vous pouvez également utiliser WITH ENCRYPTION pour chiffrer la fonction. 
 
CREATE FUNCTION dbo.ufn_CountAlbums (@ArtistId int) RETURNS smallintWITH ENCRYPTIONAS BEGIN DECLARE @AlbumCount int ; SELECT @AlbumCount =COUNT(AlbumId) FROM dbo.Albums WHERE ArtistId =@ArtistId; RETURN @AlbumCount;END;
 
Exemple 6 - Entrée NULL
 

 Lors de l'appel de la fonction, si l'un des arguments est NULL, le corps de la fonction est toujours exécuté. Autrement dit, à moins que vous n'ayez explicitement indiqué RETURNS NULL ON NULL INPUT dans la définition de la fonction. 
 

 Spécifier cette option renverra NULL si l'un des arguments est NULL.
 
CREATE FUNCTION dbo.ufn_CountAlbums (@ArtistId int) RETURNS smallintWITH RETURNS NULL ON NULL INPUTAS BEGIN DECLARE @AlbumCount int; SELECT @AlbumCount =COUNT(AlbumId) FROM dbo.Albums WHERE ArtistId =@ArtistId; RETURN @AlbumCount;END;
 

 Lorsque j'invoque la fonction en utilisant NULL comme argument :
 
SELECT dbo.ufn_CountAlbums(NULL) COMME résultat ;
 

 J'obtiens un résultat différent, selon ce que j'ai spécifié pour cette option.
 

 Voici le résultat lorsque la fonction utilise le paramètre par défaut (CALLED ON NULL INPUT ):
 
+----------+| Résultat ||----------|| 0 |+----------+
 

 Et voici le résultat lorsqu'il utilise RETURNS NULL ON NULL INPUT :
 
+----------+| Résultat ||----------|| NULL |+----------+
 
Exemple 7 – Options multiples
 

 Vous pouvez séparer plusieurs options par une virgule. 
 

 Voici un exemple qui ajoute à la fois le chiffrement et la liaison de schéma à la fonction :
 
CREATE FUNCTION dbo.ufn_CountAlbums (@ArtistId int) RENVOIE smallintAVEC LE CHIFFREMENT, SCHEMABINDINGAS COMMENCE À DÉCLARER @AlbumCount int ; SELECT @AlbumCount =COUNT(AlbumId) FROM dbo.Albums WHERE ArtistId =@ArtistId; RETURN @AlbumCount;END;
 
Exemple 8 - Modifier une fonction
 

 Vous pouvez modifier une UDF scalaire en remplaçant CREATE avec ALTER .
 
ALTER FUNCTION dbo.ufn_CountAlbums (@ArtistId int) RETURNS smallintWITH SCHEMABINDINGAS BEGIN DECLARE @AlbumCount int ; SELECT @AlbumCount =COUNT(AlbumId) FROM dbo.Albums WHERE ArtistId =@ArtistId; RETURN @AlbumCount;END;