Utilisation de SnowSQL¶

Définition de variables¶

Vous pouvez définir des variables pour SnowSQL de plusieurs façons :

• Définition de variables avant la connexion (fichier de configuration)

• Définition de variables pendant la connexion (indicateur de ligne de commande -D ou --variable)

• Définition de variables dans une session (commande !define)

Activation de la substitution de variables¶

Pour permettre à SnowSQL de substituer des valeurs aux variables, vous devez définir l’option de configuration variable_substitution sur true de l’une des manières suivantes :

• Pour définir cette option avant de lancer SnowSQL, ouvrez le fichier de configuration SnowSQL dans un éditeur de texte, et définissez cette option dans la section [options] :

  [options]
  variable_substitution = True
  

  Copy

• Pour définir cette option lorsque vous démarrez SnowSQL, spécifiez l’indicateur de ligne de commande -o :

  $ snowsql ... -o variable_substitution=true
  

  Copy

• Pour définir cette option dans une session SnowSQL, exécutez la commande !set dans la session :

  user#> !set variable_substitution=true
  

  Copy

  Note

  Il n’y a actuellement aucune option pour annuler la définition d’une valeur d’option, telle que l’option variable_substitution . Si vous devez désactiver la substitution de variable, exécutez la commande !set variable_substitution=false.

Substitution de variables dans une session¶

Après avoir activé la substitution de variables, vous pouvez utiliser des variables dans des instructions SQL.

Pour utiliser une variable dans une instruction, utilisez la syntaxe &variable_name . Notez que les noms de variables sont insensibles à la casse. Par exemple :

user#> !define snowshell=bash

user#> !set variable_substitution=true

user#> select '&snowshell';

+--------+
| 'BASH' |
|--------|
| bash   |
+--------+

Copy

Si l’option variable_substitution n’est pas activée, aucune substitution de variable ne se produit. Par exemple :

user#> !define snowshell=bash

user#> !set variable_substitution=false

user#> select '&snowshell';

+--------------+
| '&SNOWSHELL' |
|--------------|
| &snowshell   |
+--------------+

Copy

Si vous faites référence à une variable qui n’a pas été définie, SnowSQL affiche une erreur. Par exemple :

select '&z';

Variable z is not defined

Copy

Pour combiner une variable avec du texte, placez la référence de variable entre accolades. Par exemple :

user#> !define snowshell=bash

user#> !set variable_substitution=true

select '&{snowshell}_shell';

+--------------+
| 'BASH_SHELL' |
|--------------|
| bash_shell   |
+--------------+

Copy

Pour utiliser une esperluette sans utiliser de substitution, isolez l’esperluette à l’aide d’une deuxième esperluette :

&&variable

Par exemple :

user#> !set variable_substitution=true

user#> select '&notsubstitution';

Variable notsubstitution is not defined

user#> select '&&notsubstitution';

+--------------------+
| '&NOTSUBSTITUTION' |
|--------------------|
| &notsubstitution   |
+--------------------+

Copy

Affichage de variables¶

Pour afficher les variables, exécutez la commande !variables ou !vars dans la session :

user#> !variables

+-----------+-------+
| Name      | Value |
|-----------+-------|
| snowshell | bash  |
+-----------+-------+

Copy

Utilisation des variables intégrées¶

SnowSQL inclut un ensemble de variables intégrées qui renvoient des métadonnées sur les instructions exécutées dans la session utilisateur en cours.

Chacun de ces noms de variable commence par deux tirets bas (« __ »).

__rowcount

Renvoie le nombre de lignes affectées par la dernière instruction DML exécutée par l’utilisateur.

user#> insert into a values(1),(2),(3);

+-------------------------+
| number of rows inserted |
|-------------------------|
|                       3 |
+-------------------------+
3 Row(s) produced. Time Elapsed: 0.950s

user#> !set variable_substitution=true

user#> select &__rowcount;

+---+
| 3 |
|---|
| 3 |
+---+

Copy

__sfqid

Renvoie l’ID de la requête la plus récente exécutée par l’utilisateur.

user#> !set variable_substitution=true

user#> select * from a;

user#> select '&__sfqid';

