Catégories :

DDL pour les fonctions définies par l’utilisateur, les fonctions externes et les procédures stockées

CREATE EXTERNAL FUNCTION

Crée une nouvelle fonction externe.

Voir aussi :

ALTER EXTERNAL FUNCTION , SHOW EXTERNAL FUNCTIONS , DROP FUNCTION , DESCRIBE FUNCTION , CREATE API INTEGRATION

Syntaxe

CREATE [ OR REPLACE ] [ SECURE ] EXTERNAL FUNCTION <name> ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type>
  [ [ NOT ] NULL ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ VOLATILE | IMMUTABLE ]
  [ COMMENT = '<string_literal>' ]
  API_INTEGRATION = <api_integration_name>
  [ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  [ COMPRESSION = <compression_type> ]
  AS <url_of_proxy_and_resource>;

Paramètres requis

nom:

Spécifie l’identificateur pour la fonction.

L’identifiant peut contenir le nom du schéma et le nom de la base de données, ainsi que le nom de la fonction.

L’identificateur n’a pas besoin d’être unique pour le schéma dans lequel la fonction est créée, parce que les fonctions sont identifiées et résolues par leurs noms et types d’arguments. Cependant, la signature (nom et types de données d’argument) doit être unique dans le schéma.

Le nom doit suivre les règles des identificateurs Snowflake. Pour plus de détails, voir Exigences relatives à l’identificateur.

Le fait de donner le même nom que celui du service distant peut rendre la relation plus claire. Cependant, ce n’est pas requis.

( [ nom_argument type_données_argument ] [ , ... ] )

Spécifie les arguments/entrées pour la fonction externe. Ceux-ci doivent correspondre aux arguments attendus par le service distant.

S’il n’y a pas d’arguments, incluez les parenthèses sans nom d’argument et type de données.

RETURNS ...

Spécifie le type de données renvoyé par la fonction.

nom_intégration_api

Il s’agit du nom de l’objet d’intégration API qui doit être utilisé pour authentifier l’appel au service proxy.

url_proxy_et_ressource

Il s’agit de l’URL d’appel du service proxy (par exemple, passerelle API) et de la ressource via laquelle Snowflake appelle le service distant.

Paramètres facultatifs

SECURE

Précise que la fonction est sécurisée. Si une fonction est sécurisée, l’URL, les en-têtes HTTP et les en-têtes de contexte sont masqués à tous les utilisateurs qui ne sont pas propriétaires de la fonction.

[ [ NOT ] NULL ]

La clause indique si la fonction peut renvoyer des valeurs NULL ou doit uniquement renvoyer des valeurs NON-NULL. Si NOT NULL est spécifié, la fonction doit renvoyer uniquement des valeurs non-NULL. Si NULL est spécifié, la fonction peut renvoyer des valeurs NULL.

Par défaut : la valeur est NULL (c’est-à-dire que la fonction peut renvoyer des valeurs NULL).

CALLED ON NULL INPUT ou . RETURNS NULL ON NULL INPUT | STRICT

Spécifie le comportement de la fonction lorsqu’elle est appelée avec des entrées « null ». Contrairement aux fonctions définies par le système, qui retournent toujours la valeur « null » lorsqu’une entrée est nulle, les fonctions externes peuvent gérer les entrées null, retournant des valeurs non nulles même lorsqu’une entrée est null :

  • CALLED ON NULL INPUT appellera toujours la fonction avec des entrées null. Il appartient à la fonction de traiter ces valeurs de manière appropriée.

  • RETURNS NULL ON NULL INPUT (ou son synonyme STRICT) n’appellera pas la fonction si une entrée est null. En revanche, une valeur null sera toujours retournée pour cette ligne. Notez que la fonction peut toujours retourner une valeur null pour les entrées non null.

Par défaut : CALLED ON NULL INPUT

VOLATILE | IMMUTABLE

Spécifie le comportement de la fonction lors de l’affichage de résultats :

  • VOLATILE: la fonction peut afficher des valeurs différentes pour différentes lignes, même pour la même entrée (par exemple, en raison du non-déterminisme et du statut).

  • IMMUTABLE: la fonction renvoie toujours le même résultat lorsqu’elle est appelée avec la même entrée. Snowflake ne vérifie ni ne garantit cela ; le service distant doit être conçu pour se comporter de cette façon. Spécifier IMMUTABLE pour une fonction qui retourne effectivement des valeurs différentes pour la même entrée se traduira par un comportement indéfini.

Par défaut : VOLATILE

Snowflake vous recommande de définir ce paramètre explicitement plutôt que d’accepter la valeur par défaut. La définition de ce paramètre réduit explicitement le risque d’erreur et indique aux utilisateurs comment la fonction se comporte. (La commande SHOW EXTERNAL FUNCTIONS indique si une fonction est volatile ou immuable.)

Pour des informations complémentaires importantes sur les fonctions externes VOLATILE ou IMMUTABLE, voir Classez votre fonction comme volatile ou immuable.

COMMENT = 'litéral_chaine'

Spécifie un commentaire pour la fonction, qui est affiché dans la colonne DESCRIPTION de la sortie SHOW FUNCTIONS et de la sortie SHOW EXTERNAL FUNCTIONS.

[ HEADERS = ( '<header_1>' = '<value_1>' [ , '<header_2>' = '<value_2>' ... ] ) ]

Cette clause permet aux utilisateurs de spécifier des métadonnées de valeur clé envoyées avec chaque demande. Le créateur de la fonction externe décide de ce qui va dans les en-têtes, et l’appelant n’a aucun contrôle dessus. Snowflake ajoute tous les noms d’en-tête spécifiés avec le préfixe « sf-custom- » et les envoie en tant qu’en-têtes HTTP.

La valeur doit être une chaîne constante, pas une expression.

Voici un exemple :

headers = (
    'volume-measure' = 'liters',
    'distance-measure' = 'kilometers'
)

Ainsi, Snowflake ajoute deux en-têtes HTTP à chaque demande HTTPS : sf-custom-volume-measure et sf-custom-distance-measure, avec leurs valeurs correspondantes.

Les règles pour les noms d’en-tête sont différentes des règles pour les identificateurs de base de données Snowflake. Les noms d’en-tête peuvent être composés des caractères ASCII standard les plus visibles (décimaux 32-126), à l’exception des suivants :

  • `` `` (caractère d’espacement)

  • (

  • )

  • ,

  • /

  • :

  • ;

  • <

  • >

  • =

  • "

  • ?

  • @

  • [

  • ]

  • \

  • {

  • }

  • _

Notez spécifiquement que le caractère de soulignement n’est pas autorisé dans les noms d’en-tête.

Le nom et la valeur de l’en-tête sont délimités par des guillemets simples, de sorte que tout guillemet simple à l’intérieur du nom ou de la valeur de l’en-tête doit être échappé avec la barre oblique inverse.

Si la barre oblique inverse est utilisée comme un caractère littéral dans une valeur d’en-tête, elle doit être échappée.

Dans les valeurs d’en-tête, les espaces et les tabulations sont autorisés, mais les valeurs d’en-tête ne doivent pas contenir plus d’un caractère d’espacement par ligne. Cette restriction s’applique aux combinaisons de caractères d’espacement (par exemple, un espace suivi d’un onglet), ainsi qu’aux caractères d’espacement individuels (par exemple deux espaces consécutifs).

Si l’auteur de la fonction marque la fonction comme sécurisée (avec CREATE SECURE EXTERNAL FUNCTION...), alors les en-têtes, les en-têtes de contexte, les en-têtes de contexte binaires et les URL ne sont pas visibles pour les utilisateurs de la fonction.

La somme des tailles des noms d’en-tête et des valeurs d’en-tête pour une fonction externe doit être inférieure ou égale à 8 KB.

CONTEXT_HEADERS ...

Ceci est similaire à headers, mais au lieu d’utiliser des chaînes constantes, cela lie les résultats de la fonction de contexte Snowflake aux en-têtes HTTP. (Pour une liste des fonctions de contexte Snowflake, voir : Fonctions contextuelles.)

Les noms de fonction ne doivent pas être placés entre guillemets.

Snowflake ajoute « sf-context » à l’en-tête avant que ce ne soit écrit dans la demande HTTP.

Exemple :

context_headers = (current_timestamp)

Dans cet exemple, Snowflake écrit l’en-tête sf-context-current-timestamp dans la demande HTTP.

Les caractères autorisés dans les noms et valeurs d’en-têtes de contexte sont les mêmes que ceux autorisés dans les noms et valeurs d’en-têtes personnalisés.

Les fonctions de contexte peuvent générer des caractères non autorisés dans les valeurs d’en-tête HTTP, notamment (mais sans s’y limiter) :

  • nouvelle ligne

  • Ä

  • Î

  • ß

  • ë

  • ¬

  • ±

  • ©

  • ®

Snowflake remplace chaque séquence d’un ou plusieurs caractères non autorisés par un espace. (Le remplacement se fait par séquence, pas par caractère.)

Par exemple, supposons que la fonction de contexte CURRENT_STATEMENT() renvoie :

select
  /*ÄÎß묱©®*/
  my_external_function(1);

La valeur envoyée dans sf-context-current-statement est :

select /* */ my_external_function(1);

Pour garantir que les services distants puissent accéder au résultat d’origine (avec des caractères non autorisés) à partir de la fonction de contexte même si les caractères non autorisés ont été remplacés, Snowflake envoie également un en-tête de contexte binaire qui contient le résultat de la fonction de contexte codé en base64.

Dans l’exemple ci-dessus, la valeur envoyée dans l’en-tête base64 est le résultat de l’appel :

base64_encode('select\n/ÄÎß묱©®/\nmy_external_function(1)')

Le service distant est chargé de décoder la valeur base64 si nécessaire.

Chacun de ces en-têtes base64 est nommé selon la convention suivante :

sf-context-<context-function>-base64

Dans l’exemple ci-dessus, le nom de l’en-tête serait

sf-context-current-statement-base64

Si aucun en-tête de contexte n’est envoyé, aucun en-tête de contexte base64 n’est envoyé.

Si les lignes envoyées à une fonction externe sont réparties sur plusieurs lots, tous les lots contiennent les mêmes en-têtes de contexte et les mêmes en-têtes de contexte binaires.

MAX_BATCH_ROWS = <integer>

Cela spécifie le nombre maximal de lignes de chaque lot envoyées au service proxy. La taille du lot peut être plus petite, et généralement le dernier lot d’une requête est plus petit, sauf si le nombre total de lignes envoyées est un multiple de la taille du lot.

Si vous ne spécifiez pas MAX_BATCH_ROWS, Snowflake estime la taille de lot optimale et l’utilise.

La valeur doit être un entier positif compris entre 1 et 2147483647.

COMPRESSION = <compression_type>

Si cette clause est spécifiée, la charge utile JSON est compressée lorsqu’elle est envoyée de Snowflake au service proxy et lorsqu’elle est renvoyée du service proxy à Snowflake.

Les valeurs valides sont :

  • NONE.

  • AUTO. (Sur AWS, est équivalent à GZIP.)

  • GZIP.

  • DEFLATE.

Amazon AWS API Gateway compresse/décompresse automatiquement les demandes. Pour plus d’informations sur la compression et la décompression d’Amazon API Gateway, voir : https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-gzip-compression-decompression.html

Pour plus d’informations sur la compression et la décompression pour d’autres services proxy de plate-forme Cloud, consultez la documentation de ces plates-formes Cloud.

Par défaut : la valeur par défaut est AUTO.

Notes sur l’utilisation

  • Pour exécuter une fonction externe, un rôle doit avoir le privilège USAGE ou OWNERSHIP sur la fonction externe.

  • Lorsque la compression est utilisée, Snowflake définit les en-têtes HTTP « Content-Encoding » et « Accept-Encoding ».

  • Sur AWS, les fonctions externes nécessitent des points de terminaison régionaux. Pour plus de détails, voir Amazon AWS API Gateway.

  • Les types d’arguments et le type de retour ne peuvent pas être GEOGRAPHY.

Exemples

L’exemple suivant montre une instruction CREATE EXTERNAL FUNCTION qui est appelée via un service proxy Amazon AWS API Gateway :

create or replace external function local_echo(string_col VARCHAR)
    returns variant
    api_integration = demonstration_external_api_integration_01
    as 'https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo';

Dans cet exemple :

  • local_echo est le nom appelé à partir d’une instruction SQL. (Par exemple, vous pouvez exécuter SELECT local_echo(varchar_column) ...;.)

  • string_col VARCHAR contient le nom et le type de données des paramètres d’entrée. Une fonction externe peut avoir 0, 1 ou plusieurs paramètres d’entrée.

  • variant est le type de données de la valeur renvoyée par la fonction externe.

  • Le nom demonstration_external_api_integration_01 est le nom de l’intégration API créée précédemment dans l’instruction CREATE API INTEGRATION.

  • L’URL « https://xyz.execute-api.us-west-2.amazonaws.com/prod/remote_echo » est la chaîne qui identifie le service proxy et la ressource. Une commande HTTP POST est envoyée à cette URL.