CALL (avec procédure anonyme)

Crée et appelle une procédure anonyme qui est comme une procédure stockée mais qui n’est pas stockée pour une utilisation ultérieure.

Avec cette commande, vous créez une procédure anonyme définie par des paramètres dans la clause WITH et vous appelez cette procédure.

Il n’est pas nécessaire d’avoir un rôle avec des privilèges de schéma CREATE PROCEDURE pour cette commande.

La procédure s’exécute avec les droits de l’appelant, ce qui signifie que la procédure s’exécute avec les privilèges de l’appelant, utilise le contexte de session actuel et a accès aux variables et paramètres de session de l’appelant.

Voir aussi :

CREATE PROCEDURE , CALL.

Syntaxe

Java et Scala

WITH <name> AS PROCEDURE ([ <arg_name> <arg_data_type> ]) [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE { SCALA | JAVA }
  RUNTIME_VERSION = '<scala_or_java_runtime_version>'
  PACKAGES = ( 'com.snowflake:snowpark:<version>' [, '<package_name_and_version>' ...] )
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [, '<stage_path_and_file_name_to_read>' ...] ) ]
  HANDLER = '<fully_qualified_method_name>'
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ AS '<procedure_definition>' ]
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
CALL <name> ( [ <arg> , ... ] )

Pour les procédures précompilées en Scala et Java, utilisez la syntaxe suivante :

WITH <name> AS PROCEDURE ([ <arg_name> <arg_data_type> ]) [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE { SCALA | JAVA }
  RUNTIME_VERSION = '<scala_or_java_runtime_version>'
  PACKAGES = ( 'com.snowflake:snowpark:<version>' [, '<package_name_and_version>' ...] )
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [, '<stage_path_and_file_name_to_read>' ...] ) ]
  HANDLER = '<fully_qualified_method_name>'
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
CALL <name> ( [ <arg> , ... ] )

JavaScript

WITH <name> AS PROCEDURE ([ <arg_name> <arg_data_type> ]) [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE JAVASCRIPT
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  AS '<procedure_definition>'
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
CALL <name> ( [ <arg> , ... ] )

Python

Pour les procédures en ligne, utilisez la syntaxe suivante :

WITH <name> AS PROCEDURE ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE PYTHON
  RUNTIME_VERSION = '<python_version>'
  PACKAGES = ( 'snowflake-snowpark-python[==<version>]'[, '<package_name>[==<version>]' ... ])
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [, '<stage_path_and_file_name_to_read>' ...] ) ]
  HANDLER = '<function_name>'
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
  AS '<procedure_definition>'
CALL <name> ( [ <arg> , ... ] )

Pour une procédure stockée dans laquelle le code se trouve dans un fichier sur une zone de préparation, utilisez la syntaxe suivante :

WITH <name> AS PROCEDURE ( [ <arg_name> <arg_data_type> ] [ , ... ] )
  RETURNS <result_data_type> [ [ NOT ] NULL ]
  LANGUAGE PYTHON
  RUNTIME_VERSION = '<python_version>'
  PACKAGES = ( 'snowflake-snowpark-python[==<version>]'[, '<package_name>[==<version>]' ... ])
  [ IMPORTS = ( '<stage_path_and_file_name_to_read>' [, '<stage_path_and_file_name_to_read>' ...] ) ]
  HANDLER = '<module_file_name>.<function_name>'
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ , <name> AS PROCEDURE ([ <arg_name> <arg_data_type> ]) [ , ... ] ) ... ]
  [ , <cte_nameN> [ ( <cte_column_list> ) ] AS ( SELECT ...  ) ]
CALL <name> ( [ <arg> , ... ] )

Paramètres requis

Tous les langages

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

Spécifie l’identificateur (name) et tout argument d’entrée pour la procédure.

RETURNS result_data_type [ [ NOT ] NULL ]

Spécifie le type du résultat renvoyé par la procédure.

Utilisez NOT NULL pour spécifier que la procédure doit renvoyer uniquement des valeurs non nulles ; la valeur par défaut est NULL, ce qui signifie que la procédure peut renvoyer NULL.

En pratique, la valeur renvoyée ne peut pas être utilisée, car l’appel ne peut pas faire partie d’une expression.

LANGUAGE language

Spécifie la langue du code du gestionnaire de la procédure.

Actuellement, les valeurs prises en charge pour language comprennent :