+----------------------------------------+
| 'A5F35B56-49A2-4437-BA0E-998496CE793E' |
|----------------------------------------|
| a5f35b56-49a2-4437-ba0e-998496ce793e   |
+----------------------------------------+

Copy

Fichier Historique¶

Le fichier historique interactif de ligne de commande est nommé history et se trouve dans le répertoire ~/.snowsql/history.

Exécution pendant la connexion (paramètre de connexion -f)¶

Pour exécuter un script SQL en se connectant à Snowflake, utilisez le paramètre de connexion -f <nom_fichier_entrée> :

Un fichier de sortie pour le script peut être spécifié en utilisant -o output_file=<nom_fichier_sortie>. De plus, vous pouvez utiliser -o quiet=true pour désactiver la sortie standard et -o friendly=false pour désactiver les messages de démarrage et de sortie.

Par exemple :

snowsql -a myorganization-myaccount -u jsmith -f /tmp/input_script.sql -o output_file=/tmp/output.csv -o quiet=true -o friendly=false -o header=false -o output_format=csv

Copy

Pour plus d’informations sur tous les paramètres de connexion, voir Référence Paramètres de connexion.

Exécution dans une session (commande !source ou !load)¶

Pour exécuter un script SQL après la connexion à Snowflake, exécutez la commande !source (ou !load) dans la session.

Par exemple :

user#> !source example.sql

Copy

Jetons pris en charge¶

SnowSQL prend en charge les types d’objet suivants en tant que jeton :

• user

• account

• role

• database

• schema

• warehouse

Invite par défaut¶

L’invite par défaut SnowSQL utilise les jetons et la structure suivant :

[user]#[warehouse]@[database].[schema]>

Copy

Par exemple :

jdoe#DATALOAD@BOOKS_DB.PUBLIC>

Copy

Exemple d’invite¶

Pour poursuivre l’exemple ci-dessus, la commande !set suivante exécutée dans la ligne de commande ajoute le jeton de rôle et modifie l’ordre des jetons en user et role, database, et schema, puis warehouse. Elle modifie également le délimiteur de chaque jeton par un point (.) et définit les jetons de façon à utiliser différentes couleurs :

jdoe#DATALOAD@BOOKS_DB.PUBLIC> !set prompt_format=[#FF0000][user].[role].[#00FF00][database].[schema].[#0000FF][warehouse]>

Copy

Cet exemple donne lieu à l’invite suivante pour la session :

Codes de sortie¶

Il existe plusieurs codes de sortie possibles qui sont renvoyés lorsque SnowSQL se ferme.

0:

Tout s’est bien passé.

1:

Une erreur est survenue avec le client.

2:

Une erreur est survenue avec les arguments de ligne de commande.

3:

SnowSQL n’a pas pu contacter le serveur.

4:

SnowSQL n’a pas pu communiquer correctement avec le serveur.

5:

L’option de configuration exit_on_error a été définie et SnowSQL s’est fermé à cause d’une erreur.

!abort¶

Annule une requête (spécifiée par l’ID de requête). L’ID de requête peut être obtenu à partir de la page History dans l’interface Web.

Par exemple :

user#> !abort 77589bd1-bcbf-4ec8-9ebc-6c949b00614d;

Copy

!connect¶

SnowSQL prend en charge les sessions multiples (c’est-à-dire les connexions) avec !connect <nom_connexion> :

• Les paramètres/options de connexion associés à connection_name sont stockés dans la section [connections.<nom_connexion>] correspondante du fichier de configuration SnowSQL.

• Si un paramètre/option n’est pas spécifié dans la section [connections.<nom_connexion>] , le paramètre non spécifié correspondra par défaut aux paramètres dans [connections].

Lorsque vous vous connectez, la connexion est ajoutée à votre pile de connexions, et le fait de quitter vous ramènera à votre connexion précédente. Quitter fermera toutes vos connexions, quel que soit le nombre de connexions que vous avez.

Par exemple :

Fichier de configuration :

[connections.my_example_connection]
...

Copy

Ligne de commande :

user#> !connect my_example_connection

Copy

!define¶

Définit une variable sur une valeur spécifiée, en utilisant le format suivant :

!define <nom_variable>=<valeur_variable>

