CRÉER UNE FONCTION (Transact-SQL)

2025-06-28

S’applique à :SQL Server Azure SQL Database Azure SQL Managed Instance Base de données SQL dans Microsoft Fabric

Crée une fonction définie par l’utilisateur (UDF), qui est une routine d’exécution Transact-SQL ou CLR (Common Language Runtime). Une fonction définie par l’utilisateur accepte des paramètres, effectue une action telle qu’un calcul complexe et renvoie le résultat de cette action sous forme de valeur. La valeur de retour peut être une valeur scalaire (unique) ou une table.

Permet CREATE FUNCTION de créer une routine T-SQL réutilisable qui peut être utilisée de ces manières :

Dans Transact-SQL des déclarations telles que SELECT
Dans les applications qui appellent la fonction
Dans la définition d’une autre fonction définie par l’utilisateur
Pour paramétrer une vue ou améliorer la fonctionnalité d’une vue indexée
Pour définir une colonne dans une table
Pour définir une CHECK contrainte sur un poteau
Pour remplacer une procédure stockée
Utiliser une fonction en ligne comme prédicat de filtre pour une stratégie de sécurité

L’intégration de .NET Framework CLR dans SQL Server est abordée dans cet article. L’intégration CLR ne s’applique pas à Azure SQL Database.

Remarque

Pour Microsoft Fabric Data Warehouse ou Azure Synapse Analytics, consultez CREATE FUNCTION (Azure Synapse Analytics et Microsoft Fabric).

Conseil / Astuce

Vous pouvez spécifier CREATE OR ALTER FUNCTION de créer une fonction si elle n’existe pas par ce nom, ou modifier une fonction existante, dans une seule instruction.

Conventions de la syntaxe Transact-SQL

Syntaxe

Syntaxe des fonctions scalaires Transact-SQL.

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

Syntaxe pour Transact-SQL fonctions table-value en ligne.

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

Syntaxe pour Transact-SQL fonctions tabletable à plusieurs instructions.

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

Syntaxe des clauses de fonction Transact-SQL.

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

Syntaxe des fonctions scalaires CLR.

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

Syntaxe des fonctions table 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>
[ ; ]

Syntaxe des clauses de fonction CLR.

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

Syntaxe OLTP en mémoire pour les fonctions scalaires définies par l’utilisateur compilées en natif.

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

Les arguments

OU ALTER

S’applique à : SQL Server 2016 (13.x) SP 1 et versions ultérieures, ainsi qu’à Azure SQL Database.

Modifie conditionnellement la fonction uniquement si elle existe déjà.

Une syntaxe facultative OR ALTER est disponible pour CLR, à partir de SQL Server 2016 (13.x) SP 1 CU 1.

schema_name

Nom du schéma auquel appartient la fonction définie par l’utilisateur.

function_name

Nom de la fonction définie par l’utilisateur. Les noms de fonction doivent être conformes aux règles d’identification et doivent être uniques au sein de la base de données et de son schéma.

Les parenthèses sont obligatoires après le nom de la fonction, même si aucun paramètre n’est spécifié.

@parameter_name

Paramètre de la fonction définie par l’utilisateur. Un ou plusieurs paramètres peuvent être déclarés.

Une fonction peut avoir un maximum de 2 100 paramètres. La valeur de chaque paramètre déclaré doit être fournie par l’utilisateur lors de l’exécution de la fonction, sauf si une valeur par défaut pour le paramètre est définie.

Spécifiez un nom de paramètre en utilisant le signe arobase (@) comme premier caractère. Le nom du paramètre doit être conforme aux règles d’identification. Les paramètres sont locaux à la fonction ; Les mêmes noms de paramètres peuvent être utilisés dans d’autres fonctions. Les paramètres ne peuvent remplacer que des constantes ; Ils ne peuvent pas être utilisés à la place des noms de table, des noms de colonne ou des noms d’autres objets de base de données.

ANSI_WARNINGS n’est pas respecté lorsque vous transmettez des paramètres dans une procédure stockée, une fonction définie par l’utilisateur ou lorsque vous déclarez et définissez des variables dans une instruction batch. Par exemple, si une variable est définie comme char(3) et qu’une valeur de plus de trois caractères lui est attribuée, les données sont tronquées en fonction de la taille définie, et l’instruction INSERT ou UPDATE réussit.

[ type_schema_name. ] parameter_data_type

Le type de données du paramètre et, éventuellement, le schéma auquel il appartient. Pour Transact-SQL fonctions, tous les types de données, y compris les types CLR définis par l’utilisateur et les types de table définis par l’utilisateur, sont autorisés, à l’exception du type de données timestamp . Pour les fonctions CLR, tous les types de données, y compris les types CLR définis par l’utilisateur, sont autorisés, à l’exception des types de données text, ntext, image, table définie par l’utilisateur et timestamp . Les types non scalaires, cursor et table, ne peuvent pas être spécifiés en tant que type de données de paramètre dans les fonctions Transact-SQL ou CLR.

