CREATE PROCEDURE¶

Une procédure peut être écrite dans l’un des langages suivants :

Note

Lorsque vous voulez créer et appeler une procédure anonyme (plutôt que stockée), utilisez CALL (avec procédure anonyme). La création d’une procédure anonyme ne nécessite pas un rôle avec des privilèges de schéma CREATE PROCEDURE.

Voir aussi :: ALTER PROCEDURE, DROP PROCEDURE , SHOW PROCEDURES , DESCRIBE PROCEDURE, CALL

Syntaxe¶

Gestionnaire Java¶

Vous pouvez créer une procédure stockée qui inclut son code de gestionnaire en ligne ou qui renvoie à son code de gestionnaire dans un fichier JAR. Pour plus d’informations, voir Conserver le code du gestionnaire en ligne ou dans une zone de préparation.

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

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <defaut_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  LANGUAGE JAVA
  RUNTIME_VERSION = '<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>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ TARGET_PATH = '<stage_path_and_file_name_to_write>' ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { CALLER | OWNER } ]
  AS '<procedure_definition>'

Copy

Pour une procédure stockée qui utilise un gestionnaire précompilé, utilisez la syntaxe suivante.

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  LANGUAGE JAVA
  RUNTIME_VERSION = '<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>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ VOLATILE | IMMUTABLE ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { CALLER | OWNER } ]

Copy

Gestionnaire JavaScript¶

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS <result_data_type> [ NOT NULL ]
  LANGUAGE JAVASCRIPT
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ VOLATILE | IMMUTABLE ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { CALLER | OWNER } ]
  AS '<procedure_definition>'

Copy

Important

JavaScript est sensible à la casse, alors que SQL ne l’est pas. Voir Sensibilité à la casse dans les arguments JavaScript pour obtenir des informations importantes sur l’utilisation de noms d’arguments de procédure stockée dans le code JavaScript.

Gestionnaire Python¶

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

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  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>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { CALLER | OWNER } ]
  AS '<procedure_definition>'

Copy

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 :

CREATE [ OR REPLACE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  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>'
  [ EXTERNAL_ACCESS_INTEGRATIONS = ( <name_of_integration> [ , ... ] ) ]
  [ SECRETS = ('<secret_variable_name>' = <secret_name> [ , ... ] ) ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { CALLER | OWNER } ]

Copy

Gestionnaire Scala¶

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

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  LANGUAGE SCALA
  RUNTIME_VERSION = '<scala_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>'
  [ TARGET_PATH = '<stage_path_and_file_name_to_write>' ]
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { CALLER | OWNER } ]
  AS '<procedure_definition>'

Copy

Pour une procédure stockée qui utilise un gestionnaire précompilé, utilisez la syntaxe suivante.