Le nom et la valeur doivent être séparés par un seul = sans espaces. Les caractères valides qui peuvent être utilisés dans la variable sont les suivants :

0-9a-zA-Z_

Pour plus d’informations sur la définition et l’utilisation des variables, voir Utilisation de variables.

!edit¶

Ouvre l’éditeur qui a été configuré à l’aide du paramètre de connexion editor (si aucun éditeur n’a été configuré, la valeur par défaut est vim). La commande accepte une requête comme argument. Si aucun argument n’est passé, cela ouvre la dernière requête qui a été exécutée.

!exit , !disconnect¶

Abandonne la connexion actuelle et quitte SnowSQL s’il s’agit de la dernière connexion.

!help , !helps , !h¶

Affiche l’aide pour les commandes SnowSQL.

!options , !opts¶

Renvoie une liste de toutes les options de configuration SnowSQL et leurs valeurs actuellement définies. Ces options peuvent être définies à l’aide de la commande !set dans la session SnowSQL actuelle.

!pause¶

Mettez en pause les requêtes en cours. Appuyez sur la touche Retour pour continuer.

!print¶

Imprime le texte spécifié à l’écran et tous les fichiers vers lesquels vous effectuez un « spooling ».

Par exemple :

user#> !print Include This Text

Copy

!queries¶

Répertorie toutes les requêtes qui correspondent aux filtres spécifiés. Les filtres par défaut sont session et amount=25 qui renvoient les 25 requêtes les plus récentes de la session en cours.

Par exemple :

• Renvoie les 25 requêtes les plus récentes qui ont été exécutées dans la session en cours :

  !queries session
  

  Copy

• Renvoie les 20 requêtes les plus récentes exécutées dans le compte :

  !queries amount=20
  

  Copy

• Renvoie les 20 requêtes les plus récentes exécutées dans le compte qui ont pris plus de 200 millisecondes à s’exécuter :

  !queries amount=20 duration=200
  

  Copy

• Renvoie les 25 requêtes les plus récentes qui se sont exécutées dans l’entrepôt spécifié :

  !queries warehouse=mywh
  

  Copy

Cette commande crée une variable pour chaque ID de requête renvoyé. Notez que la substitution de variable doit être activée pour que vous puissiez utiliser ces variables. Par exemple :

user#> !queries session

+-----+--------------------------------------+----------+-----------+----------+
| VAR | QUERY ID                             | SQL TEXT | STATUS    | DURATION |
|-----+--------------------------------------+----------+-----------+----------|
| &0  | acbd6778-c68c-4e79-a977-510b2d8c08f1 | select 1 | SUCCEEDED |       19 |
+-----+--------------------------------------+----------+-----------+----------+

user#> !result &0

+---+
| 1 |
|---|
| 1 |
+---+

user#> !result acbd6778-c68c-4e79-a977-510b2d8c08f1

+---+
| 1 |
|---|
| 1 |
+---+

Copy

!quit , !q (également CTRL + d)¶

Abandonne toutes les connexions et quitte SnowSQL.

!rehash¶

Resynchronise les jetons d’auto-complétion.

Une utilisation normale ne nécessite pas de resynchroniser les jetons d’auto-complétion. Cependant, forcer une mise à jour des jetons côté serveur pourrait être utile dans certains scénarios (par exemple, si une nouvelle fonction définie par l’utilisateur est créée dans une session différente).

!result¶

Renvoie le résultat d’une requête complétée (spécifié par l’ID de requête). Les IDs de requête peuvent être obtenus à partir de la page History dans l’interface Web ou via la commande !queries.

Si la requête est toujours en cours d’exécution, la commande attend que la requête soit terminée.

Par exemple :

user#> !result 77589bd1-bcbf-4ec8-9ebc-6c949b00614d;

Copy

!set¶

Définit l’option de configuration spécifiée SnowSQL sur une valeur donnée au format <option>=<valeur>.

Notez qu’il n’existe actuellement aucune option servant à annuler la définition d’une valeur d’option. Pour modifier la valeur d’une option, exécutez à nouveau la commande !set avec la valeur souhaitée.

Par exemple :

user#> !options

+-----------------------+-------------------+
| Name                  | Value             |
|-----------------------+-------------------|
 ...