Si type_schema_name n’est pas spécifié, le moteur de base de données recherche dans scalar_parameter_data_type l’ordre suivant :

Schéma qui contient les noms des types de données système SQL Server.
Le schéma par défaut de l'utilisateur actuel dans la base de données active
Schéma dbo dans la base de données active.

[ = par défaut ]

Valeur par défaut du paramètre. Si une valeur par défaut est définie, la fonction peut être exécutée sans spécifier de valeur pour ce paramètre.

Les valeurs de paramètre par défaut peuvent être spécifiées pour les fonctions CLR, à l’exception des types de données varchar(max) et varbinary(max).

Lorsqu’un paramètre de la fonction a une valeur par défaut, le mot-clé DEFAULT doit être spécifié lors de l’appel de la fonction pour récupérer la valeur par défaut. Ce comportement est différent de l’utilisation de paramètres avec des valeurs par défaut dans des procédures stockées dans lesquelles l’omission du paramètre implique également la valeur par défaut. Cependant, le mot-clé n’est pas requis lors de l’appel DEFAULT d’une fonction scalaire à l’aide de l’instruction EXECUTE .

LECTURE SEULE

Indique que le paramètre ne peut pas être mis à jour ou modifié dans la définition de la fonction. READONLY est requis pour les paramètres de type de table définis par l’utilisateur (TVP) et ne peut pas être utilisé pour tout autre type de paramètre.

return_data_type

Valeur de retour d’une fonction scalaire définie par l’utilisateur. Pour Transact-SQL fonctions, tous les types de données, y compris les types CLR définis par l’utilisateur, sont autorisés, à l’exception du type de données timestamp . Pour les fonctions CLR, tous les types de données, y compris les types CLR définis par l’utilisateur, sont autorisés, à l’exception des types de données text, ntext, image et timestamp . Les types non scalaires, cursor et table, ne peuvent pas être spécifiés en tant que type de données de retour dans les fonctions Transact-SQL ou CLR.

function_body

Spécifie qu’une série d’instructions Transact-SQL, qui ensemble ne produisent pas d’effet secondaire tel que la modification d’une table, définit la valeur de la fonction. function_body est utilisé uniquement dans les fonctions scalaires et les fonctions table-value à instructions multiples (MSTVF).

Dans les fonctions scalaires, function_body est une série d’instructions Transact-SQL qui s’élèvent ensemble jusqu’à une valeur scalaire.

Dans les MSTVF, function_body est une série d’instructions Transact-SQL qui renseignent une TABLE variable de retour.

scalar_expression

Spécifie la valeur scalaire renvoyée par la fonction scalaire.

TABLEAU

Spécifie que la valeur de retour de la fonction table-value (TVF) est une table. Seules les constantes et @local_variables peuvent être transmises aux TVF.

Dans les TVF en ligne, la valeur de TABLE retour est définie par une seule SELECT instruction. Les fonctions en ligne n’ont pas de variables de retour associées.

Dans les fonctions table à plusieurs instructions (MSTVFs), @return_variable est une TABLE variable, utilisée pour stocker et accumuler les lignes qui doivent être retournées comme valeur de la fonction. @ return_variable ne peut être spécifié que pour les fonctions Transact-SQL et non pour les fonctions CLR.

select_stmt

Instruction unique SELECT qui définit la valeur de retour d’une fonction table-value (TVF) en ligne.

COMMANDE (<order_clause>)

Spécifie l’ordre dans lequel les résultats sont renvoyés par la fonction table. Pour plus d’informations, consultez la section Utiliser l’ordre de tri dans les fonctions table CLR plus loin dans cet article.

NOM EXTERNE <method_specifier>assembly_name.class_name. method_name

S’applique à : SQL Server 2008 (10.0.x) SP 1 et versions ultérieures.

Spécifie l’assembly et la méthode auxquels le nom de la fonction créée doit faire référence.

assembly_name - doit correspondre à une valeur de la name colonne SELECT * FROM sys.assemblies;.

Le nom qui a été utilisé sur la CREATE ASSEMBLY déclaration.
class_name - doit correspondre à une valeur de la assembly_name colonne SELECT * FROM sys.assembly_modules;.

Souvent, la valeur contient un point ou un point intégré. Dans ce cas, la syntaxe Transact-SQL exige que la valeur soit délimitée par une paire de crochets ([]), ou par une paire de guillemets doubles ("").
method_name - doit correspondre à une valeur de la method_name colonne SELECT * FROM sys.assembly_modules;.

La méthode doit être statique.

Dans un exemple typique de MyFood.dll, dans lequel tous les types se trouvent dans l’espace de MyFood noms, la EXTERNAL NAME valeur pourrait être MyFood.[MyFood.MyClass].MyStaticMethod.

Par défaut, SQL Server ne peut pas exécuter de code CLR. Vous pouvez créer, modifier et supprimer des objets de base de données qui font référence à des modules d’exécution de langage courant. Toutefois, vous ne pouvez pas exécuter ces références dans SQL Server tant que vous n’avez pas activé l’option clr enabled. Pour activer cette option, utilisez sp_configure. Cette option n'est pas disponible dans une base de données autonome.

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

