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 :

Les UDFs d’exécution de scripts Snowflake prennent en charge les types de données suivants pour les arguments d’entrée uniquement :

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 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;
Copy

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);
Copy
+----------------------------+
| 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);
Copy

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;
Copy
+---------------------------------+
| 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;
Copy

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);
Copy
+---------------+
| 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);
Copy
+--------------------------+
| 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;
Copy

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);
Copy
+---------------------------------------+
| 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;
Copy

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);
Copy
+-----------------------------+
| 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);
Copy
+-------------------------------------------------+
| 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);
Copy
+-----------------------------------------+
| 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);
Copy

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;
Copy

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);
Copy

Interroger la table pour afficher les valeurs insérées :

SELECT * FROM test_sql_udf_insert;
Copy
+-----+
| 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);
Copy

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;
Copy

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;
Copy
+-----+----+
|  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);
Copy
+------+------+
|  P1  | P2   |
|------+------|
| 100  | 3    |
| 100  | 4    |
| 100  | 7    |
| NULL | NULL |
+------+------+