AS procedure_definition

Définit le code exécuté par la procédure. La définition peut consister en n’importe quel code valide.

Remarques :

Pour plus de détails sur les procédures stockées, voir Travailler avec des procédures stockées.

Java, Python, ou Scala

RUNTIME_VERSION = 'language_runtime_version'

Version de la runtime du langage à utiliser. Les versions prises en charge sont les suivantes :

  • Java : 11

  • Python : 3.8

  • Scala : 2.12

PACKAGES = ( 'snowpark_package_name' [, 'package_name' ...] )

Une liste, séparée par des virgules, des noms des paquets déployés dans Snowflake qui doivent être inclus dans l’environnement d’exécution du code du gestionnaire. Le package Snowpark est requis pour les procédures, il doit donc toujours être référencé dans la clause PACKAGES. Pour plus d’informations sur Snowpark, voir API Snowpark.

Par défaut, l’environnement dans lequel Snowflake exécute les procédures comprend un ensemble sélectionné de packages pour les langages pris en charge. Lorsque vous référencez ces paquets dans la clause PACKAGES, il n’est pas nécessaire de référencer un fichier contenant le paquet dans la clause IMPORTS car le paquet est déjà disponible dans Snowflake.

Pour obtenir la liste des packages et des versions pris en charge pour un langage particulier, interrogez la vue INFORMATION_SCHEMA.PACKAGES, en spécifiant le langage. Par exemple :

select * from information_schema.packages where language = '<language>';

language est java, python, ou scala.

La syntaxe pour faire référence à un package dans la clause PACKAGES varie selon le langage du package, comme décrit ci-dessous.

  • Java

    Spécifiez le nom du paquet et le numéro de version en utilisant la forme suivante :

    domain:package_name:version
    

    Pour spécifier la dernière version, spécifiez latest pour version.

    Par exemple, pour inclure un paquet de la dernière bibliothèque Snowpark dans Snowflake, utilisez ce qui suit :

    PACKAGES = ('com.snowflake:snowpark:latest')
    

    Lorsque vous spécifiez un paquet de la bibliothèque Snowpark, vous devez spécifier la version 1.3.0 ou une version ultérieure.

  • Python

    Snowflake comprend un grand nombre de paquets disponibles via Anaconda ; pour plus d’informations, voir Utilisation de paquets tiers.

    Spécifiez le nom du paquet et le numéro de version en utilisant la forme suivante :

    package_name[==version]
    

    Pour spécifier la dernière version, omettez le numéro de version.

    Par exemple, pour inclure la version du paquet spacy 2.3.5 (ainsi que la dernière version du paquet Snowpark requis), utilisez ce qui suit :

    PACKAGES = ('snowflake-snowpark-python', 'spacy==2.3.5')
    

    Lorsque vous spécifiez un paquet de la bibliothèque Snowpark, vous devez spécifier la version 0.4.0 ou une version ultérieure. Omettez le numéro de version pour utiliser la dernière version disponible dans Snowflake.

  • Scala

    Spécifiez le nom du paquet et le numéro de version en utilisant la forme suivante :

    domain:package_name:version
    

    Pour spécifier la dernière version, spécifiez latest pour version.

    Par exemple, pour inclure un paquet de la dernière bibliothèque Snowpark dans Snowflake, utilisez ce qui suit :

    PACKAGES = ('com.snowflake:snowpark:latest')
    

    Snowflake prend en charge l’utilisation de Snowpark version 0.9.0 ou ultérieure dans une procédure Scala. Notez toutefois que ces versions présentent des limites. Par exemple, les versions antérieures à la version 1.1.0 ne prennent pas en charge l’utilisation de transactions dans une procédure.

HANDLER = 'fully_qualified_method_name'

  • Python

    Utilisez le nom de la fonction ou de la méthode de la procédure. Cela peut varier selon que le code est en ligne ou référencé au niveau d’une zone de préparation.

    • Lorsque le code est en ligne, vous pouvez spécifier uniquement le nom de la fonction, comme dans l’exemple suivant :

      WITH myproc AS PROCEDURE()
        ...
        HANDLER = 'run'
        AS
        $$
        def run(session):
          ...
        $$
      CALL myproc();
      
    • Lorsque le code est importé depuis une zone de préparation, spécifiez le nom de la fonction de gestionnaire entièrement qualifié sous la forme <nom_module>.<nom_fonction>.

      WITH myproc AS PROCEDURE()
        ...
        IMPORTS = ('@mystage/my_py_file.py')
        HANDLER = 'my_py_file.run'
      CALL myproc();
      
  • Java et Scala

    Utilisez le nom complet de la méthode ou de la fonction pour la procédure. Ceci se présente généralement sous la forme suivante :

    com.my_company.my_package.MyClass.myMethod
    

    où :

    com.my_company.my_package
    

    correspond au paquet contenant l’objet ou la classe :

    package com.my_company.my_package;
    