Définit le type de données de table d’une fonction Transact-SQL. La déclaration de table inclut des définitions de colonne et des contraintes de colonne ou de table. La table est toujours placée dans le groupe de fichiers principal.

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

S’applique à : SQL Server 2008 (10.0.x) SP 1 et versions ultérieures, et Azure SQL Database (préversion dans certaines régions).

Définit les types de données de table pour une fonction CLR. La déclaration de table inclut uniquement les noms de colonnes et les types de données. La table est toujours placée dans le groupe de fichiers principal.

NULL | NOT NULL

Pris en charge uniquement pour les fonctions scalaires définies par l’utilisateur compilées en natif. Pour plus d’informations, consultez Fonctions User-Defined scalaires pour In-Memory OLTP.

NATIVE_COMPILATION

Indique si une fonction définie par l’utilisateur est compilée en mode natif. Cet argument est requis pour les fonctions scalaires définies par l’utilisateur compilées en natif.

COMMENCEZ ATOMIC AVEC

Obligatoire, et uniquement pris en charge, pour les fonctions scalaires définies par l’utilisateur compilées en natif. Pour plus d’informations, consultez Blocs atomiques dans les procédures natives.

SCHEMABINDING

L’argument SCHEMABINDING est requis pour les fonctions scalaires définies par l’utilisateur compilées en natif.

EXECUTER EN TANT QUE

EXECUTE AS est requis pour les fonctions scalaires définies par l’utilisateur compilées en natif.

< > function_option ::= et <clr_function_option> ::=

Spécifie que la fonction dispose d’une ou plusieurs des options suivantes.

CHIFFREMENT

S’applique à : SQL Server 2008 (10.0.x) SP 1 et versions ultérieures.

Indique que le Moteur de base de données convertit le texte d’origine de l’instruction CREATE FUNCTION dans un format obfusqué. Le résultat de l’obfuscation n’est pas directement visible dans les vues de catalogue. Les utilisateurs qui n’ont pas accès aux tables système ou aux fichiers de base de données ne peuvent pas récupérer le texte obfusqué. Toutefois, le texte est disponible pour les utilisateurs privilégiés qui peuvent soit accéder aux tables système via la connexion de diagnostic pour les administrateurs de base de données , soit accéder directement aux fichiers de base de données. En outre, les utilisateurs qui peuvent attacher un débogueur au processus serveur peuvent récupérer la procédure d’origine à partir de la mémoire au moment de l’exécution. Pour plus d’informations sur l’accès aux métadonnées système, consultez Configuration de la visibilité des métadonnées.

L’utilisation de cette option empêche la publication de la fonction dans le cadre de la réplication SQL Server. Cette option ne peut pas être spécifiée pour les fonctions CLR.

SCHEMABINDING

Spécifie que la fonction est liée aux objets de base de données qu’elle référence. Lorsque SCHEMABINDING est spécifié, les objets de base ne peuvent pas être modifiés d’une manière qui affecterait la définition de la fonction. La définition de la fonction elle-même doit d’abord être modifiée ou supprimée pour supprimer les dépendances sur l’objet à modifier.

La liaison de la fonction aux objets qu’elle référence n’est supprimée que lorsque l’une des actions suivantes se produit :

La fonction est supprimée.
La fonction est modifiée en utilisant l’instruction ALTER avec l’option SCHEMABINDING non spécifiée.

Une fonction ne peut être liée à un schéma que si les conditions suivantes sont remplies :

Il s’agit d’une fonction Transact-SQL.
Les fonctions et les vues définies par l’utilisateur référencées par la fonction sont également liées au schéma.
Les objets référencés par la fonction sont référencés à l’aide d’un nom en deux parties.
La fonction et les objets qu’elle référence appartiennent à la même base de données.
L’utilisateur qui a exécuté l’instruction CREATE FUNCTION dispose REFERENCES d’une autorisation sur les objets de base de données référencés par la fonction.

RENVOIE NULL SUR L’ENTRÉE NULL | APPELÉ SUR UNE ENTRÉE NULL

Spécifie l’attribut OnNULLCall d’une fonction scalaire. S’il n’est pas spécifié, CALLED ON NULL INPUT est implicite par défaut. En d’autres termes, le corps de la fonction s’exécute même s’il NULL est passé en argument.

Si RETURNS NULL ON NULL INPUT est spécifié dans une fonction CLR, il indique que SQL Server peut retourner NULL lorsque l’un des arguments qu’il reçoit est NULL, sans appeler le corps de la fonction. Si la méthode d’une fonction CLR spécifiée dans <method_specifier> possède déjà un attribut personnalisé qui indique RETURNS NULL ON NULL INPUT, mais que l’instruction CREATE FUNCTION indique CALLED ON NULL INPUT, l’instruction CREATE FUNCTION est prioritaire. L’attribut OnNULLCall ne peut pas être spécifié pour les fonctions table CLR.

