CREATE EXTERNAL FUNCTION¶

Voir aussi :: ALTER 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> ]
  [ REQUEST_TRANSLATOR = <request_translator_udf_name> ]
  [ RESPONSE_TRANSLATOR = <response_translator_udf_name> ]
  AS <url_of_proxy_and_resource>;

Copy

Paramètres requis¶

name :

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 name 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 name que celui du service distant peut rendre la relation plus claire. Cependant, ce n’est pas requis.

( [ arg_name arg_data_type ] [ , ... ] )

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 result_data_type

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

API_INTEGRATION = api_integration_name

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

AS url_of_proxy_and_resource

Il s’agit de l’URL d’appel du service proxy (par exemple, API Gateway ou service API Management) 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 = 'string_literal'

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.

Par défaut : user-defined function

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

Copy

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 = ( context_function_1 [ , context_function_2 ...] )

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 plus d’informations sur les fonctions contextuelles de Snowflake, voir : Fonctions contextuelles).

Toutes les fonctions contextuelles ne sont pas prises en charge dans les en-têtes de contexte. Les éléments suivants sont pris en charge :

CURRENT_ACCOUNT()
CURRENT_CLIENT()
CURRENT_DATABASE()
CURRENT_DATE()
CURRENT_IP_ADDRESS()
CURRENT_REGION()
CURRENT_ROLE()
CURRENT_SCHEMA()
CURRENT_SCHEMAS()
CURRENT_SESSION()
CURRENT_STATEMENT()
CURRENT_TIME()
CURRENT_TIMESTAMP()
CURRENT_TRANSACTION()
CURRENT_USER()
CURRENT_VERSION()
CURRENT_WAREHOUSE()
LAST_QUERY_ID()
LAST_TRANSACTION()
LOCALTIME()
LOCALTIMESTAMP()

Lorsque les noms de fonction sont énumérés dans la clause CONTEXT_HEADERS ils ne doivent pas être placés entre guillemets.

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

Exemple :

CONTEXT_HEADERS = (current_timestamp)

Copy

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

Copy

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

select /* */ my_external_function(1);

Copy

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

Copy

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

Copy

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

sf-context-current-statement-base64

Copy

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.

Le but de ce paramètre est de limiter la taille des lots pour les services distants qui ont des contraintes de mémoire ou d’autres limitations. Ce paramètre n’est pas un paramètre de réglage des performances. Ce paramètre indique une taille maximale, et non une taille recommandée.

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

Snowflake recommande de ne pas régler ce paramètre, sauf si le service distant exige une limite.

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.
GZIP.
DEFLATE.
AUTO.
- Sur AWS, AUTO est équivalent à GZIP.
- Sur Azure, AUTO est équivalent à NONE.
- Sur GCP, AUTO est équivalent à NONE.

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

REQUEST_TRANSLATOR = request_translator_udf_name

Spécifie le nom de la fonction de traducteur de requêtes. Pour plus d’informations, voir Utilisation de traducteurs de requêtes et de réponses avec des données pour un service distant.

RESPONSE_TRANSLATOR = response_translator_udf_name

Spécifie le nom de la fonction de traducteur de réponses. Pour plus d’informations, voir Utilisation de traducteurs de requêtes et de réponses avec des données pour un service distant.

Exigences en matière de contrôle d’accès¶

Un rôle utilisé pour exécuter cette commande SQL doit avoir les privilèges suivants définis au minimum ainsi :

Privilège	Objet	Remarques
CREATE EXTERNAL FUNCTION	Schéma	Operating on functions also requires the USAGE privilege on the parent database and schema.
Soit OWNERSHIP soit USAGE	intégration API	Requis pour créer des fonctions externes qui font référence à une intégration API.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation¶

Lorsque la compression est utilisée, Snowflake définit les en-têtes HTTP « Content-Encoding » et « Accept-Encoding ».
Les types d’arguments et le type de retour ne peuvent pas être GEOGRAPHY.
Concernant les métadonnées :

Attention

Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.
Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

Exemples¶

L’exemple suivant montre une instruction CREATE EXTERNAL FUNCTION qui est appelée via un service proxy Amazon 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';

Copy

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 posséder de zéro à 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.