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> ]
  [ MAX_BATCH_RETRIES = <integer> ]
  [ ON_BATCH_FAILURE = { ABORT | RETURN_NULL } ]
  [ BATCH_TIMEOUT_SECS = <integer> ]
  AS '<http_path_to_request_handler>'

Syntaxe des variantes¶

CREATE [ OR ALTER ] FUNCTION ...

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

MAX_BATCH_RETRIES = integer

Spécifie le nombre de tentatives que Snowflake doit effectuer pour rélancer un lot qui a échoué.

Par défaut : 3

ON_BATCH_FAILURE = { ABORT | RETURN_NULL }

Spécifie le comportement de la fonction après que Snowflake a atteint le nombre maximum de tentatives de traitement du lot.

• ABORT : la fonction de service interrompt son exécution. Les lots de lignes restants ne sont pas traités.

• RETURN_NULL : la fonction de service renvoie une adresse NULL pour chaque ligne du lot qui a échoué et poursuit le traitement des lots restants. Si vous choisissez cette option, notez les mises en garde suivantes :

  • Si ces lots dépendent les uns des autres et que l’un d’entre eux est défaillant, cela peut entraîner des résultats inattendus.

  • Si votre service peut renvoyer une réponse valide de type NULL, il n’est pas possible de faire la différence entre NULL renvoyé par Snowflake en raison d’un échec de lot et NULL renvoyé par votre service.

Par défaut : ABORT

BATCH_TIMEOUT_SECS = integer

Spécifie la durée maximale de traitement d’un seul lot de lignes, y compris les tentatives (et l’interrogation pour les requêtes de fonctions asynchrones), après laquelle Snowflake doit mettre fin à la requête de lot.

Valeurs acceptables : supérieures à 0 et inférieures ou égales à 604 800 secondes (7 jours).

Valeur par défaut : 604 800 secondes (7 jours)

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 opération doit au minimum disposer des privilèges suivants :

Le privilège USAGE relatif à la base de données et au schéma parents est exigé pour effectuer des opérations sur tout objet d’un schéma.

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 générales 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.

Notes sur l’utilisation de CREATE OR ALTER FUNCTION (Snowpark Container Services)¶

Les modifications suivantes ne sont pas prises en charge :

• RETURNS

• Volatilité (VOLATILE/IMMUTABLE)

• Traitement des nuls (CALLED ON NULL INPUT / RETURNS NULL ON NULL)

Exemples¶

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

CREATE OR ALTER FUNCTION my_echo_udf (InputText VARCHAR)
  RETURNS VARCHAR
  SERVICE = echo_service
  ENDPOINT = reverse_echoendpoint
  CONTEXT_HEADERS = (current_account)
  MAX_BATCH_ROWS = 100
  AS '/echo';