EXECUTER EN TANT QUE

Spécifie le contexte de sécurité dans lequel la fonction définie par l’utilisateur est exécutée. Par conséquent, vous pouvez contrôler le compte d’utilisateur que SQL Server utilise pour valider les autorisations sur tous les objets de base de données référencés par la fonction.

EXECUTE AS ne peut pas être spécifié pour les fonctions table-value en ligne.

Pour plus d’informations, consultez la clause EXECUTE AS (Transact-SQL).

EN LIGNE = { ACTIVÉ | DÉSACTIVÉ }

S’applique à : SQL Server 2019 (15.x) et versions ultérieures, ainsi qu’Azure SQL Database.

Spécifie si cette FDU scalaire doit être incorporée ou non. Cette clause s’applique uniquement aux fonctions scalaires définies par l’utilisateur. La INLINE clause n’est pas obligatoire. Si la INLINE clause n’est pas spécifiée, elle est automatiquement définie sur ON ou OFF en fonction de la fonction définie par l’utilisateur ou non. Si INLINE = ON est spécifié mais que la fonction définie par l’utilisateur n’est pas inlinable, une erreur est générée. Pour plus d’informations, consultez d’inlining UDF Scalar.

< > column_definition ::=

Définit le type de données de la table. La déclaration de table inclut des définitions de colonnes et des contraintes. Pour les fonctions CLR, seules column_name et data_type peuvent être spécifiées.

column_name

Nom d’une colonne de la table. Les noms de colonne doivent être conformes aux règles d’identification et doivent être uniques dans la table. column_name peut comporter de 1 à 128 caractères.

data_type

Spécifie le type de données de colonne. Pour Transact-SQL fonctions, tous les types de données, y compris les types CLR définis par l’utilisateur, sont autorisés, à l’exception de timestamp. Pour les fonctions CLR, tous les types de données, y compris les types CLR définis par l’utilisateur, sont autorisés, à l’exception de text, ntext, image, char, varchar, varchar(max) et timestamp. Le curseur de type non scalaire ne peut pas être spécifié en tant que type de données de colonne dans les fonctions Transact-SQL ou CLR.

constant_expression PAR DÉFAUT

Spécifie la valeur fournie pour la colonne lorsque vous n'avez pas spécifié explicitement de valeur lors d'une insertion. constant_expression est une valeur constante, NULLou une valeur de fonction système. DEFAULT Les définitions peuvent être appliquées à n’importe quelle colonne, à l’exception de celles qui ont la IDENTITY propriété. DEFAULT ne peut pas être spécifié pour les fonctions table CLR.

COLLATE collation_name

Indique le classement de la colonne. Si l'argument n'est pas spécifié, c'est le classement par défaut de la base de données qui est affecté à la colonne. Le nom du classement peut être un nom de classement Windows ou SQL. Pour obtenir la liste des classements et plus d’informations sur ceux-ci, consultez Nom du classement Windows (Transact-SQL) et Nom du classement SQL Server (Transact-SQL ).

La COLLATE clause peut être utilisée pour modifier uniquement le classement des colonnes des types de données char, varchar, nchar et nvarchar . COLLATE ne peut pas être spécifié pour les fonctions table CLR.

ROWGUIDCOL

Indique que la nouvelle colonne est une colonne d’identificateur unique global de ligne. Une seule colonne uniqueidentifier par table peut être désignée comme ROWGUIDCOL colonne. La ROWGUIDCOL propriété ne peut être affectée qu’à une colonne uniqueidentifier .

La ROWGUIDCOL propriété n’impose pas l’unicité des valeurs stockées dans la colonne. Il ne génère pas non plus automatiquement de valeurs pour les nouvelles lignes insérées dans la table. Pour générer des valeurs uniques pour chaque colonne, utilisez la NEWID fonction on INSERT instructions. Une valeur par défaut peut être spécifiée ; Toutefois, ne NEWID peut pas être spécifié par défaut.

IDENTITÉ

Indique que la nouvelle colonne est une colonne d'identité. Lorsqu’une nouvelle ligne est ajoutée à la table, SQL Server fournit une valeur incrémentielle unique pour la colonne. Les colonnes d’identité sont généralement utilisées avec PRIMARY KEY des contraintes pour servir d’identificateur de ligne unique pour la table. La IDENTITY propriété peut être affectée aux colonnes tinyint, smallint, int, bigint, decimal(p,0) ou numeric(p,0). Une seule colonne d'identité peut être créée par table. Les valeurs par défaut et DEFAULT les contraintes liées ne peuvent pas être utilisées avec une colonne d’identité. Vous devez spécifier à la fois la graine et l’incrément ou ni l’un ni l’autre. Si vous n'en spécifiez aucun, la valeur par défaut est (1,1).

IDENTITY ne peut pas être spécifié pour les fonctions table CLR.

Graines

