Variables SQL¶

Vous pouvez définir et utiliser des variables SQL dans les sessions dans Snowflake.

Vue d’ensemble¶

Snowflake prend en charge les variables SQL déclarées par l’utilisateur. Elles ont de nombreuses utilisations, telles que le stockage de paramètres d’environnement spécifiques à l’application.

Identificateurs de variables¶

Les variables SQL sont identifiées globalement à l’aide de noms insensibles à la casse.

DDL de variables¶

Snowflake fournit les commandes DDL suivantes pour l’utilisation des variables SQL :

Initialisation des variables¶

Vous pouvez définir des variables en exécutant l’instruction SQL SET ou en définissant les variables dans la chaîne de connexion lorsque vous vous connectez à Snowflake.

La taille des chaînes ou des variables binaires est limitée à 256 octets.

Utilisation de SQL pour initialiser des variables dans une session¶

Vous pouvez initialiser des variables dans SQL à l’aide de la commande SET. Le type de données de la variable s’appuie sur le type de données du résultat de l’expression évaluée. Les exemples suivants initialisent des variables :

SET my_variable1 = 10;
SET my_variable2 = 'example';

Vous pouvez initialiser des variables à l’aide de requêtes qui renvoient un seul résultat. Les exemples suivants initialisent des variables à l’aide de requêtes :

SET cust_last_name = (SELECT lname FROM customers WHERE customer_id=100);
SET timestamp_variable = (SELECT CURRENT_TIMESTAMP());

Vous pouvez initialiser plusieurs variables dans la même instruction, réduisant ainsi le nombre de communications aller-retour avec le serveur. Les exemples suivants initialisent plusieurs variables :

SET (var1, var2, var3) = (10, 20, 30);
SET (current_user, current_warehouse) = ((SELECT CURRENT_USER()), (SELECT CURRENT_WAREHOUSE()));

Définition des variables à la connexion¶

En plus d’utiliser SET pour définir des variables dans une session, vous pouvez transmettre des variables en arguments dans la chaîne de connexion utilisée pour initialiser une session dans Snowflake. Cette option est particulièrement utile lorsque vous utilisez des outils où la spécification de la chaîne de connexion est la seule personnalisation possible.

Par exemple, en utilisant le pilote JDBC de Snowflake, vous pouvez définir des propriétés de connexion supplémentaires qui seront interprétées comme des paramètres. Notez que l’API JDBC nécessite que des variables SQL soient des chaînes.

// Build connection properties
Properties properties = new Properties();

// Required connection properties
properties.put("user"    ,  "jsmith"      );
properties.put("password",  "mypassword");
properties.put("account" ,  "myaccount");

// Set some additional variables.
properties.put("$variable_1", "some example");
properties.put("$variable_2", "1"           );

// Create a new connection
String connectStr = "jdbc:snowflake://localhost:8080";

// Open a connection under the snowflake account and enable variable support
Connection con = DriverManager.getConnection(connectStr, properties);

Utilisation des variables dans SQL¶

Des variables peuvent être utilisées dans Snowflake partout où une constante littérale est permise, sauf dans les cas indiqués dans la documentation. Pour les distinguer des valeurs de liaison et des noms de colonnes, toutes les variables doivent être préfixées par un signe $.

Par exemple :

SET (min, max)=(40, 70);

SELECT $min;

SELECT AVG(salary) FROM emp WHERE age BETWEEN $min AND $max;

Note

Puisque le signe $ est le préfixe utilisé pour identifier les variables dans des instructions SQL, il est traité comme un caractère spécial lorsqu’il est utilisé dans des identificateurs. Les identificateurs (noms de base de données, noms de tables, noms de colonnes, etc.) ne peuvent pas commencer par des caractères spéciaux, à moins que le nom entier soit entre guillemets doubles. Pour plus d’informations, voir Identificateurs d’objet.