| rowset_size           | 1000              |
 ...
+-----------------------+-------------------+

user#> !set rowset_size=500

user#> !options

+-----------------------+-------------------+
| Name                  | Value             |
|-----------------------+-------------------|
 ...
| rowset_size           | 500               |
 ...
+-----------------------+-------------------+

user#> !set rowset_size=1000

user#> !options

+-----------------------+-------------------+
| Name                  | Value             |
|-----------------------+-------------------|
 ...
| rowset_size           | 1000              |
 ...
+-----------------------+-------------------+

Copy

!source , !load¶

Exécute SQL à partir d’un fichier. Vous pouvez exécuter SQL à partir de fichiers locaux ou d’une URL.

Par exemple :

user#> !source example.sql

user#> !load /tmp/scripts/example.sql

user#> !load http://www.example.com/sql_text.sql

Copy

!spool¶

Cette commande peut être exécutée de deux façons :

• Activez le spooling et écrivez les résultats de toutes les instructions/requêtes suivantes dans le fichier spécifié :

  !spool <nom_fichier>

• Désactivez le spooling des résultats (s’il est activé) :

  !spool off

Par exemple :

user#> select 1 num;

+-----+
| NUM |
|-----|
|   1 |
+-----+

user#> !spool /tmp/spool_example

user#> select 2 num;

+---+
| 2 |
|---|
| 2 |
+---+

user#> !spool off

user#> select 3 num;

+---+
| 3 |
|---|
| 3 |
+---+

user#> !exit

Goodbye!

$ cat /tmp/spool_example

+---+
| 2 |
|---|
| 2 |
+---+

Copy

Vous pouvez modifier le format de sortie en exécutant d’abord la commande !set output_format=<format>. Cette option prend en charge les valeurs suivantes :

• expanded

• fancy_grid

• grid

• html

• latex

• latex_booktabs

• mediawiki

• orgtbl

• pipe

• plain

• psql

• rst

• simple

• tsv

Valeur recommandée : psql, fancy_grid ou grid

Par exemple, pour une sortie au format CSV :

user#> !set output_format=csv

user#> !spool /tmp/spool_example

Copy

!system¶

Exécute une commande shell.

!system <commande>

L’exemple suivant exécute la commande ls dans le répertoire personnel de l’utilisateur :

user#> !system ls ~

Copy

!variables , !vars¶

Répertorie toutes les variables actuelles. Renvoie chaque paire <nom_variable>=<valeur_variable> actuellement définie.

Une fois qu’une variable est assignée, elle ne peut pas être supprimée, mais sa valeur peut être supprimée en attribuant aucune valeur au nom de la variable. Par exemple :

user#> !set variable_substitution=true

user#> !define SnowAlpha=_ALPHA_

user#> !variables

+------------------+---------+
| Name             | Value   |
|------------------+---------|
| snowalpha        | _ALPHA_ |
+------------------+---------+

user#> !define SnowAlpha

user#> !variables

+------------------+-------+
| Name             | Value |
|------------------+-------|
| snowalpha        |       |
+------------------+-------+

user#> !define snowalpha=456

user#> select &snowalpha;

+-----+
| 456 |
|-----|
| 456 |
+-----+

Copy

Pour plus d’informations sur le paramétrage des variables, voir Utilisation de variables (dans ce chapitre).

Message d’erreur : Variable is not defined¶

Cause:

Si vous voyez ce message d’erreur lorsque vous exécutez des commandes dans SnowSQL, la cause peut être une esperluette (&) dans une commande CREATE FUNCTION. (L’esperluette est le caractère de substitution de variable dans SnowSQL). Par exemple, l’exécution de ce qui suit dans SnowSQL provoque cette erreur :

create function mask_bits(...)
    ...
    as
    $$
    var masked = (x & y);
    ...
    $$;

Copy

L’erreur se produit lorsque la fonction est créée, et non lorsqu’elle est appelée.

Solution:

Si vous n’avez pas l’intention d’utiliser la substitution de variable dans SnowSQL, vous pouvez explicitement désactiver la substitution de variable en exécutant la commande suivante :

!set variable_substitution=false;

Copy

Pour plus d’informations sur la substitution de variables, voir Utilisation de variables.