Valeur entière à attribuer à la première ligne de la table.

augmentation

Valeur entière à ajouter à la valeur de départ des lignes successives de la table.

< > column_constraint ::= et <table_constraint> ::=

Définit la contrainte d’une colonne ou d’une table spécifiée. Pour les fonctions CLR, le seul type de contrainte autorisé est NULL. Les contraintes nommées ne sont pas autorisées.

NULL | NOT NULL

Détermine si les valeurs nulles sont autorisées dans la colonne. NULL n’est pas strictement une contrainte, mais peut être spécifié comme NOT NULL. NOT NULL ne peut pas être spécifié pour les fonctions table CLR.

CLÉ PRIMAIRE

Contrainte qui applique l’intégrité de l’entité pour une colonne spécifiée par le biais d’un index unique. Dans les fonctions définies par l’utilisateur basées sur une table, la PRIMARY KEY contrainte ne peut être créée que sur une seule colonne par table. PRIMARY KEY ne peut pas être spécifié pour les fonctions table CLR.

UNIQUE

Contrainte assurant l’intégrité de l’entité d’une colonne ou de plusieurs colonnes spécifiées au moyen d’un index unique. Une table peut avoir plusieurs UNIQUE contraintes. UNIQUE ne peut pas être spécifié pour les fonctions table CLR.

CLUSTERED et NONCLUSTERED

Indiquez qu’un index cluster ou non-cluster est créé pour la PRIMARY KEY contrainte or UNIQUE . PRIMARY KEY contraintes utilisent CLUSTERED, et UNIQUE les contraintes utilisent NONCLUSTERED.

CLUSTERED ne peut être spécifié que pour une seule contrainte. Si CLUSTERED est spécifié pour une UNIQUE contrainte et qu’une PRIMARY KEY contrainte est également spécifiée, le PRIMARY KEYNONCLUSTEREDutilise .

CLUSTERED et NONCLUSTERED ne peut pas être spécifié pour les fonctions table CLR.

VÉRIFIER

Contrainte qui assure l'intégrité du domaine en limitant les valeurs possibles pouvant être entrées dans une ou plusieurs colonnes. CHECK Les contraintes ne peuvent pas être spécifiées pour les fonctions table CLR.

logical_expression

Expression logique qui renvoie TRUE ou FALSE.

< > computed_column_definition ::=

Spécifie une colonne calculée. Pour plus d’informations sur les colonnes calculées, consultez CREATE TABLE (Transact-SQL).

column_name

Nom de la colonne calculée.

computed_column_expression

Expression définissant la valeur d’une colonne calculée.

< > index_option ::=

Spécifie les options d’index pour l’index PRIMARY KEY ou UNIQUE . Pour plus d’informations sur les options d’index, consultez CREATE INDEX (Transact-SQL).

PAD_INDEX = { ON | OFF }

Spécifie le remplissage de l'index. La valeur par défaut est OFF.

FILLFACTOR = fillfactor

Spécifie un pourcentage qui indique le niveau de remplissage de chaque page d’index par le moteur de base de données lors de la création ou de la modification de l’index. fillfactor doit être une valeur entière comprise entre 1 et 100. La valeur par défaut est 0.

IGNORE_DUP_KEY = { ON | OFF }

Spécifie la réponse d'erreur lorsqu'une opération d'insertion essaie d'insérer des valeurs de clés en double dans un index unique. L’option IGNORE_DUP_KEY s’applique uniquement aux opérations d’insertion après la création ou la régénération de l’index. La valeur par défaut est OFF.

STATISTICS_NORECOMPUTE = { ON | OFF }

Spécifie si les statistiques de distribution sont recalculées. La valeur par défaut est OFF.

ALLOW_ROW_LOCKS = { ON | OFF }

Spécifie si les verrous de ligne sont autorisés. La valeur par défaut est ON.

ALLOW_PAGE_LOCKS = { ON | OFF }

Spécifie si les verrous de page sont autorisés. La valeur par défaut est ON.

Meilleures pratiques

Si une fonction définie par l’utilisateur n’est pas créée avec la clause, les SCHEMABINDING modifications apportées aux objets sous-jacents peuvent affecter la définition de la fonction et produire des résultats inattendus lorsqu’elle est appelée. Nous vous recommandons d’implémenter l’une des méthodes suivantes pour vous assurer que la fonction ne devient pas obsolète en raison des modifications apportées à ses objets sous-jacents :

Spécifiez la WITH SCHEMABINDING clause lors de la création de la fonction. Cette option garantit que les objets référencés dans la définition de la fonction ne peuvent pas être modifiés, sauf si la fonction est également modifiée.
Exécute la procédure stockée sp_refreshsqlmodule après avoir modifié un objet spécifié dans la définition de la fonction.

Pour plus d’informations et pour obtenir des considérations sur les performances des fonctions table en ligne (TVF en ligne) et des fonctions table à instructions multiples (MSTVF), consultez Création de fonctions définies par l’utilisateur (moteur de base de données).