Les variables peuvent également contenir des noms d’identificateur, tels que des noms de table. Pour utiliser une variable en tant qu’identificateur, vous devez l’envelopper dans IDENTIFIER() (par exemple, IDENTIFIER($my_variable)). Quelques exemples ci-dessous :

SET my_table_name='table1';

CREATE TABLE IDENTIFIER($my_table_name) (i INTEGER);
INSERT INTO IDENTIFIER($my_table_name) (i) VALUES (42);

SELECT * FROM IDENTIFIER($my_table_name);

+----+
|  I |
|----|
| 42 |
+----+

Dans le contexte d’une clause FROM, vous pouvez envelopper le nom de la variable dans TABLE(), comme indiqué ci-dessous :

SELECT * FROM TABLE($my_table_name);

+----+
|  I |
|----|
| 42 |
+----+

DROP TABLE IDENTIFIER($my_table_name);

Pour plus d’informations sur IDENTIFIER(), voir Littéraux et variables comme identificateurs avec la syntaxe IDENTIFIER().

Voir des variables de la session¶

Pour voir toutes les variables définies dans la session actuelle, utilisez la commande SHOW VARIABLES :

SET (min, max)=(40, 70);

+----------------------------------+
| status                           |
|----------------------------------|
| Statement executed successfully. |
+----------------------------------+

SHOW VARIABLES;

+----------------+-------------------------------+-------------------------------+------+-------+-------+---------+
|     session_id | created_on                    | updated_on                    | name | value | type  | comment |
|----------------+-------------------------------+-------------------------------+------+-------+-------+---------|
| 10363773891062 | 2024-06-28 10:09:57.990 -0700 | 2024-06-28 10:09:58.032 -0700 | MAX  | 70    | fixed |         |
| 10363773891062 | 2024-06-28 10:09:57.990 -0700 | 2024-06-28 10:09:58.021 -0700 | MIN  | 40    | fixed |         |
+----------------+-------------------------------+-------------------------------+------+-------+-------+---------+

Fonctions des variables de session¶

Les fonctions de commodité suivantes sont fournies pour manipuler des variables de session afin d’assurer la compatibilité avec d’autres systèmes de base de données et d’émettre des commandes SQL au moyen d’outils qui ne prennent pas en charge la syntaxe $ d’accès aux variables. Toutes ces fonctions acceptent et retournent des valeurs de variables de session sous forme de chaînes :

SYS_CONTEXT et SET_SYS_CONTEXT

SESSION_CONTEXT et SET_SESSION_CONTEXT

GETVARIABLE et SETVARIABLE

Voici des exemples d’utilisation de GETVARIABLE. Définissez d’abord une variable en utilisant SET :

SET var_artist_name = 'Jackson Browne';

+----------------------------------+
| status                           |
+----------------------------------+
| Statement executed successfully. |
+----------------------------------+

Renvoyez la valeur de la variable :

SELECT GETVARIABLE('var_artist_name');

Dans cet exemple, la sortie est NULL car Snowflake stocke les variables avec des lettres majuscules.

Mise à jour de la casse :

SELECT GETVARIABLE('VAR_ARTIST_NAME');

+--------------------------------+
| GETVARIABLE('VAR_ARTIST_NAME') |
+--------------------------------+
| Jackson Browne                 |
+--------------------------------+

Vous pouvez utiliser le nom de la variable dans une clause WHERE, par exemple :

SELECT album_title
  FROM albums
  WHERE artist = $var_artist_name;

Suppression des variables¶

Les variables SQL sont privées dans une session. Lorsqu’une session Snowflake est fermée, toutes les variables créées pendant la session sont détruites. Cela signifie que personne ne peut accéder aux variables définies par l’utilisateur qui ont été définies dans une autre session, et lorsque la session est fermée, ces variables expirent.

De plus, les variables peuvent être explicitement supprimées en utilisant la commande UNSET.

Par exemple :

UNSET my_variable;