Paramètres facultatifs

Tous les langages

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

Spécifie le comportement de la procédure lors d’un appel 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 procédures 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 procédure avec des entrées null. Il appartient à la procédure de traiter ces valeurs de manière appropriée.

  • RETURNS NULL ON NULL INPUT (ou son synonyme STRICT) n’appelle pas la procédure si une entrée est null, ainsi les instructions contenues dans la procédure stockée ne seront pas exécutées. En revanche, une valeur null sera toujours retournée. Notez que la procédure peut toujours retourner une valeur null pour les entrées non null.

Par défaut : CALLED ON NULL INPUT

Java, Python, ou Scala

IMPORTS = ( 'stage_path_and_file_name_to_read' [, 'stage_path_and_file_name_to_read' ...] )

L’emplacement (zone de préparation), le chemin et le nom du ou des fichiers à importer. Vous devez définir la clause IMPORTS pour inclure tous les fichiers dont dépend votre procédure :

  • Si vous écrivez une procédure en ligne, vous pouvez omettre cette clause, sauf si votre code dépend de classes définies en dehors de la procédure ou de fichiers de ressources.

  • Java ou Scala : si vous écrivez une procédure précompilée, vous devez également inclure un chemin vers le fichier JAR contenant la définition de la procédure stockée.

  • Python : si le code de votre procédure se trouve au niveau d’une zone de préparation, vous devez également inclure un chemin vers le fichier du module dans lequel se trouve votre code.

Chaque fichier de la clause IMPORTS doit avoir un nom unique, même si les fichiers se trouvent dans des sous-répertoires différents ou dans des zones de préparation différentes.

Notes sur l’utilisation

Utilisation générale

  • Les procédures ne sont pas atomiques ; si une instruction d’une procédure échoue, les autres instructions de la procédure ne sont pas nécessairement annulées. Pour des informations sur les procédures et les transactions, voir Gestion des transactions.

  • Une procédure ne peut renvoyer qu’une seule valeur, telle qu’une chaîne (par exemple, un indicateur de réussite/échec) ou un nombre (par exemple, un code d’erreur). Si vous devez renvoyer des informations plus détaillées, vous pouvez renvoyer un VARCHAR contenant des valeurs séparées par un délimiteur (tel qu’une virgule) ou un type de données semi-structuré, tel que VARIANT.

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

Syntaxe

  • Comme lorsqu’une clause WITH est utilisée avec une instruction SELECT, une clause WITH utilisée avec CALL permet de spécifier plusieurs CTEs séparés par des virgules, en plus de la définition de la procédure. Cependant, il n’est pas possible de transmettre des valeurs tabulaires produites par une clause WITH à la clause CALL.

    Il est toutefois possible de spécifier une simple variable dont la valeur est assignée dans la clause WITH.

  • La clause CALL doit apparaître en dernier dans la syntaxe.

Privilèges

  • La création et l’appel d’une procédure avec cette commande ne nécessitent pas un rôle avec des privilèges de schéma CREATE PROCEDURE.

  • Le code du gestionnaire de la procédure ne pourra effectuer que les actions autorisées pour le rôle attribué à la personne qui a exécuté cette commande.

Langage spécifique

Exemples

with copy_to_table as procedure (fromTable string, toTable string, count int)
  returns string
  language scala
  packages = ('com.snowflake:snowpark:latest')
  handler = 'DataCopy.copyBetweenTables'
  as
  $$
    object DataCopy
    {
      def copyBetweenTables(session: com.snowflake.snowpark.Session, fromTable: String, toTable: String, count: Int): String =
      {
        session.table(fromTable).limit(count).write.saveAsTable(toTable)
        return "Success"
      }
    }
  $$
call copy_to_table('table_a', 'table_b', 5);

Pour des exemples de procédures, voir Travailler avec des procédures stockées.

Revenir au début