Types de données

Si des paramètres sont spécifiés dans une fonction CLR, ils doivent être de type SQL Server tels que définis précédemment pour scalar_parameter_data_type. Pour plus d’informations sur la comparaison des types de données système SQL Server aux types de données d’intégration CLR ou aux types de données d’exécution du langage commun .NET Framework, consultez Mappage des données de paramètre CLR.

Pour que SQL Server référence la méthode correcte lorsqu’elle est surchargée dans une classe, la méthode indiquée dans <method_specifier> doit avoir les caractéristiques suivantes :

Recevoir le même nombre de paramètres que celui spécifié dans [ , ...n ].
Recevez tous les paramètres par valeur, et non par référence.
Utilisez des types de paramètres compatibles avec les types spécifiés dans la fonction SQL Server.

Si le type de données de retour de la fonction CLR spécifie un type de table (RETURNS TABLE), le type de données de retour de la méthode dans <method_specifier> doit être de type IEnumerator ou IEnumerable, et suppose que l’interface est implémentée par le créateur de la fonction. Contrairement aux fonctions Transact-SQL, les fonctions CLR ne peuvent pas inclure PRIMARY KEY, UNIQUEou CHECK des contraintes dans <table_type_definition>. Les types de données des colonnes spécifiées dans <table_type_definition> doivent correspondre aux types des colonnes correspondantes du jeu de résultats renvoyé par la méthode in <method_specifier> au moment de l’exécution. Cette vérification de type n’est pas effectuée au moment de la création de la fonction.

Pour plus d’informations sur la programmation des fonctions CLR, consultez Fonctions User-Defined CLR.

Remarques

Les fonctions scalaires peuvent être appelées lorsque des expressions scalaires sont utilisées, ce qui inclut les colonnes calculées et CHECK les définitions de contraintes. Les fonctions scalaires peuvent également être exécutées à l’aide de l’instruction EXECUTE (Transact-SQL). Les fonctions scalaires doivent être appelées en utilisant au moins le nom en deux parties de la fonction (<schema>.<function>). Pour plus d’informations sur les noms en plusieurs parties, consultez Transact-SQL Conventions de syntaxe (Transact-SQL). Les fonctions table-value peuvent être appelées lorsque les expressions de table sont autorisées dans la FROM clause des SELECTinstructions , INSERT, UPDATE, or DELETE . Pour plus d’informations, consultez Exécuter des fonctions définies par l’utilisateur.

Interopérabilité

Les instructions suivantes sont valides dans une fonction :

Instructions d’affectation.
Instructions de contrôle de flux, à l’exception TRY...CATCH des instructions.
DECLARE Instructions définissant des variables de données locales et des curseurs locaux.
SELECT Instructions contenant des listes de sélection avec des expressions qui attribuent des valeurs à des variables locales.
Opérations de curseur référençant les curseurs locaux qui sont déclarés, ouverts, fermés et désalloués dans la fonction. Seules les FETCH instructions qui attribuent des valeurs à des variables locales à l’aide de la INTO clause sont autorisées, tandis FETCH que les instructions qui renvoient des données au client ne sont pas autorisées.
INSERT, UPDATEet DELETE les instructions modifiant les variables de table locales.
EXECUTE instructions appelant des procédures stockées étendues.

Pour plus d’informations, consultez Créer des fonctions définies par l’utilisateur (moteur de base de données).

Interopérabilité des colonnes calculées

Les fonctions ont les propriétés suivantes. Les valeurs de ces propriétés déterminent si les fonctions peuvent être utilisées dans des colonnes calculées qui peuvent être conservées ou indexées.

Propriété	Descriptif	Remarques
`IsDeterministic`	La fonction est déterministe ou non déterministe.	L’accès local aux données est autorisé dans les fonctions déterministes. Par exemple, les fonctions qui renvoient toujours le même résultat chaque fois qu’elles sont appelées à l’aide d’un ensemble spécifique de valeurs d’entrée et avec le même état de la base de données sont étiquetées déterministes.
`IsPrecise`	La fonction est précise ou imprécise.	Les fonctions imprécises contiennent des opérations telles que des opérations en virgule flottante.
`IsSystemVerified`	Les propriétés de précision et de déterminisme de la fonction peuvent être vérifiées par SQL Server.
`SystemDataAccess`	La fonction accède aux données système (catalogues système ou tables système virtuelles) dans l’instance locale de SQL Server.
`UserDataAccess`	La fonction accède aux données utilisateur dans l’instance locale de SQL Server.	Inclut les tables définies par l’utilisateur et les tables temporaires, mais pas les variables de table.

Les propriétés de précision et de déterminisme de Transact-SQL fonctions sont déterminées automatiquement par SQL Server. Les propriétés d’accès aux données et de déterminisme des fonctions CLR peuvent être spécifiées par l’utilisateur. Pour plus d’informations, consultez Intégration CLR : attributs personnalisés pour les routines CLR.

