UDFs d’exécution de scripts Snowflake¶
Snowflake prend en charge les fonctions définies par l’utilisateur (UDFs) SQL qui contiennent le langage procédural Exécution de scripts Snowflake. Ces UDFs sont appelés UDFs d’exécution de scripts Snowflake.
Les UDFs d’exécution de scripts Snowflake peuvent être appelées dans une instruction SQL, telle qu’une instruction SELECT ou une instruction INSERT. Par conséquent, elles sont plus flexibles qu’une procédure stockée d’exécution de scripts Snowflake, qui ne peut être appelée que dans une commande SQL CALL.
Utilisation générale¶
Une UDF d’exécution de scripts Snowflake évalue le code procédural et renvoie une valeur scalaire (c’est-à-dire unique).
Vous pouvez utiliser le sous-ensemble suivant de la syntaxe d”exécution de scripts Snowflake dans les UDFs d’exécution de scripts Snowflake :
Types de données pris en charge¶
Les UDFs d’exécution de scripts Snowflake prennent en charge les types de données suivants pour les arguments d’entrée et les valeurs de retour :
Types de données numériques (par exemple, INTEGER, NUMBER et FLOAT)
Types de données Chaîne et Binaire (par exemple, VARCHAR et BINARY)
Types de données de date et heure (par exemple, DATE, TIME, et TIMESTAMP)
Types de données logiques (par exemple, BOOLEAN)
Les UDFs d’exécution de scripts Snowflake prennent en charge les types de données suivants pour les arguments d’entrée uniquement :
Types de données semi-structurées (par exemple, VARIANT, OBJECT, et ARRAY)
Types de données structurés (par exemple, ARRAY, OBJECT et MAP)
Limitations¶
Les limitations suivantes s’appliquent aux UDFs d’exécution de scripts Snowflake :
Les types suivants de la syntaxe d’exécution de scripts Snowflake ne sont pas pris en charge dans les UDFs d’exécution de scripts Snowflake :
Les instructions SQL ne sont pas prises en charge dans les UDFs d’exécution de scripts Snowflake (y compris SELECT, INSERT, UPDATE, etc.).
Les UDFs d’exécution de scripts Snowflake ne peuvent pas être définies en tant que fonctions de table.
Les types d’expressions suivants ne sont pas pris en charge dans les UDFs d’exécution de scripts Snowflake :
Fonctions définies par l’utilisateur
Fonctions d’agrégation
Fonctions de fenêtre
Les UDFs d’exécution de scripts Snowflake ne peuvent pas être utilisées lors de la création d’une vue matérialisée.
Les UDFs d’exécution de scripts Snowflake ne peuvent pas être utilisées lors de la création de politiques d’accès aux lignes et de politiques de masquage.
Les UDFs d’exécution de scripts Snowflake ne peuvent pas être utilisées pour spécifier une valeur de colonne par défaut.
Les UDFs d’exécution de scripts Snowflake ne peuvent pas être utilisées dans une commande COPY INTO pour le chargement et le déchargement de données.
Les UDFs d’exécution de scripts Snowflake ne sont pas mémorisable.
Les UDFs d’exécution de scripts Snowflake ont une limite de 500 arguments d’entrée.
Vous ne pouvez pas enregistrer de messages pour les UDFs d’exécution de scripts Snowflake.
Exemples¶
Les exemples suivants créent et appellent des UDFs d’exécution de scripts Snowflake :
Créer une UDF d’exécution de scripts Snowflake avec des variables
Créer une UDF d’exécution de scripts Snowflake avec une logique conditionnelle
Créer une UDF d’exécution de scripts Snowflake avec une boucle
Créer une UDF d’exécution de scripts Snowflake avec traitement des exceptions
Créer une UDF d’exécution de scripts Snowflake qui renvoie une valeur pour une instruction INSERT
Créer une UDF d’exécution de scripts Snowflake appelée dans les clauses WHERE et ORDER BY
Créer une UDF d’exécution de scripts Snowflake avec des variables¶
Créer une UDF d’exécution de scripts Snowflake qui calcule le bénéfice en fonction des valeurs de deux arguments :
CREATE OR REPLACE FUNCTION calculate_profit(
cost NUMBER(38, 2),
revenue NUMBER(38, 2))
RETURNS number(38, 2)
LANGUAGE SQL
AS
DECLARE
profit NUMBER(38, 2) DEFAULT 0.0;
BEGIN
profit := revenue - cost;
RETURN profit;
END;
Note
Si vous utilisez Snowflake CLI, SnowSQL, le Classic Console, ou la méthode execute_stream
ou execute_string
dans le code de connecteur Python, vous devez apporter quelques modifications mineures à cet exemple. Pour plus d’informations, voir Utilisation de Snowflake Scripting dans Snowflake CLI, SnowSQL, le Classic Console et le connecteur Python.
Appeler calculate_profit
dans une requête :
SELECT calculate_profit(100, 110);
+----------------------------+
| CALCULATE_PROFIT(100, 110) |
|----------------------------|
| 10.00 |
+----------------------------+
Vous pouvez utiliser la même UDF d’exécution de scripts Snowflake et spécifier des colonnes pour les arguments. Créer une table en premier et insérer des données :
CREATE OR REPLACE TABLE snowflake_scripting_udf_profit(
cost NUMBER(38, 2),
revenue NUMBER(38, 2));
INSERT INTO snowflake_scripting_udf_profit VALUES
(100, 200),
(200, 190),
(300, 500),
(400, 401);
Appeler calculate_profit
dans une requête et spécifier les colonnes pour les arguments :
SELECT calculate_profit(cost, revenue)
FROM snowflake_scripting_udf_profit;
+---------------------------------+
| CALCULATE_PROFIT(COST, REVENUE) |
|---------------------------------|
| 100.00 |
| -10.00 |
| 200.00 |
| 1.00 |
+---------------------------------+
Créer une UDF d’exécution de scripts Snowflake avec une logique conditionnelle¶
Créer une UDF d’exécution de scripts Snowflake qui utilise une logique conditionnelle pour déterminer le nom du département en fonction d’une valeur INTEGER d’entrée :
CREATE OR REPLACE function check_dept(department_id INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
BEGIN
IF (department_id < 3) THEN
RETURN 'Engineering';
ELSEIF (department_id = 3) THEN
RETURN 'Tool Design';
ELSE
RETURN 'Marketing';
END IF;
END;
Note
Si vous utilisez Snowflake CLI, SnowSQL, le Classic Console, ou la méthode execute_stream
ou execute_string
dans le code de connecteur Python, vous devez apporter quelques modifications mineures à cet exemple. Pour plus d’informations, voir Utilisation de Snowflake Scripting dans Snowflake CLI, SnowSQL, le Classic Console et le connecteur Python.
Appeler check_dept
dans une requête :
SELECT check_dept(2);
+---------------+
| CHECK_DEPT(2) |
|---------------|
| Engineering |
+---------------+
Vous pouvez utiliser une variable SQL dans un argument lorsque vous appelez une UDF d’exécution de scripts Snowflake. L’exemple suivant définit une variable SQL et utilise ensuite la variable dans un appel à l’UDF check_dept
:
SET my_variable = 3;
SELECT check_dept($my_variable);
+--------------------------+
| CHECK_DEPT($MY_VARIABLE) |
|--------------------------|
| Tool Design |
+--------------------------+
Créer une UDF d’exécution de scripts Snowflake avec une boucle¶
Créer une UDF d’exécution de scripts Snowflake qui utilise une boucle pour compter tous les nombres jusqu’à un nombre cible fourni dans un argument et calculer la somme de tous les nombres comptés :
CREATE OR REPLACE function count_to(
target_number INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
DECLARE
counter INTEGER DEFAULT 0;
sum_total INTEGER DEFAULT 0;
BEGIN
WHILE (counter < target_number) DO
counter := counter + 1;
sum_total := sum_total + counter;
END WHILE;
RETURN 'Counted to ' || counter || '. Sum of all numbers: ' || sum_total;
END;
Note
Si vous utilisez Snowflake CLI, SnowSQL, le Classic Console, ou la méthode execute_stream
ou execute_string
dans le code de connecteur Python, vous devez apporter quelques modifications mineures à cet exemple. Pour plus d’informations, voir Utilisation de Snowflake Scripting dans Snowflake CLI, SnowSQL, le Classic Console et le connecteur Python.
Appeler count_to
dans une requête :
SELECT count_to(10);
+---------------------------------------+
| COUNT_TO(10) |
|---------------------------------------|
| Counted to 10. Sum of all numbers: 55 |
+---------------------------------------+
Créer une UDF d’exécution de scripts Snowflake avec traitement des exceptions¶
Créer une UDF d’exécution de scripts Snowflake qui déclare une exception et soulève ensuite l’exception :
CREATE OR REPLACE FUNCTION raise_exception(input_value INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
DECLARE
counter_val INTEGER DEFAULT 0;
my_exception EXCEPTION (-20002, 'My exception text');
BEGIN
WHILE (counter_val < 12) DO
counter_val := counter_val + 1;
IF (counter_val > 10) THEN
RAISE my_exception;
END IF;
END WHILE;
RETURN counter_val;
EXCEPTION
WHEN my_exception THEN
IF (input_value = 1) THEN
RETURN 'My exception caught: ' || sqlcode;
ELSEIF (input_value = 2) THEN
RETURN 'My exception caught with different path: ' || sqlcode;
END IF;
RETURN 'Default exception handling path: ' || sqlcode;
END;
Note
Si vous utilisez Snowflake CLI, SnowSQL, le Classic Console, ou la méthode execute_stream
ou execute_string
dans le code de connecteur Python, vous devez apporter quelques modifications mineures à cet exemple. Pour plus d’informations, voir Utilisation de Snowflake Scripting dans Snowflake CLI, SnowSQL, le Classic Console et le connecteur Python.
Appeler raise_exception
dans une requête et spécifier 1
pour la valeur d’entrée :
SELECT raise_exception(1);
+-----------------------------+
| RAISE_EXCEPTION(1) |
|-----------------------------|
| My exception caught: -20002 |
+-----------------------------+
Appeler raise_exception
dans une requête et spécifier 2
pour la valeur d’entrée :
SELECT raise_exception(2);
+-------------------------------------------------+
| RAISE_EXCEPTION(2) |
|-------------------------------------------------|
| My exception caught with different path: -20002 |
+-------------------------------------------------+t
Appeler raise_exception
dans une requête et spécifier NULL
pour la valeur d’entrée :
SELECT raise_exception(NULL);
+-----------------------------------------+
| RAISE_EXCEPTION(NULL) |
|-----------------------------------------|
| Default exception handling path: -20002 |
+-----------------------------------------+
Créer une UDF d’exécution de scripts Snowflake qui renvoie une valeur pour une instruction INSERT¶
Créer une UDF d’exécution de scripts Snowflake qui renvoie une valeur utilisée dans une instruction INSERT. Créer la table dans laquelle les valeurs seront insérées :
CREATE OR REPLACE TABLE test_sql_udf_insert (num NUMBER);
Créer une UDF SQL qui renvoie une valeur numérique :
CREATE OR REPLACE FUNCTION value_to_insert(l NUMBER, r NUMBER)
RETURNS number
LANGUAGE SQL
AS
BEGIN
IF (r < 0) THEN
RETURN l/r * -1;
ELSEIF (r > 0) THEN
RETURN l/r;
ELSE
RETURN 0;
END IF;
END;
Note
Si vous utilisez Snowflake CLI, SnowSQL, le Classic Console, ou la méthode execute_stream
ou execute_string
dans le code de connecteur Python, vous devez apporter quelques modifications mineures à cet exemple. Pour plus d’informations, voir Utilisation de Snowflake Scripting dans Snowflake CLI, SnowSQL, le Classic Console et le connecteur Python.
Appeler value_to_insert
dans plusieurs instructions INSERT :
INSERT INTO test_sql_udf_insert SELECT value_to_insert(10, 2);
INSERT INTO test_sql_udf_insert SELECT value_to_insert(10, -2);
INSERT INTO test_sql_udf_insert SELECT value_to_insert(10, 0);
Interroger la table pour afficher les valeurs insérées :
SELECT * FROM test_sql_udf_insert;
+-----+
| NUM |
|-----|
| 5 |
| 5 |
| 0 |
+-----+
Créer une UDF d’exécution de scripts Snowflake appelée dans les clauses WHERE et ORDER BY¶
Créer une UDF d’exécution de scripts Snowflake qui renvoie une valeur utilisée dans une clause WHERE ou ORDER BY. Créer une table et insérer des valeurs :
CREATE OR REPLACE TABLE test_sql_udf_clauses (p1 INT, p2 INT);
INSERT INTO test_sql_udf_clauses VALUES
(100, 7),
(100, 3),
(100, 4),
(NULL, NULL);
Créer une UDF SQL qui renvoie une valeur numérique qui est le produit de la multiplication de deux valeurs d’entrée :
CREATE OR REPLACE FUNCTION get_product(a INTEGER, b INTEGER)
RETURNS VARCHAR
LANGUAGE SQL
AS
BEGIN
RETURN a * b;
END;
Note
Si vous utilisez Snowflake CLI, SnowSQL, le Classic Console, ou la méthode execute_stream
ou execute_string
dans le code de connecteur Python, vous devez apporter quelques modifications mineures à cet exemple. Pour plus d’informations, voir Utilisation de Snowflake Scripting dans Snowflake CLI, SnowSQL, le Classic Console et le connecteur Python.
Appeler get_product
dans la clause WHERE d’une requête pour renvoyer les lignes où le produit est supérieur à 350
:
SELECT *
FROM test_sql_udf_clauses
WHERE get_product(p1, p2) > 350;
+-----+----+
| P1 | P2 |
|-----+----|
| 100 | 7 |
| 100 | 4 |
+-----+----+
Appeler get_product
dans la clause ORDER BY d’une requête pour classer les résultats du produit du plus bas au plus élevé renvoyés par l’UDF :
SELECT *
FROM test_sql_udf_clauses
ORDER BY get_product(p1, p2);
+------+------+
| P1 | P2 |
|------+------|
| 100 | 3 |
| 100 | 4 |
| 100 | 7 |
| NULL | NULL |
+------+------+