CREATE [ OR REPLACE ] [ SECURE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> [ [ NOT ] NULL ] | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  LANGUAGE SCALA
  RUNTIME_VERSION = '<scala_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 } } ]
  [ VOLATILE | IMMUTABLE ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { CALLER | OWNER } ]

Copy

Gestionnaire d’exécution de scripts Snowflake¶

CREATE [ OR REPLACE ] PROCEDURE <name> (
    [ <arg_name> <arg_data_type> [ DEFAULT <default_value> ] ] [ , ... ] )
  [ COPY GRANTS ]
  RETURNS { <result_data_type> | TABLE ( [ <col_name> <col_data_type> [ , ... ] ] ) }
  [ NOT NULL ]
  LANGUAGE SQL
  [ { CALLED ON NULL INPUT | { RETURNS NULL ON NULL INPUT | STRICT } } ]
  [ { VOLATILE | IMMUTABLE } ] -- Note: VOLATILE and IMMUTABLE are deprecated.
  [ COMMENT = '<string_literal>' ]
  [ EXECUTE AS { CALLER | OWNER } ]
  AS <procedure_definition>

Copy

Note

Si vous créez une procédure Exécution de scripts Snowflake dans SnowSQL ou dans l”Classic Console, vous devez utiliser les délimiteurs de littéral de chaîne (' ou $$) autour de la procedure definition. Voir Utilisation d’Exécution de scripts Snowflake dans SnowSQL et l”Classic Console.

Paramètres requis¶

Toutes les langues¶

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

Spécifie l’identificateur (name), tous les arguments d’entrée et les valeurs par défaut de tous les arguments facultatifs pour la procédure stockée.

Pour l’identificateur :
- L’identificateur n’a pas besoin d’être unique pour le schéma dans lequel la procédure est créée parce que les procédures stockées 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.
Pour les arguments d’entrée :
- Pour arg_name, spécifiez le nom de l’argument d’entrée.
- Pour arg_data_type, utilisez le type de données Snowflake qui correspond au langage que vous utilisez.
  - Pour les procédures stockées Java, voir Mappages de type de données SQL-Java.
  - Pour les procédures stockées JavaScript, voir Mappage de type de données SQL et JavaScript.
  - Pour les procédures stockées Python, voir Mappages des types de données SQL-Python.
  - Pour les procédures stockées Scala, voir Mappages de type de données SQL-Scala.
  - Pour Exécution de scripts Snowflake, un type de données SQL.
  Note
  
  Pour les procédures stockées que vous écrivez en Java, Python ou Scala (qui utilisent des APIs Snowpark), omettez l’argument pour l’objet Session Snowpark.
  
  L’argument Session n’est pas un paramètre formel que vous spécifiez dans CREATE PROCEDURE ou CALL. Lorsque vous appelez votre procédure stockée, Snowflake crée automatiquement un objet Session et le transmet à la fonction de gestionnaire de votre procédure stockée.
- Pour indiquer qu’un argument est facultatif, utilisez DEFAULT default_value pour spécifier la valeur par défaut de l’argument. Pour la valeur par défaut, vous pouvez utiliser un littéral ou une expression.
  
  Si vous spécifiez des arguments facultatifs, vous devez les placer après les arguments obligatoires.
  
  Si une procédure a des arguments facultatifs, vous ne pouvez pas définir d’autres procédures portant le même nom et ayant des signatures différentes.
  
  Pour plus de détails, voir Spécifiez des arguments facultatifs.

RETURNS result_data_type [ NOT NULL ]

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

Pour result_data_type, utilisez le type de données Snowflake qui correspond au type de langage que vous utilisez.
- Pour les procédures stockées Java, voir Mappages de type de données SQL-Java.
- Pour les procédures stockées JavaScript, voir Mappage de type de données SQL et JavaScript.
- Pour les procédures stockées Python, voir Mappages des types de données SQL-Python.
- Pour les procédures stockées Scala, voir Mappages de type de données SQL-Scala.
- Pour Exécution de scripts Snowflake, un type de données SQL.
Note

Les procédures stockées que vous écrivez dans Snowpark (Java ou Scala) doivent avoir une valeur de retour. Dans Snowpark (Python), lorsqu’une procédure stockée ne renvoie aucune valeur, on considère qu’elle renvoie None. Notez que chaque instruction CREATE PROCEDURE doit inclure une clause RETURNS qui définit un type de retour, même si la procédure ne retourne rien explicitement.
Pour RETURNS TABLE ( [ col_name col_data_type [ , ... ] ] ), si vous connaissez les types de données Snowflake des colonnes de la table renvoyée, spécifiez les noms et les types de colonnes :
```
CREATE OR REPLACE PROCEDURE get_top_sales()
  RETURNS TABLE (sales_date DATE, quantity NUMBER)
...
```
Copy
Sinon (par exemple, si vous déterminez les types de colonnes pendant l’exécution), vous pouvez omettre les noms et les types de colonnes :
```
CREATE OR REPLACE PROCEDURE get_top_sales()
  RETURNS TABLE ()
```
Copy
Note

Actuellement, dans la clause RETURNS TABLE(...) , vous ne pouvez pas spécifier GEOGRAPHY comme type de colonne. Ceci s’applique que vous créiez une procédure stockée ou anonyme.
CREATE OR REPLACE PROCEDURE test_return_geography_table_1() RETURNS TABLE(g GEOGRAPHY) ...
Copy
WITH test_return_geography_table_1() AS PROCEDURE RETURNS TABLE(g GEOGRAPHY) ... CALL test_return_geography_table_1();
Copy
Si vous tentez de spécifier GEOGRAPHY comme type de colonne, l’appel de la procédure stockée entraîne une erreur :
Stored procedure execution error: data type of returned table does not match expected returned table type
Copy
Pour contourner ce problème, vous pouvez omettre les arguments et les types de colonnes dans RETURNS TABLE().
CREATE OR REPLACE PROCEDURE test_return_geography_table_1() RETURNS TABLE() ...
Copy
WITH test_return_geography_table_1() AS PROCEDURE RETURNS TABLE() ... CALL test_return_geography_table_1();
Copy
RETURNS TABLE(…) est pris en charge uniquement lorsque le gestionnaire est écrit dans les langages suivants :

En pratique, en dehors d’un bloc Exécution de scripts Snowflake, 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 le langage du code de la procédure stockée Notez que ceci est facultatif pour les procédures stockées écrites avec Exécution de scripts Snowflake.

Actuellement, les valeurs prises en charge pour language comprennent :

JAVA (pour Java).
JAVASCRIPT (pour JavaScript)
PYTHON (pour Python)
SCALA (pour Scala).
SQL (pour Exécution de scripts Snowflake)

Par défaut : SQL.

AS procedure_definition

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

Remarques :

Pour les procédures stockées dont le code n’est pas en ligne, omettez la clause AS. Cela inclut les procédures stockées avec des gestionnaires en zone de préparation.

Utilisez plutôt la clause IMPORTS pour spécifier l’emplacement du fichier contenant le code de la procédure stockée. Pour plus de détails, voir :
Pour plus d’informations sur les gestionnaires en ligne et en zone de préparation, voir Conserver le code du gestionnaire en ligne ou dans une zone de préparation.
Vous devez utiliser les délimiteurs de littéral de chaîne (' ou $$) autour de la procedure definition si :
- Vous utilisez un langage autre que Exécution de scripts Snowflake.
- Vous créez une procédure Exécution de scripts Snowflake dans SnowSQL ou l”Classic Console. Voir Utilisation d’Exécution de scripts Snowflake dans SnowSQL et l”Classic Console.
Pour les procédures stockées en JavaScript et si vous écrivez une chaîne qui contient de nouvelles lignes, vous pouvez utiliser des guillemets (également appelés « backticks ») autour de la chaîne.

L’exemple ci-dessous d’une procédure stockée JavaScript utilise $$ et des guillemets, car le corps de la procédure stockée contient des guillemets simples et des guillemets doubles :
CREATE OR REPLACE TABLE table1 ("column 1" VARCHAR);
Copy
CREATE or replace PROCEDURE proc3() RETURNS VARCHAR LANGUAGE javascript AS $$ var rs = snowflake.execute( { sqlText: `INSERT INTO table1 ("column 1") SELECT 'value 1' AS "column 1" ;` } ); return 'Done.'; $$;
Copy
Pour les langages autres que Exécution de scripts Snowflake, Snowflake ne valide pas complètement le code lorsque vous exécutez la commande CREATE PROCEDURE.

Par exemple, pour les procédures stockées Snowpark (Scala), le nombre et les types d’arguments d’entrée sont validés, mais le corps de la fonction ne l’est pas. Si le nombre ou les types ne correspondent pas (par exemple, si le type de données Snowflake NUMBER est utilisé alors que l’argument est un type non numérique), l’exécution de la commande CREATE PROCEDURE provoque une erreur.

Si le code n’est pas valide, la commande CREATE PROCEDURE réussira, et des erreurs s’afficheront lorsque la procédure stockée sera appelée.

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

Java¶

RUNTIME_VERSION = 'language_runtime_version'

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

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 paquet Snowpark est requis pour les procédures stockées, 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 stockées comprend un ensemble sélectionné de paquets 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. Vous pouvez également spécifier la version du paquet.

Pour obtenir la liste des paquets et des versions pris en charge pour Java, interrogez la vue INFORMATION_SCHEMA.PACKAGES pour les lignes, en spécifiant le langage. Par exemple :

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'java';

Copy

Pour spécifier le nom du paquet et le numéro de version, utilisez le format suivant :

domain:package_name:version

Copy

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

Copy

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.

HANDLER = 'fully_qualified_method_name'

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

com.my_company.my_package.MyClass.myMethod

Copy

où :

com.my_company.my_package

Copy

correspond au paquet contenant l’objet ou la classe :

package com.my_company.my_package;

Copy

Python¶

RUNTIME_VERSION = 'language_runtime_version'

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

3,8

3,9

3,10

3,11

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

Pour obtenir la liste des paquets et des versions pris en charge pour Python, interrogez la vue INFORMATION_SCHEMA.PACKAGES pour les lignes, en spécifiant le langage. Par exemple :

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'python';

Copy

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

Pour spécifier le nom du paquet et le numéro de version, utilisez le format suivant :

package_name[==version]

Copy

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

Copy

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.

HANDLER = 'fully_qualified_method_name'

Utilisez le nom de la fonction ou de la méthode de la procédure stockée. 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 :

CREATE OR REPLACE PROCEDURE MYPROC(from_table STRING, to_table STRING, count INT)
  ...
  HANDLER = 'run'
AS
$$
def run(session, from_table, to_table, count):
  ...
$$;

Copy

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

CREATE OR REPLACE PROCEDURE MYPROC(from_table STRING, to_table STRING, count INT)
  ...
  IMPORTS = ('@mystage/my_py_file.py')
  HANDLER = 'my_py_file.run';

Copy

Scala¶

RUNTIME_VERSION = 'language_runtime_version'

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

2,12

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

Pour obtenir la liste des paquets et des versions pris en charge pour Scala, interrogez la vue INFORMATION_SCHEMA.PACKAGES pour les lignes, en spécifiant le langage. Par exemple :

SELECT * FROM INFORMATION_SCHEMA.PACKAGES WHERE LANGUAGE = 'scala';

Copy

Pour spécifier le nom du paquet et le numéro de version, utilisez le format suivant :

domain:package_name:version

Copy

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

Copy

Snowflake prend en charge l’utilisation de Snowpark version 0.9.0 ou ultérieure dans une procédure stockée 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 stockée.

HANDLER = 'fully_qualified_method_name'

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

com.my_company.my_package.MyClass.myMethod

Copy

où :

com.my_company.my_package

Copy

correspond au paquet contenant l’objet ou la classe :

package com.my_company.my_package;

Copy

Paramètres facultatifs¶

Toutes les langues¶

SECURE

Indique que la procédure est sécurisée. Pour plus d’informations sur les procédures sécurisées, voir Protection des informations sensibles avec les UDFs et les procédures stockées sécurisées.

[ [ NOT ] NULL ]

Indique si la procédure stockée 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 procédure stockée peut renvoyer une valeur NULL).

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

Spécifie le comportement de la procédure stockée 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 stockées peuvent gérer des entrées null, retournant des valeurs non nulles même lorsqu’une entrée est nulle :

CALLED ON NULL INPUT appellera toujours la procédure stockée 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 stockée 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

VOLATILE | IMMUTABLE

Obsolète

Attention

Ces mots-clés sont obsolètes pour les procédures stockées. Ces mots-clés ne sont pas destinés à s’appliquer aux procédures stockées. Dans une prochaine version, ces mots-clés seront supprimés de la documentation.

COMMENT = 'string_literal'

Spécifie un commentaire pour la procédure stockée, qui est affiché dans la colonne DESCRIPTION de la sortie SHOW PROCEDURES.

Par défaut : stored procedure

EXECUTE AS CALLER ou . EXECUTE AS OWNER

Spécifie si une procédure stockée peut s’exécuter avec les privilèges du propriétaire (procédure stockée des « droits du propriétaire ») ou avec les privilèges de l’appelant (procédure stockée des « droits de l’appelant ») :

Si vous exécutez l’instruction CREATE PROCEDURE … EXECUTE AS CALLER, alors plus tard, la procédure s’exécutera en tant que procédure de droits de l’appelant.
Si vous exécutez CREATE PROCEDURE … EXECUTE AS OWNER, la procédure sera exécutée comme une procédure de droits du propriétaire.

Par défaut (si ni OWNER ni CALLER ne sont spécifiés explicitement au moment de la création de la procédure), la procédure s’exécute en tant que procédure stockée avec droits du propriétaire.

Les procédures stockées avec droits du propriétaire ont moins d’accès à l’environnement de l’appelant (par exemple, les variables de session de l’appelant), et Snowflake utilise par défaut ce niveau supérieur de confidentialité et de sécurité.

Pour plus d’informations, consultez Understanding Caller’s Rights and Owner’s Rights Stored Procedures.

Par défaut : OWNER

COPY GRANTS

Spécifie de conserver les privilèges d’accès de la procédure originale lorsqu’une nouvelle procédure est créée en utilisant CREATE OR REPLACE PROCEDURE.

Ce paramètre copie tous les privilèges, excepté OWNERSHIP, depuis la table existante vers la nouvelle table. La nouvelle table n’hérite pas des attributions futures définies pour le type d’objet dans le schéma. Par défaut, le rôle qui exécute l’instruction CREATE PROCEDURE est propriétaire de la nouvelle table.

Remarque :

La sortie SHOW GRANTS pour la procédure de remplacement liste le concessionnaire des privilèges copiés comme le rôle qui a exécuté l’instruction CREATE PROCEDURE, avec l’horodatage courant lorsque l’instruction a été exécutée.
L’opération de copie des accords s’effectue atomiquement dans la commande CREATE PROCEDURE (c’est-à-dire dans la même transaction).

Java¶

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 stockée :

Si vous écrivez une procédure stockée en ligne, vous pouvez omettre cette clause, sauf si votre code dépend de classes définies en dehors de la procédure stockée ou de fichiers de ressources.
Si vous écrivez une procédure stockée avec un gestionnaire en zone de préparation, vous devez également inclure un chemin vers le fichier JAR contenant le code du gestionnaire de la procédure stockée.
La définition IMPORTS ne peut pas faire référence à des variables provenant d’arguments transmis à la procédure stockée.

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.

TARGET_PATH = 'stage_path_and_file_name_to_write'

Pour les procédures stockées avec un code de gestionnaire en ligne, spécifie l’emplacement vers lequel Snowflake doit écrire le code compilé (fichier JAR) après avoir compilé le code source spécifié dans la procedure_definition. Si cette clause est omise, Snowflake recompile le code source chaque fois que le code est nécessaire.

Si vous spécifiez cette clause :

Vous ne pouvez pas définir cette option sur un fichier existant. Snowflake renvoie une erreur si le TARGET_PATH pointe vers un fichier existant.
Si vous spécifiez les clauses IMPORTS et TARGET_PATH , le nom du fichier dans la clause TARGET_PATH doit être différent de chaque nom de fichier dans la clause IMPORTS , même si les fichiers se trouvent dans des sous-répertoires différents ou dans des zones de préparation différentes.
Si vous n’avez plus besoin d’utiliser la procédure stockée (par exemple, si vous détruisez la procédure stockée), vous devez supprimer manuellement ce fichier JAR.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

Les noms des intégrations d’accès externe nécessaires pour que le code du gestionnaire de cette procédure puisse accéder aux réseaux externes.

Une intégration d’accès externe contient des règles de réseau et des secrets qui spécifient les emplacements externes et les identifiants de connexion (le cas échéant) nécessaires au code du gestionnaire pour effectuer des requêtes auprès d’un réseau externe, tel qu’une API REST externe.

SECRETS = ( 'secret_variable_name' = secret_name [ , ... ] )

Attribue les noms des secrets aux variables afin que vous puissiez utiliser les variables pour référencer les secrets lors de la récupération des informations des secrets dans le code du gestionnaire.

La valeur de ce paramètre est une liste d’expressions d’affectation séparées par des virgules et composée des parties suivantes :

secret_name comme nom d’un secret spécifié dans la valeur du paramètre ALLOWED_AUTHENTICATION_SECRETS d’une intégration d’accès externe. Le nom de cette intégration d’accès externe doit, à son tour, être spécifié comme valeur du paramètre EXTERNAL_ACCESS_INTEGRATIONS de cet appel CREATE PROCEDURE.

Vous recevrez une erreur si vous spécifiez une valeur SECRETS dont le secret n’est pas également inclus dans une intégration spécifiée par le paramètre EXTERNAL_ACCESS_INTEGRATIONS.
'secret_variable_name' comme variable qui sera utilisée dans le code du gestionnaire lors de la récupération des informations du secret.

Pour plus d’informations, y compris un exemple, reportez-vous à Utilisation de l’intégration de l’accès externe dans une fonction ou une procédure.

Python¶

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

Si vous écrivez une procédure stockée en ligne, vous pouvez omettre cette clause, sauf si votre code dépend de classes définies en dehors de la procédure stockée ou de fichiers de ressources.
Si le code de votre procédure stockée 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.
La définition IMPORTS ne peut pas faire référence à des variables provenant d’arguments transmis à la procédure stockée.

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.

EXTERNAL_ACCESS_INTEGRATIONS = ( integration_name [ , ... ] )

Les noms des intégrations d’accès externe nécessaires pour que le code du gestionnaire de cette procédure puisse accéder aux réseaux externes.

SECRETS = ( 'secret_variable_name' = secret_name [ , ... ] )

La valeur de ce paramètre est une liste d’expressions d’affectation séparées par des virgules et composée des parties suivantes :

secret_name comme nom d’un secret spécifié dans la valeur du paramètre ALLOWED_AUTHENTICATION_SECRETS d’une intégration d’accès externe. Le nom de cette intégration d’accès externe doit, à son tour, être spécifié comme valeur du paramètre EXTERNAL_ACCESS_INTEGRATIONS de cet appel CREATE PROCEDURE.

Vous recevrez une erreur si vous spécifiez une valeur SECRETS dont le secret n’est pas également inclus dans une intégration spécifiée par le paramètre EXTERNAL_ACCESS_INTEGRATIONS.
'secret_variable_name' comme variable qui sera utilisée dans le code du gestionnaire lors de la récupération des informations du secret.

Pour plus d’informations, y compris un exemple, reportez-vous à Utilisation de l’intégration de l’accès externe dans une fonction ou une procédure.

Scala¶

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

Si vous écrivez une procédure stockée en ligne, vous pouvez omettre cette clause, sauf si votre code dépend de classes définies en dehors de la procédure stockée ou de fichiers de ressources.
Si vous écrivez une procédure stockée avec un gestionnaire en zone de préparation, vous devez également inclure un chemin vers le fichier JAR contenant le code du gestionnaire de la procédure stockée.
La définition IMPORTS ne peut pas faire référence à des variables provenant d’arguments transmis à la procédure stockée.

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.

TARGET_PATH = 'stage_path_and_file_name_to_write'

Si vous spécifiez cette clause :

Vous ne pouvez pas définir cette option sur un fichier existant. Snowflake renvoie une erreur si le TARGET_PATH pointe vers un fichier existant.
Si vous spécifiez les clauses IMPORTS et TARGET_PATH , le nom du fichier dans la clause TARGET_PATH doit être différent de chaque nom de fichier dans la clause IMPORTS , même si les fichiers se trouvent dans des sous-répertoires différents ou dans des zones de préparation différentes.
Si vous n’avez plus besoin d’utiliser la procédure stockée (par exemple, si vous détruisez la procédure stockée), vous devez supprimer manuellement ce fichier JAR.

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 PROCEDURE	Schéma
USAGE	Procédure	L’attribution du privilège USAGE à un rôle sur la procédure nouvellement créée permet aux utilisateurs ayant ce rôle d’appeler la procédure ailleurs dans Snowflake.
USAGE	Intégration de l’accès externe	Requis pour les intégrations, s’il y en a, spécifiées par le paramètre EXTERNAL_ACCESS_INTEGRATIONS. Pour plus d’informations, consultez CREATE EXTERNAL ACCESS INTEGRATION.
READ	Secret	Requis pour les secrets, s’il y en a, spécifiés par le paramètre SECRETS. Pour plus d’informations, voir Création d’un secret pour représenter les identifiants de connexion et Utilisation de l’intégration de l’accès externe dans une fonction ou une procédure.
USAGE	Schéma	Obligatoire pour les schémas contenant des secrets, s’il y en a, spécifiés par le paramètre SECRETS. Pour plus d’informations, voir Création d’un secret pour représenter les identifiants de connexion et Utilisation de l’intégration de l’accès externe dans une fonction ou une procédure.

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¶

Pour toutes les procédures stockées :
- Les procédures stockées prennent en charge la surcharge. Deux procédures peuvent avoir le même nom si elles ont un nombre différent de paramètres ou un type de données différent pour leurs paramètres.
- Les procédures stockées ne sont pas atomiques ; si une instruction d’une procédure stockée échoue, les autres instructions de la procédure stockée ne sont pas nécessairement annulées. Pour des informations sur les procédures et les transactions stockées, voir Gestion des transactions.
- 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.
Astuce

Si votre organisation utilise une combinaison de procédures stockées relatives aux droits de l’appelant et aux droits du propriétaire, vous pouvez utiliser une convention de dénomination pour vos procédures stockées afin d’indiquer si une procédure stockée individuelle est une procédure stockée avec droits d’un appelant ou une procédure stockée avec droits du propriétaire.
Pour les procédures stockées JavaScript :
- Une procédure stockée JavaScript 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.
Pour les procédures stockées Java, voir les limitations connues.
Pour les procédures stockées Python, voir les limitations connues.
Pour les procédures stockées Scala, voir les limitations connues.

Exemples¶

Cela crée une procédure stockée triviale qui renvoie une valeur codée en dur. Cela n’est pas réaliste, mais affiche la syntaxe de base SQL avec un minimum de code JavaScript :

create or replace procedure sp_pi()
    returns float not null
    language javascript
    as
    $$
    return 3.1415926;
    $$
    ;

Copy

Voici un exemple plus réaliste incluant un appel à l’API JavaScript. Une version plus complète de cette procédure pourrait permettre à un utilisateur d’insérer des données dans une table dans laquelle l’utilisateur ne disposerait pas de privilèges nécessaires pour insérer directement des données. Des instructions JavaScript pourraient vérifier les paramètres d’entrée et exécuter la requête SQL INSERT uniquement si certaines conditions étaient remplies.

create or replace procedure stproc1(FLOAT_PARAM1 FLOAT)
    returns string
    language javascript
    strict
    execute as owner
    as
    $$
    var sql_command = 
     "INSERT INTO stproc_test_table1 (num_col1) VALUES (" + FLOAT_PARAM1 + ")";
    try {
        snowflake.execute (
            {sqlText: sql_command}
            );
        return "Succeeded.";   // Return a success/error indicator.
        }
    catch (err)  {
        return "Failed: " + err;   // Return a success/error indicator.
        }
    $$
    ;

Copy

Pour des exemples de procédures stockées Java, voir Écriture de procédures stockées en Java.
Pour des exemples de procédures stockées Python, voir Écriture de procédures stockées en Python.
Pour des exemples de procédures stockées Scala, voir Écriture de procédures stockées en Scala.
Pour des exemples de procédures stockées Exécution de scripts Snowflake, voir Écriture de procédures stockées dans Exécution de scripts Snowflake.

Pour plus d’exemples, voir Travailler avec des procédures stockées.