CREATE FUNCTION |
Crée une fonction |
|---|---|
| PostgreSQL | |
Syntaxe
|
CREATE FUNCTION name ( [ [ argmode ] [ argname ] argtype [ { DEFAULT | = } default_expr ] [, ...] ] ) [ RETURNS rettype | RETURNS TABLE ( column_name column_type [, ...] ) ] { LANGUAGE lang_name | TRANSFORM { FOR TYPE type_name } [, ... ] | WINDOW | { IMMUTABLE | STABLE | VOLATILE } | [ NOT ] LEAKPROOF | { CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT } | { [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER } | PARALLEL { UNSAFE | RESTRICTED | SAFE } | COST execution_cost | ROWS result_rows | SET configuration_parameter { TO value | = value | FROM CURRENT } | AS 'definition' | AS 'obj_file', 'link_symbol' } ... [ WITH ( attribute [, ...] ) ] |
Paramètres
| Nom | Description | |
|---|---|---|
| name | Ce paramètre permet d'indiquer le nom (éventuellement qualifié par le schéma) de la fonction à créer. | |
| argmode | Ce paramètre permet d'indiquer le mode d'un paramètre : IN, OUT, INOUT ou VARIADIC. S'il est omis, la valeur par défaut est IN. Seuls les paramètres OUT peuvent suivre un paramètre VARIADIC. De plus, les paramètres OUT et INOUT ne peuvent pas être utilisés avec la notation RETURNS TABLE. | |
| argname | Ce paramètre permet d'indiquer le nom d'un paramètre. Certains langages (dont SQL et PL/pgSQL) vous permettent d'utiliser le nom dans le corps de la fonction. Pour d'autres langages, le nom d'un paramètre d'entrée n'est qu'une documentation supplémentaire, en ce qui concerne la fonction elle-même ; mais vous pouvez utiliser des noms de paramètres d'entrée lors de l'appel d'une fonction pour améliorer la lisibilité. Dans tous les cas, le nom d'un paramètre de sortie est significatif, car il définit le nom de la colonne dans le type de ligne de résultat. (Si vous omettez le nom d'un paramètre de sortie, le système choisira un nom de colonne par défaut.) | |
| argtype | Ce paramètre permet d'indiquer le(s) type(s) de données des paramètres de la fonction (éventuellement qualifiés de schéma), le cas échéant. Les types de paramètres peuvent être des types de base, composites ou de domaine, ou peuvent référencer le type d'une colonne de table. Selon le langage d'implémentation, il peut également être autorisé de spécifier des «pseudo-types» tels que cstring. Les pseudo-types indiquent que le type de paramètres réel est soit incomplètement spécifié, soit en dehors de l'ensemble des types de données SQL ordinaires. Le type d'une colonne est référencé en écrivant table_name.column_name%TYPE. L'utilisation de cette fonctionnalité peut parfois aider à rendre une fonction indépendante des modifications apportées à la définition d'une table. | |
| default_expr | Ce paramètre permet d'indiquer une expression à utiliser comme valeur par défaut si le paramètre n'est pas spécifié. L'expression doit être coercitive au type d'argument du paramètre. Seuls les paramètres d'entrée (y compris INOUT) peuvent avoir une valeur par défaut. Tous les paramètres d'entrée suivant un paramètre avec une valeur par défaut doivent également avoir des valeurs par défaut. | |
| rettype | Ce paramètre permet d'indiquer le type de données de retour (éventuellement qualifié de schéma). Le type de retour peut être un type de base, composite ou de domaine, ou peut référencer le type d'une colonne de table. Selon le langage d'implémentation, il peut également être autorisé de spécifier des «pseudo-types» tels que cstring. Si la fonction n'est pas censée renvoyer une valeur, spécifiez void comme type de retour. Lorsqu'il existe des paramètres OUT ou INOUT, la clause RETURNS peut être omise. S'il est présent, il doit être en accord avec le type de résultat impliqué par les paramètres de sortie : RECORD s'il existe plusieurs paramètres de sortie, ou le même type que le paramètre de sortie unique. Le modificateur SETOF indique que la fonction renverra un ensemble d'éléments plutôt qu'un seul élément. Le type d'une colonne est référencé en écrivant table_name.column_name%TYPE. | |
| column_name | Ce paramètre permet d'indiquer le nom d'une colonne de sortie dans la syntaxe RETURNS TABLE. C'est effectivement une autre façon de déclarer un paramètre OUT nommé, sauf que RETURNS TABLE implique également RETURNS SETOF. | |
| column_type | Ce paramètre permet d'indiquer le type de données d'une colonne de sortie dans la syntaxe RETURNS TABLE. | |
| lang_name | Ce paramètre permet d'indiquer le nom du langage dans lequel la fonction est implémentée. Il peut s'agir de sql, c, internal, ou le nom d'un langage procédural défini par l'utilisateur, par exemple, plpgsql. Mettre le nom entre guillemets simples est déconseillé et nécessite une correspondance de la casse. | |
| TRANSFORM { FOR TYPE type_name } [, ... ] } | Ce paramètre permet d'indiquer les listes transformant un appel à la fonction doivent s'appliquer. Les transformations convertissent entre les types SQL et les types de données spécifiques au langage ; voir CREATE TRANSFORM. Les implémentations de langage procédural ont généralement une connaissance codée en dur des types intégrés, ils n'ont donc pas besoin d'être répertoriés ici. Si une implémentation de langage procédural ne sait pas comment gérer un type et qu'aucune transformation n'est fournie, elle reviendra à un comportement par défaut pour convertir les types de données, mais cela dépend de l'implémentation. | |
| WINDOW | Ce paramètre permet d'indiquer que la fonction est une fonction de fenêtre plutôt qu'une fonction simple. Ceci n'est actuellement utile que pour les fonctions écrites en C. L'attribut WINDOW ne peut pas être modifié lors du remplacement d'une définition de fonction existante. | |
| IMMUTABLE | Ce paramètre permet d'indiquer que la fonction ne peut pas modifier la base de données et renvoie toujours le même résultat lorsqu'on lui donne les mêmes valeurs de paramètre ; c'est-à-dire qu'il ne fait pas de recherche dans la base de données et n'utilise pas d'informations n'étant pas directement présentes dans sa liste de paramètres. Si cette option est donnée, tout appel de la fonction avec des arguments entièrement constants peut être immédiatement remplacé par la valeur de la fonction. | |
| STABLE | Ce paramètre permet d'indiquer que la fonction ne peut pas modifier la base de données et qu'au cours d'un seul balayage de table, elle renverra systématiquement le même résultat pour les mêmes valeurs d'argument, mais que son résultat pourrait changer d'une instruction SQL à l'autre. C'est la sélection appropriée pour les fonctions dont les résultats dépendent des recherches dans la base de données, des variables de paramètres (telles que le fuseau horaire actuel),... (Ceci est inapproprié pour les déclencheurs AFTER souhaitant interroger les lignes modifiées par la commande actuelle.) La famille de fonctions current_timestamp est qualifiée de stable, car leurs valeurs ne changent pas au cours d'une transaction. | |
| VOLATILE | Ce paramètre permet d'indiquer que la valeur de la fonction peut changer même au cours d'un seul balayage de table, de sorte qu'aucune optimisation ne peut être effectuée. Relativement peu de fonctions de base de données sont volatiles dans ce sens ; quelques exemples sont random(), currval(), timeofday(). Mais notez que toute fonction ayant des effets secondaires doit être classée volatile, même si son résultat est assez prévisible, pour éviter que les appels ne soient optimisés à distance ; un exemple est setval(). | |
| LEAKPROOF | Ce paramètre permet d'indiquer que la fonction n'a pas d'effets secondaires. Il ne révèle aucune information sur ses paramètres autre que par sa valeur de retour. Par exemple, une fonction renvoyant un message d'erreur pour certaines valeurs de paramètres mais pas pour d'autres, ou incluant les valeurs de paramètres dans un message d'erreur, n'est pas étanche. Cela affecte la façon dont le système exécute les requêtes sur les vues créées avec l'option security_barrier ou les tables avec la sécurité au niveau des lignes activée. Le système appliquera les conditions des politiques de sécurité et des vues des barrières de sécurité avant toute condition fournie par l'utilisateur à partir de la requête elle-même contenant des fonctions non étanches, afin d'empêcher l'exposition accidentelle des données. Les fonctions et les opérateurs marqués comme étanches sont supposés être dignes de confiance et peuvent être exécutés avant les conditions des politiques de sécurité et des vues des barrières de sécurité. De plus, les fonctions ne prenant pas de paramètres ou ne recevant aucun paramètre de la vue ou de la table de barrière de sécurité n'ont pas besoin d'être marquées comme étanches pour être exécutées avant les conditions de sécurité. | |
| CALLED ON NULL INPUT | Ce paramètre permet d'indiquer que la fonction sera appelée normalement lorsque certains de ses paramètres sont nuls. Il est alors de la responsabilité de l'auteur de la fonction de vérifier les valeurs nulles si nécessaire et de répondre de manière appropriée. | |
| RETURNS NULL ON NULL INPUT STRICT |
Ce paramètre permet d'indiquer la réaction. RETURNS NULL ON NULL INPUT ou STRICT indique que la fonction renvoie toujours null chaque fois que l'un de ses paramètres est null. Si ce paramètre est spécifié, la fonction n'est pas exécutée lorsqu'il y a des paramètres est nuls ; à la place, un résultat nul est supposé automatiquement. | |
| [EXTERNAL] SECURITY INVOKER | Ce paramètre permet d'indiquer que la fonction doit être exécutée avec les privilèges de l'utilisateur l'appelant. C'est la valeur par défaut. | |
| [EXTERNAL] SECURITY DEFINER | Ce paramètre permet d'indiquer que la fonction doit être exécutée avec les privilèges de l'utilisateur qui la possède. | |
| PARALLEL mode | Ce paramètre permet d'indiquer le mode parallèle : | |
| Mode | Description | |
| UNSAFE | Ce mode permet d'indiquer que la fonction ne peut pas être exécutée en mode parallèle et la présence d'une telle fonction dans une instruction SQL force un plan d'exécution en série. C'est la valeur par défaut. | |
| RESTRICTED | Ce mode permet d'indiquer que la fonction peut être exécutée en mode parallèle, mais l'exécution est limitée au chef de groupe parallèle. | |
| SAFE | Ce mode permet d'indiquer que la fonction peut être exécutée en toute sécurité en mode parallèle sans restriction. | |
| Les fonctions doivent être étiquetées parallèles non sécurisées si elles modifient l'état de la base de données, ou si elles apportent des modifications à la transaction telles que l'utilisation de sous-transactions, ou si elles accèdent à des séquences ou tentent d'apporter des modifications persistantes aux paramètres (par exemple, setval). Ils doivent être étiquetés comme parallèles restreints s'ils accèdent aux tables temporaires, à l'état de connexion client, aux curseurs, aux instructions préparées ou à divers états backend-local que le système ne peut pas synchroniser en mode parallèle (par exemple, setseed ne peut être exécuté que par le chef de groupe car un changement effectué par un autre processus ne serait pas reflété dans le leader). En général, si une fonction est étiquetée comme étant sûre lorsqu'elle est restreinte ou dangereuse, ou si elle est étiquetée comme étant restreinte alors qu'elle est en fait dangereuse, elle peut générer des erreurs ou produire des réponses erronées lorsqu'elle est utilisée dans une requête parallèle. Les fonctions du langage C pourraient en théorie présenter un comportement totalement indéfini si elles étaient mal étiquetées, car il n'y a aucun moyen pour le système de se protéger contre le code C arbitraire, mais dans la plupart des cas, le résultat ne sera pas pire que pour toute autre fonction. En cas de doute, les fonctions doivent être étiquetées comme UNSAFE, ce qui est la valeur par défaut. | ||
| execution_cost | Ce paramètre permet d'indiquer un nombre positif donnant le coût d'exécution estimé de la fonction, en unités de cpu_operator_cost. Si la fonction renvoie un ensemble, il s'agit du coût par ligne renvoyée. Si le coût n'est pas spécifié, 1 unité est supposée pour le langage C et les fonctions internes, et 100 unités pour les fonctions dans toutes les autres langues. Des valeurs plus élevées amènent le planificateur à essayer d'éviter d'évaluer la fonction plus souvent que nécessaire. | |
| result_rows | Ce paramètre permet d'indiquer un nombre positif donnant le nombre estimé de lignes que le planificateur doit s'attendre à ce que la fonction renvoie. Ceci n'est autorisé que lorsque la fonction est déclarée pour retourner un ensemble. Le résultat par défaut est de 1000 lignes. | |
| configuration_parameter | Ce paramètre permet d'indiquer le paramètre de configuration. | |
| value | Ce paramètre permet d'indiquer la valeur. La clause SET fait que le paramètre de configuration spécifié est défini sur la valeur spécifiée lorsque la fonction est entrée, puis restauré à sa valeur précédente lorsque la fonction se termine. Le SET FROM CURRENT enregistre la valeur du paramètre étant en cours lorsque CREATE FUNCTION est exécuté comme valeur à appliquer lorsque la fonction est entrée. Si une clause SET est attachée à une fonction, alors les effets d'une commande SET LOCAL exécutée à l'intérieur de la fonction pour la même variable sont limités à la fonction : la valeur antérieure du paramètre de configuration est toujours restaurée à la sortie de la fonction. Cependant, une commande SET ordinaire (sans LOCAL) remplace la clause SET, comme elle le ferait pour une commande SET LOCAL précédente : les effets d'une telle commande persisteront après la sortie de la fonction, à moins que la transaction en cours ne soit annulée. | |
| definition | Ce paramètre permet d'indiquer une constante de chaîne de caractères définissant la fonction ; le sens dépend de la langue. Il peut s'agir d'un nom de fonction interne, du chemin d'accès à un fichier objet, d'une commande SQL ou d'un texte dans un langage procédural. Il est souvent utile d'utiliser les guillemets dollar pour écrire la chaîne de définition de la fonction, plutôt que la syntaxe normale des guillemets simples. Sans guillemets dollar, les guillemets simples ou les barres obliques inverses dans la définition de la fonction doivent être échappés en les doublant. | |
| obj_file, link_symbol | Ces paramètres permettent d'indiquer les noms de fichiers et le symbole de lien. Cette forme de clause AS est utilisée pour les fonctions du langage C chargeables dynamiquement lorsque le nom de la fonction dans le code source du langage C n'est pas le même que le nom de la fonction SQL. La chaîne de caractères obj_file est le nom du fichier de bibliothèque partagée contenant la fonction C compilée, et est interprétée comme pour la commande LOAD. La chaîne de caractères link_symbol est le symbole de lien de la fonction, c'est-à-dire le nom de la fonction dans le code source du langage C. Si le symbole de lien est omis, il est supposé être le même que le nom de la fonction SQL définie. Les noms C de toutes les fonctions doivent être différents, vous devez donc donner aux fonctions C surchargées des noms C différents (par exemple, utilisez les types de paramètres dans le cadre des noms C). Lorsque des appels CREATE FUNCTION répétés font référence au même fichier objet, le fichier n'est chargé qu'une fois par session. Pour décharger et recharger le fichier (peut-être pendant le développement), démarrez une nouvelle session. | |
| attribute | Ce paramètre permet d'indiquer des informations facultatives sur la fonction. Les attributs suivants peuvent apparaître ici : | |
| Attribut | Description | |
| isStrict | Cette attribut est équivalent à STRICT ou RETURNS NULL ON NULL INPUT. | |
| isCachable | Cette attribut est un équivalent obsolète de IMMUTABLE ; il est toujours accepté pour des raisons de compatibilité descendante. | |
| Les noms d'attribut ne sont pas sensibles à la casse. | ||
Description
Cette instruction permet de définir une nouvelle fonction.
Dernière mise à jour : Jeudi, le 14 Octobre 2021