Exécution d’instructions SQL¶
Snowflake CLI vous permet d’exécuter des requêtes SQL, des requêtes ad hoc ou des fichiers contenant des requêtes SQL, en utilisant la commande snow sql.
Pour exécuter une requête ad hoc, lancez une commande similaire à la suivante :
snow sql -q "SELECT * FROM FOO"
Pour exécuter un fichier contenant une requête SQL, exécutez une commande similaire à la suivante :
snow sql -f my_query.sql
La commande snow sql
peut exécuter plusieurs instructions, auquel cas plusieurs jeux de résultats sont renvoyés. Par exemple en cours exécutant :
snow sql -q "select 'a', 'b'; select 'c', 'd';"
donne le résultat suivant :
select 'a', 'b';
+-----------+
| 'A' | 'B' |
|-----+-----|
| a | b |
+-----------+
select 'c', 'd';
+-----------+
| 'C' | 'D' |
|-----+-----|
| c | d |
+-----------+
Vous pouvez également exécuter les blocs d’exécution de scripts dans Snowflake CLI avec une mise en garde concernant le délimiteur $$
.
Par exemple :
EXECUTE IMMEDIATE $$
-- Snowflake Scripting code
DECLARE
radius_of_circle FLOAT;
area_of_circle FLOAT;
BEGIN
radius_of_circle := 3;
area_of_circle := pi() * radius_of_circle * radius_of_circle;
RETURN area_of_circle;
END;
$$
;
Certains systèmes d’exploitation interprètent $$
, comme un ID de processus (PID), au lieu de le reconnaître comme un délimiteur de bloc d’exécution de scripts. Pour remédier à cette limite, vous pouvez utiliser les alternatives suivantes :
Si vous souhaitez toujours spécifier le bloc d’exécution de scripts sur la ligne de commande, vous pouvez isoler les délimiteurs
$$
, comme dans\$\$
.Vous pouvez également placer le bloc d’exécution de scripts avec les délimiteurs par défaut
$$
dans un fichier séparé et l’appeler avec la commandesnow sql -f <filename>
.
Pour plus d’informations, voir la commande snow sql.
Utilisation de variables pour les modèles SQL¶
Dans certaines situations, vous pouvez souhaiter modifier vos requêtes SQL en fonction du contexte. La commande snow sql
prend en charge la substitution de variables côté client, ce qui vous permet d’utiliser des variables dans la commande qui sont résolues localement avant de soumettre la requête. Les variables de la chaîne SQL prennent la forme <% variable_name %>
, et l’option -D
(ou --variable
) spécifie la valeur de la variable.
Note
Vous pouvez actuellement utiliser la syntaxe SnowSQL
&variable_name
et<% variable_name %>
pour les modèles. Cependant, Snowflake recommande d’utiliser la<% variable_name %>
.
Par exemple, pour spécifier une base de données à l’aide d’une variable côté client, vous pouvez entrer une commande similaire à la suivante :
snow sql -q "select * from <% database %>.logs" -D "database=dev"
Lorsqu’elle est exécutée, la commande remplace la valeur dev
dans la variable <% database %>
pour créer le nom de fichier dev.logs
, puis envoie la requête select * from dev.logs
SQL à Snowflake en vue de son traitement.
Vous pouvez également spécifier plusieurs entrées variables, comme indiqué :
snow sql \
-q "grant usage on database <% database %> to <% role %>" \
-D "database=dev" \
-D "role=eng_rl"
Cet exemple génère la requête SQL suivante :
grant usage on database dev to eng_rl
Stockage de variables dans le fichier de définition du projet snowflake.yml
¶
Il n’est pas toujours pratique de spécifier des variables en tant qu’options de ligne de commande snow sql
, ou vous ne souhaitez peut-être pas spécifier des valeurs sensibles sur la ligne de commande. Dans ce cas, vous pouvez définir des variables et des valeurs dans le fichier de définition du projet snowflake.yml
. Vous pouvez alors spécifier les noms des variables sous la forme <% ctx.env.<variable_name> %>
au lieu d’utiliser l’option -D "<variable> = <valeur>"
.
En reprenant l’exemple de la section précédente, vous pourriez stocker la base de données et les variables de rôle dans le fichier snowflake.yml
et modifier la requête ainsi :
snow sql -q "grant usage on database <% ctx.env.database %> to <% ctx.env.role %>"
Dans cet exemple, la commande snow sql
recherche les définitions de variables dans le fichier de définition du projet et extrait les valeurs sans les rendre visibles sur la ligne de commande. Le fichier snowflake.yml
doit être situé soit dans le répertoire de travail actuel, soit à l’emplacement spécifié avec l’option -p
.
Pour plus d’informations sur l’enregistrement de ces valeurs dans le fichier de définition du projet, voir Utiliser des variables dans SQL.
Exécution asynchrone des requêtes SQL¶
Snowflake CLI vous permet d’exécuter une ou plusieurs requêtes SQL de manière asynchrone. Au lieu d’attendre un résultat, la commande snow sql
planifie les requêtes au niveau de Snowflake et renvoie un ID de requête. Une fois la requête terminée, vous pouvez obtenir le résultat en utilisant la commande de requête !result ou la commande SQL RESULT_SCAN.
Pour exécuter une requête SQL de manière asynchrone, terminez la requête par ; >
au lieu de ;
, comme indiqué :
snow sql -q 'select "My async query" ;>'
L’exemple suivant exécute une seule requête de manière asynchrone :
snow sql -q "select 'This is async query';>"
select 'This is async query'
+--------------------------------------+
| scheduled query ID |
|--------------------------------------|
| 01bc3011-080f-f2d7-0001-c1be14bae7c2 |
+--------------------------------------+
Vous pouvez ensuite utiliser l’ID de requête renvoyée dans la commande de requête !result pour afficher le résultat de la requête :
snow sql -q '!result 01bc3011-080f-f2d7-0001-c1be14bae7c2'
path-to-private-key-file
+-----------------------+
| 'THIS IS ASYNC QUERY' |
|-----------------------|
| This is async query |
+-----------------------+
Vous pouvez également exécuter plusieurs requêtes dans la chaîne de requête, à la fois de manière asynchrone et synchrone, comme indiqué :
snow sql -q "select 'This is async query';> select 'Not an async query'; select 'Another async query';>"
select 'This is async query'
+--------------------------------------+
| scheduled query ID |
|--------------------------------------|
| 01bc3b8c-0109-2e81-0000-0f2d0e5a4a32 |
+--------------------------------------+
select 'Not an async query';
+----------------------+
| 'NOT AN ASYNC QUERY' |
|----------------------|
| Not an async query |
+----------------------+
select 'Another async query'
+--------------------------------------+
| scheduled query ID |
|--------------------------------------|
| 01bc3b8c-0109-2e81-0000-0f2d0e5a4a36 |
+--------------------------------------+
Utilisation des commandes de requête SQL¶
Snowflake CLI fournit les commandes suivantes que vous pouvez utiliser dans vos requêtes SQL :
!source, qui exécute SQL dans les fichiers locaux ou les URLs.
!queries, qui répertorie toutes les requêtes SQL.
!result, qui affiche le résultat d’une requête SQL.
!abort, qui annule une requête SQL active.
Astuce
Si vous placez votre requête SQL entre guillemets doubles (""
) au lieu de guillemets simples (''
), vous devrez peut-être isoler le point d’exclamation (!
) en fonction de l’interpréteur que vous utilisez.
Exécuter SQL dans les fichiers locaux ou les URLs¶
Vous pouvez utiliser la commande de requête !source
dans votre requête SQL pour exécuter SQL dans les fichiers locaux ou dans un fichier basé l’URL. Par exemple, la commande suivante exécute toutes les commandes SQL dans un fichier local nommé my_sql_code.sql
:
snow sql -q '!source my_sql_code.sql'
Vous pouvez également imbriquer des commandes !source
dans les fichiers SQL, comme par exemple :
select emp_id FROM employees;
!source code_file_2.sql
Dans cet exemple, la commande exécute la requête SELECT, puis les commandes SQL dans le fichier code_file_2.sql
. Avant d’exécuter les requêtes !source
, Snowflake CLI effectue les opérations suivantes :
Évalue les substitutions de variables et les modèles.
Lit le contenu de tous les fichiers imbriqués pour s’assurer qu’il n’y a pas de récursivité.
Lorsque les variables et les modèles sont résolus et qu’aucune récursivité n’est détectée, la commande envoie le code à Snowflake pour exécution.
Note
Si vous utilisez des guillemets doubles (""
) au lieu de guillemets simples (''
) autour d’une requête !source
, vous devrez peut-être isoler !
(\!
) en fonction de l’interpréteur que vous utilisez.
Les exemples suivants illustrent différentes manières d’exécuter les fichiers sources.
Exécuter le code dans un fichier local.
Cet exemple suppose de disposer d’une requête simple dans un fichier local SQL.
cat code_to_execute.sql
select 73;
Pour exécuter le code contenu dans le fichier, entrez la commande suivante :
snow sql -q '!source code_to_execute.sql'
select 73; +----+ | 73 | |----| | 73 | +----+
Exécuter le code dans un fichier basé sur l’URL.
Cet exemple suppose de disposer de la même requête simple dans un fichier SQL au niveau de l’URL.
Pour exécuter le code contenu dans le fichier, entrez la commande suivante :
snow sql -q '!source https://trusted-host/trusted-content.sql'
select 73; +----+ | 73 | |----| | 73 | +----+
Exécuter un code qui utilise la substitution de variables et la modélisation.
Cet exemple suppose d’avoir une requête dans un fichier local SQL qui utilise une variable de modèle.
cat code_with_variable.sql
select '<% ctx.env.Message %>';
Pour exécuter le code contenu dans le fichier, entrez la commande suivante qui définit la valeur de la variable :
snow sql -q '!source code_&value.sql;' -D value=with_variable --env Message='Welcome !'
select 'Welcome !'; +-------------+ | 'WELCOME !' | |-------------| | Welcome ! | +-------------+
Note
La commande !source
prend en charge l’ancien alias !load
.
Répertorier toutes les requêtes SQL¶
La commande de requête !queries
répertorie toutes les requêtes pour un compte. Par défaut, la commande répertorie les 25 dernières requêtes exécutées dans la session en cours.
Par exemple, la commande de requête !queries
suivante renvoie les trois requêtes les plus récentes pour un utilisateur spécifique :
snow sql -q '!queries user=user1 amount=3'+-------------------------------------------------------------------------------------------------------------------------------------+ | QUERY ID | SQL TEXT | STATUS | DURATION_MS | |--------------------------------------+--------------------------------------------------------------------+-----------+-------------| | 01bc3040-080f-f4f9-0001-c1be14bb603a | select current_version(); | SUCCEEDED | 3858 | | 01bc303d-080f-f4e9-0001-c1be14bb1812 | SELECT SYSTEM$CANCEL_QUERY('01bc3011-080f-f2d7-0001-c1be14bae7c2') | SUCCEEDED | 564 | | 01bc3011-080f-f2d7-0001-c1be14bae7c2 | select 'This is async query' | SUCCEEDED | 931 | +-------------------------------------------------------------------------------------------------------------------------------------+
Vous pouvez utiliser les filtres suivants pour affiner la liste des requêtes renvoyées :
Filtre |
Par défaut |
Description |
---|---|---|
montant (entier) |
25 |
Nombre de requêtes récentes à renvoyer (par défaut : 25). |
session (boolean) |
N/A |
Si fournie, renvoyer uniquement les requêtes exécutées dans la session en cours. |
entrepôt (string) |
Aucun(e) |
Renvoyer uniquement les requêtes exécutées sur l’entrepôt spécifié. |
utilisateur (string) |
Aucun(e) |
Renvoyer uniquement les requêtes exécutées par l’utilisateur spécifié. |
durée (millisecondes) |
0 |
Renvoyer uniquement les requêtes dont l’exécution a duré au moins le nombre de millisecondes spécifié. |
start_date (string) |
Aucun(e) |
Renvoyer uniquement les requêtes exécutées après la date spécifiée. La date doit être fournie au format ISO (par exemple |
end_date (string) |
Aucun(e) |
Renvoyer uniquement les requêtes exécutées avant la date spécifiée. La date doit être fournie au format ISO (par exemple |
début (entier) |
Aucun(e) |
Renvoyer uniquement les requêtes exécutées après l’horodatage Unix spécifié (en millisecondes). |
fin (entier) |
Aucun(e) |
Renvoyer uniquement les requêtes exécutées avant l’horodatage Unix spécifié (en millisecondes). |
statut (enum) |
Aucun(e) |
Renvoyer uniquement les requêtes dans l’un des statuts suivants :
|
type |
Aucun(e) |
Renvoyer uniquement les requêtes de l’un des types suivants :
|
Les exemples suivants renvoient des requêtes utilisant différents filtres :
Renvoyer les 25 requêtes les plus récentes exécutées dans la session en cours :
snow sql -q 'select 42; select 15; !queries session'
Renvoyer les 20 requêtes les plus récentes exécutées dans le compte :
snow sql -q '!queries amount=20'
Renvoyer les 20 requêtes les plus récentes exécutées dans le compte et dont l’exécution a duré plus de 200 millisecondes :
snow sql -q '!queries amount=20 duration=200'
Renvoyer les 25 requêtes les plus récentes exécutées dans l’entrepôt spécifié :
snow sql -q '!queries warehouse=mywh'
Renvoyer le résultat d’une requête SQL terminée¶
La commande de requête !result
renvoie le résultat d’une requête terminée, compte tenu de son ID de requête. Vous pouvez obtenir l’ID de requête de la manière suivante :
Consultez la page Historique des requêtes dans Snowsight.
Exécutez la commande de requête
!queries
SQL.Utilisez l’ID renvoyé par une requête asynchrone.
snow sql -q '!result 01bc3011-080f-f2d7-0001-c1be14bae7c2'
+-----------------------+
| 'THIS IS ASYNC QUERY' |
|-----------------------|
| This is async query |
+-----------------------+
Annuler une requête SQL active¶
La commande de requête !abort
annule une requête active, compte tenu de son ID de requête. Vous pouvez obtenir l’ID de requête de la manière suivante :
Consultez la page Historique des requêtes dans Snowsight.
Exécutez la commande de requête
!queries
SQL.Utilisez l’ID renvoyé par une requête asynchrone.
snow sql -q '!abort 01bc3011-080f-f2d7-0001-c1be14bae7c2'
+-------------------------------------------------------------+
| SYSTEM$CANCEL_QUERY('01BC3011-080F-F2D7-0001-C1BE14BAE7C2') |
|-------------------------------------------------------------|
| Identified SQL statement is not currently executing. |
+-------------------------------------------------------------+
Saisie de plusieurs commandes dans une même transaction¶
L’option --single-transaction
vous permet de saisir plusieurs commandes SQL à exécuter comme un ensemble de commandes « tout ou rien ». En exécutant les commandes dans une seule transaction, vous pouvez vous assurer que toutes les commandes ont été exécutées avec succès avant de valider les modifications. Si l’une des commandes échoue, aucune des modifications apportées par les commandes abouties n’est maintenue.
Les exemples suivants montrent des transactions abouties et non abouties :
Exécution de commande aboutie
snow sql -q "insert into my_tbl values (123); insert into my_tbl values (124);" --single-transaction
BEGIN; +----------------------------------+ | status | |----------------------------------| | Statement executed successfully. | +----------------------------------+ insert into my_tbl values (123); +-------------------------+ | number of rows inserted | |-------------------------| | 1 | +-------------------------+ insert into my_tbl values (124); +-------------------------+ | number of rows inserted | |-------------------------| | 1 | +-------------------------+ COMMIT +----------------------------------+ | status | |----------------------------------| | Statement executed successfully. | +----------------------------------+
Vous pouvez alors vérifier que les commandes ont été validées dans la base de données :
snow sql -q "select count(*) from my_tbl"
select count(*) from my_tbl +----------+ | COUNT(*) | |----------| | 2 | +----------+
Transaction unique infructueuse
snow sql -c patcli -q "insert into my_tbl values (123); insert into my_tbl values (124); select BAD;" --single-transaction
BEGIN; +----------------------------------+ | status | |----------------------------------| | Statement executed successfully. | +----------------------------------+ insert into my_tbl values (123); +-------------------------+ | number of rows inserted | |-------------------------| | 1 | +-------------------------+ insert into my_tbl values (124); +-------------------------+ | number of rows inserted | |-------------------------| | 1 | +-------------------------+ select BAD; ╭─ Error ───────────────────────────────────────────────────────────────────────────────╮ │ 000904 (42000): 01bc3b84-0810-0247-0001-c1be14ee11ce: SQL compilation error: error │ │ line 1 at position 7 │ │ invalid identifier 'BAD' │ ╰───────────────────────────────────────────────────────────────────────────────────────╯
Vous pouvez alors vérifier que les commandes n’ont pas été validées dans la base de données :
snow sql -q "select count(*) from my_tbl"select count(*) from my_tbl +----------+ | COUNT(*) | |----------| | 0 | +----------+
Saisie de commandes SQL en mode interactif¶
La commande snow sql
prend en charge un mode interactif qui vous permet de saisir des commandes SQL une par une. Le mode interactif offre les fonctions suivantes :
Mise en évidence de la syntaxe
Complétion du code lors de la frappe
Historique consultable
En appuyant sur CTRL-R: vous pouvez effectuer une recherche dans l’historique de vos commandes :
Entrée multilignes
En appuyant sur ENTER sur une ligne qui ne se termine pas par un point-virgule (
;
), le curseur passe à la ligne suivante pour d’autres commandes jusqu’à ce qu’une instruction se termine par un point-virgule.
Pour utiliser le mode interactif, entrez la commande snow sql
, suivie de ENTER, comme indiqué :
snow sql
La commande ouvre un sous-interpréteur avec une invite >
où vous pouvez entrer des commandes SQL de manière interactive :
$ snow sql
╭───────────────────────────────────────────────────────────────────────────────────╮
│ Welcome to Snowflake-CLI REPL │
│ Type 'exit' or 'quit' to leave │
╰───────────────────────────────────────────────────────────────────────────────────╯
>
Vous pouvez ensuite entrer les commandes SQL, comme indiqué :
> create table my_table (c1 int);
+-------------------------------------+
| status |
|-------------------------------------|
| Table MY_TABLE successfully created.|
+-------------------------------------+
Note
Vous devez terminer chaque instruction SQL par un point-virgule (;
).
Pour quitter le mode interactif, entrez exit
, quit
, ou CTRL-D.