CREATE FUNCTION (Snowpark Container Services)¶

Syntaxe¶

CREATE [ OR REPLACE ] 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 } ]
  SERVICE = <service_name>
  ENDPOINT = <endpoint_name>
  [ COMMENT = '<string_literal>' ]
  [ CONTEXT_HEADERS = ( <context_function_1> [ , <context_function_2> ...] ) ]
  [ MAX_BATCH_ROWS = <integer> ]
  AS '<http_path_to_request_handler>'

Paramètres requis¶

name

Spécifie l’identificateur (name) et tout argument d’entrée pour 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 leur combinaison de noms et types d’arguments.

• L’identificateur doit commencer par un caractère alphabétique et ne peut pas contenir d’espaces ou de caractères spéciaux à moins que toute la chaîne d’identificateur soit délimitée par des guillemets doubles (p. ex., « Mon objet »). Les identificateurs entre guillemets doubles sont également sensibles à la casse. Voir Exigences relatives à l’identificateur.

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

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

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 du résultat renvoyé par la fonction.

SERVICE = service_name

Spécifie le nom du service Snowpark Container Services.

ENDPOINT = endpoint_name

Spécifie le nom du point de terminaison tel que défini dans la spécification de service.

AS http_path_to_request_handler

Spécifie le chemin HTTP vers le code de service qui est exécuté lorsque la fonction est appelée.

Paramètres facultatifs¶

[ [ NOT ] NULL ]

Indique si la fonction peut renvoyer des valeurs NULL ou doit uniquement renvoyer des valeurs NON-NULL. La valeur par défaut est NULL (c’est-à-dire que la fonction peut renvoyer 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 null, les fonctions 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 suppose que la fonction, lorsqu’elle est appelée avec les mêmes entrées, renvoie toujours le même résultat. Cette garantie n’est pas vérifiée. Spécifier IMMUTABLE pour une fonction qui retourne des valeurs différentes pour la même entrée se traduira par un comportement indéfini.

Par défaut : VOLATILE

[ MAX_BATCH_ROWS = integer ]

Spécifie la taille du lot lors de l’envoi de données à un service pour augmenter la concurrence

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 USER FUNCTIONS.

Par défaut : user-defined function

CONTEXT_HEADERS = ( context_function_1 [ , context_function_2 ...] )

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 cette valeur ne soit écrite 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 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_service_function(1);

Copy

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

select /* */ my_service_function(1);

Copy

Pour garantir que le code de service puisse 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 codé en base64 est le résultat de l’appel suivant :

base64_encode('select\n/ÄÎß묱©®/\nmy_service_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 le suivant :

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 de service 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.

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 :

Notez que l’exploitation d’un objet dans un schéma requiert également le privilège USAGE sur la base de données et le schéma parents.

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¶

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

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

Exemples¶

Dans Tutoriel-1, vous créez la fonction de service suivante :

CREATE FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE=echo_service
  ENDPOINT=echoendpoint
  AS '/echo';

Cette fonction se connecte à l’élément ENDPOINT spécifique de l’élément SERVICE spécifié. Lorsque vous appelez cette fonction, Snowflake envoie une requête au chemin /echo dans le conteneur de service.

Remarques :

• La fonction my_echo_udf prend une chaîne en entrée et renvoie une chaîne.

• La propriété SERVICE identifie le service (echo_service) et la propriété ENDPOINT identifie le nom convivial du point de terminaison (echoendpoint).

• AS '/echo' spécifie le chemin d’accès au service. Dans echo_service.py (voir code de service), le décorateur @app.post associe ce chemin à la fonction echo.