Pour afficher les valeurs actuelles de ces propriétés, utilisez OBJECTPROPERTYEX (Transact-SQL).

Important

Les fonctions doivent être créées avec SCHEMABINDING pour être déterministes.

Une colonne calculée qui appelle une fonction définie par l’utilisateur peut être utilisée dans un index lorsque la fonction définie par l’utilisateur a les valeurs de propriété suivantes :

IsDeterministic est true
IsSystemVerified is true (sauf si la colonne calculée est conservée)
UserDataAccess est false
SystemDataAccess est false

Pour plus d’informations, consultez Index sur les colonnes calculées.

Appel de procédures stockées étendues à partir de fonctions

La procédure stockée étendue, lorsqu’elle est appelée à partir de l’intérieur d’une fonction, ne peut pas renvoyer d’ensembles de résultats au client. Toutes les API ODS qui renvoient des jeux de résultats au client renvoient FAIL. La procédure stockée étendue peut se reconnecter à une instance de SQL Server ; Toutefois, il ne doit pas essayer de joindre la même transaction que la fonction qui a appelé la procédure stockée étendue.

À l’instar des appels à partir d’un lot ou d’une procédure stockée, la procédure stockée étendue est exécutée dans le contexte du compte de sécurité Windows sous lequel SQL Server s’exécute. Le propriétaire de la procédure stockée doit tenir compte de ce scénario lorsqu’il accorde EXECUTE une autorisation aux utilisateurs.

Limites

Les fonctions définies par l’utilisateur ne permettent pas d’exécuter des actions qui modifient l’état des bases de données.

Les fonctions définies par l’utilisateur ne peuvent pas contenir de clause OUTPUT INTO avec une table comme cible.

Les instructions Service Broker suivantes ne peuvent pas être incluses dans la définition d’une fonction Transact-SQL définie par l’utilisateur :

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

Les fonctions définies par l’utilisateur peuvent être imbriquées ; autrement dit, une fonction définie par l’utilisateur peut appeler une autre. Le niveau d’imbrication est incrémenté lorsque la fonction appelée démarre l’exécution et décrémentée lorsque la fonction appelée termine l’exécution. Les fonctions définies par l’utilisateur peuvent être imbriquées jusqu’à 32 niveaux. Le dépassement des niveaux maximal d’imbrication entraîne l’échec de l’ensemble de la chaîne de fonctions appelantes. Toute référence au code managé à partir d’une fonction Transact-SQL définie par l’utilisateur compte comme un niveau par rapport à la limite d’imbrication de 32 niveaux. Les méthodes appelées à partir du code managé ne comptent pas par rapport à cette limite.

Utiliser l’ordre de tri dans les fonctions table CLR

Lorsque vous utilisez la clause dans des ORDER fonctions table CLR, suivez ces instructions :

Vous devez vous assurer que les résultats sont toujours classés dans l’ordre spécifié. Si les résultats ne sont pas dans l’ordre spécifié, SQL Server génère un message d’erreur lors de l’exécution de la requête.
Si une ORDER clause est spécifiée, la sortie de la fonction table-value doit être triée en fonction du classement de la colonne (explicite ou implicite). Par exemple, si le classement des colonnes est chinois, les résultats renvoyés doivent être triés selon les règles de tri chinoises. (Le classement est spécifié soit dans le DDL pour la fonction table, soit obtenu à partir du classement de base de données.)
SQL Server vérifie toujours la clause si elle ORDER est spécifiée, tout en renvoyant des résultats, que le processeur de requêtes l’utilise ou non pour effectuer d’autres optimisations. N’utilisez la ORDER clause que si vous savez qu’elle est utile au processeur de requêtes.
Le processeur de requêtes SQL Server tire automatiquement parti de la clause dans les ORDER cas suivants :
- Insérez des requêtes dont la ORDER clause est compatible avec un index.
- ORDER BY clauses qui sont compatibles avec la ORDER clause.
- Agrégats, où GROUP BY est compatible avec ORDER la clause.
- DISTINCT agrégats où les colonnes distinctes sont compatibles avec la ORDER clause.

La ORDER clause ne garantit pas l’ordre des résultats lorsqu’une SELECT requête est exécutée, sauf si elle est ORDER BY également spécifiée dans la requête. Voir sys.function_order_columns (Transact-SQL) pour plus d’informations sur la recherche de colonnes incluses dans l’ordre de tri pour les fonctions table.

Métadonnées

Le tableau suivant répertorie les vues du catalogue système que vous pouvez utiliser pour renvoyer des métadonnées sur les fonctions définies par l’utilisateur.

Vue système	Descriptif
sys.sql_modules	Voir l’exemple E dans la section Exemples.
sys.assembly_modules	Affiche des informations sur les fonctions CLR définies par l’utilisateur.
sys.parameters	Affiche des informations sur les paramètres définis dans les fonctions définies par l’utilisateur.
sys.sql_dépendances_expression_	Affiche les objets sous-jacents référencés par une fonction.

Autorisations

Nécessite l’autorisation CREATE FUNCTION dans la base de données et l’autorisation ALTER sur le schéma dans lequel la fonction est créée. Si la fonction spécifie un type défini par l’utilisateur, elle nécessite l’autorisation EXECUTE sur le type.

Exemples

Pour plus d’exemples et d’informations sur les performances des fonctions définies par l’utilisateur, consultez Créer des fonctions définies par l’utilisateur (moteur de base de données).

Un. Utiliser une fonction scalaire définie par l’utilisateur qui calcule la semaine ISO

L’exemple suivant crée la fonction ISOweekdéfinie par l’utilisateur . Cette fonction prend un argument date et calcule le numéro de semaine ISO. Pour que cette fonction calcule correctement, SET DATEFIRST 1 elle doit être appelée avant d’être appelée.

L’exemple montre également l’utilisation de la clause EXECUTE AS (Transact-SQL) pour spécifier le contexte de sécurité dans lequel une procédure stockée peut être exécutée. Dans l’exemple, l’option CALLER spécifie que la procédure est exécutée dans le contexte de l’utilisateur qui l’appelle. Les autres options que vous pouvez spécifier sont SELF, OWNERet user_name.

Voici l’appel de fonction. DATEFIRST est défini sur 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';

Voici l'ensemble des résultats.

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

B. Création d’une fonction table-value inline

L’exemple suivant retourne une fonction table en ligne dans la base de données AdventureWorks2022. Il renvoie trois colonnes ProductID, Name, et l’agrégation des totaux cumulatifs de l’année par magasin pour YTD Total chaque produit vendu au magasin.

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

Pour appeler la fonction, exécutez cette requête.

SELECT * FROM Sales.ufn_SalesByStore (602);

Chapitre C. Création d’une fonction table-value à plusieurs instructions

L’exemple suivant crée la fonction fn_FindReports(InEmpID) table-value dans la AdventureWorks2022 base de données. Lorsqu’elle est fournie avec un ID d’employé valide, la fonction renvoie une table qui correspond à tous les employés qui relèvent de l’employé, directement ou indirectement. La fonction utilise une expression de table commune (CTE) récursive pour produire la liste hiérarchique des employés. Pour plus d’informations sur les CTE récursifs, consultez WITH 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. Création d’une fonction CLR

L’exemple crée la fonction len_sCLR . Avant la création de la fonction, l’assembly SurrogateStringFunction.dll est enregistré dans la base de données locale.

S’applique à : SQL Server 2008 (10.0.x) SP 1 et versions ultérieures.

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

Pour obtenir un exemple de création d’une fonction table CLR, consultez Fonctions Table-Valued CLR.

E. Afficher la définition des fonctions définies par l’utilisateur

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

La définition des fonctions créées à l’aide de l’option ne peut pas être affichée à l’aide ENCRYPTION de sys.sql_modules; cependant, d’autres informations sur les fonctions chiffrées sont affichées.

Partager via

CRÉER UNE FONCTION (Transact-SQL)

Syntaxe

Les arguments

OU ALTER

schema_name

function_name

@parameter_name

[ type_schema_name. ] parameter_data_type

[ = par défaut ]

LECTURE SEULE

return_data_type

function_body

scalar_expression

TABLEAU

select_stmt

COMMANDE (<order_clause>)

NOM EXTERNE <method_specifier>assembly_name.class_name. method_name

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

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

NULL | NOT NULL

NATIVE_COMPILATION

COMMENCEZ ATOMIC AVEC

SCHEMABINDING

EXECUTER EN TANT QUE

< > function_option ::= et <clr_function_option> ::=

CHIFFREMENT

SCHEMABINDING

RENVOIE NULL SUR L’ENTRÉE NULL | APPELÉ SUR UNE ENTRÉE NULL

EXECUTER EN TANT QUE

EN LIGNE = { ACTIVÉ | DÉSACTIVÉ }

< > column_definition ::=

column_name

data_type

constant_expression PAR DÉFAUT

COLLATE collation_name

ROWGUIDCOL

IDENTITÉ

Graines

augmentation

< > column_constraint ::= et <table_constraint> ::=

NULL | NOT NULL

CLÉ PRIMAIRE

UNIQUE

CLUSTERED et NONCLUSTERED

VÉRIFIER

logical_expression

< > computed_column_definition ::=

column_name

computed_column_expression

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

Meilleures pratiques

Types de données

Remarques

Interopérabilité

Interopérabilité des colonnes calculées

Appel de procédures stockées étendues à partir de fonctions

Limites

Utiliser l’ordre de tri dans les fonctions table CLR

Métadonnées

Autorisations

Exemples

Un. Utiliser une fonction scalaire définie par l’utilisateur qui calcule la semaine ISO

B. Création d’une fonction table-value inline

Chapitre C. Création d’une fonction table-value à plusieurs instructions

D. Création d’une fonction CLR

E. Afficher la définition des fonctions définies par l’utilisateur

Contenu connexe

Commentaires

Ressources supplémentaires