Uso de SnowSQL¶

Definição de variáveis¶

Você pode definir variáveis para o SnowSQL de várias maneiras:

• Definição de variáveis antes da conexão (arquivo de configuração)

• Definição de variáveis durante a conexão (sinalizador de linha de comando -D ou --variable)

• Definição de variáveis dentro de uma sessão (comando !define)

Habilitação da substituição de variáveis¶

Para permitir que o SnowSQL substitua os valores das variáveis, defina a opção de configuração variable_substitution como true de uma das seguintes maneiras:

• Para definir esta opção antes de iniciar o SnowSQL, abra o arquivo de configuração do SnowSQL em um editor de texto e defina esta opção na seção [options]:

  [options]
  variable_substitution = True
  

  Copy

• Para definir esta opção ao iniciar o SnowSQL, especifique o sinalizador de linha de comando -o:

  $ snowsql ... -o variable_substitution=true
  

  Copy

• Para definir esta opção em uma sessão do SnowSQL, execute o comando !set na sessão:

  user#> !set variable_substitution=true
  

  Copy

  Nota

  Atualmente não há opção para remover um valor de opção, tal como a opção variable_substitution. Se você precisar desativar a substituição de variáveis, execute o comando !set variable_substitution=false.

Substituição de variáveis em uma sessão¶

Depois que você habilitar a substituição de variáveis, pode usar variáveis nas instruções SQL.

Para usar uma variável em uma instrução, use a sintaxe &variable_name. Observe que os nomes das variáveis não fazem distinção entre maiúsculas e minúsculas. Por exemplo:

user#> !define snowshell=bash

user#> !set variable_substitution=true

user#> select '&snowshell';

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

Copy

Se a opção variable_substitution não estiver ativada, não ocorre nenhuma substituição de variável. Por exemplo:

user#> !define snowshell=bash

user#> !set variable_substitution=false

user#> select '&snowshell';

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

Copy

Se você se referir a uma variável que não foi definida, o SnowSQL exibe um erro. Por exemplo:

select '&z';

Variable z is not defined

Copy

Para combinar uma variável com texto, inclua a referência da variável entre chaves. Por exemplo:

user#> !define snowshell=bash

user#> !set variable_substitution=true

select '&{snowshell}_shell';

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

Copy

Para usar um sinal de E comercial sem usar substituição, escape o sinal de E comercial com um segundo sinal idêntico:

&&variable

Por exemplo:

user#> !set variable_substitution=true

user#> select '&notsubstitution';

Variable notsubstitution is not defined

user#> select '&&notsubstitution';

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

Copy

Listagem de variáveis¶

Para listar variáveis, execute o comando !variables ou !vars na sessão:

user#> !variables

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

Copy

Uso das variáveis internas¶

O SnowSQL inclui um conjunto de variáveis internas que retornam metadados sobre instruções executadas na sessão atual do usuário.

Cada um desses nomes de variáveis começa com dois caracteres de sublinhado (“__”).

__rowcount

Retorna o número de linhas afetadas pela mais recente instrução DML executada pelo usuário.

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

Retorna a ID para a consulta mais recente executada pelo usuário.

user#> !set variable_substitution=true

user#> select * from a;

user#> select '&__sfqid';

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

Copy

Arquivo de histórico¶

O arquivo de histórico interativo da linha de comando é chamado history e está localizado em ~/.snowsql/history.

Execução durante a conexão (parâmetro de conexão -f)¶

Para executar um script SQL enquanto se conecta ao Snowflake, use o parâmetro de conexão -f <nome_do_arquivo_de_entrada>.

Um arquivo de saída para o script pode ser especificado usando -o output_file=<nome_do_arquivo_de_saída>. Além disso, você pode usar -o quiet=true para desativar a saída padrão e -o friendly=false as mensagens de inicialização e saída.

Por exemplo:

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

Para obter mais informações sobre todos os parâmetros de conexão, consulte Referência de parâmetros de conexão.

Execução em uma sessão (comando !source ou !load)¶

Para executar um script SQL após a conexão ao Snowflake, execute o comando !source (ou !load) na sessão.

Por exemplo:

user#> !source example.sql

Copy

Tokens com suporte¶

O SnowSQL suporta os seguintes tipos de objetos como tokens:

• user

• account

• role

• database

• schema

• warehouse

Prompt padrão¶

O prompt padrão do SnowSQL usa os seguintes tokens e estrutura:

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

Copy

Por exemplo:

jdoe#DATALOAD@BOOKS_DB.PUBLIC>

Copy

Exemplo de prompt¶

Continuando o exemplo acima, o seguinte comando !set executado na linha de comando adiciona o token de função e muda a ordem dos tokens para user e role, database e schema, depois warehouse. Também muda o delimitador para cada token para um ponto (.) e define os tokens para usar cores diferentes:

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

Copy

Este exemplo resulta no seguinte prompt para a sessão:

Códigos de saída¶

Há vários códigos de saída possíveis que são retornados quando o SnowSQL fecha:

0

Tudo correu bem.

1

Algo deu errado com o cliente.

2

Algo deu errado com os argumentos da linha de comando.

3

O SnowSQL não pôde entrar em contato com o servidor.

4

O SnowSQL não conseguiu se comunicar adequadamente com o servidor.

5

A opção de configuração exit_on_error foi definida e o SnowSQL fechou por causa de um erro.

!abort¶

Anula uma consulta (especificada pela ID de consulta). A ID da consulta pode ser obtida da página History na interface da Web.

Por exemplo:

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

Copy

!connect¶

O SnowSQL suporta várias sessões (ou seja, conexões) com !connect <nome_da_conexão>:

• Os parâmetros/opções de conexão associados a connection_name são armazenados na seção correspondente [connections.<nome_da_conexão>] no arquivo de configuração SnowSQL.

• Se um parâmetro/opção não for especificado na seção [connections.<nome_da_conexão>], o parâmetro não especificado será o padrão para os parâmetros sob [connections].

Ao conectar, a conexão é adicionada à sua pilha de conexões, e a saída o retornará à sua conexão anterior. Fechar encerrará todas as suas conexões, não importa quantas conexões você tenha.

Por exemplo:

Arquivo de configuração:

[connections.my_example_connection]
...

Copy

Linha de comando:

user#> !connect my_example_connection

Copy

!define¶

Define uma variável para um valor especificado, usando o seguinte formato:

!define <nome_da_variável>=<valor_da_variável>

O nome e o valor devem ser separados por um único =, sem espaços. Os caracteres válidos que podem ser usados na variável são:

0-9a-zA-Z\_

Para obter mais informações sobre a definição e utilização de variáveis, consulte Uso de variáveis.

!edit¶

Abre o editor que foi definido usando o parâmetro de conexão editor (se nenhum editor foi definido, o padrão é vim). O comando aceita uma consulta como um argumento. Se nenhum argumento for passado, abre-se a última consulta que foi feita.

!exit, !disconnect¶

Descarta a conexão atual e fecha o SnowSQL se for a última conexão.

!help, !helps, !h¶

Exibe a ajuda para os comandos SnowSQL.

!options, !opts¶

Retorna uma lista de todas as opções de configuração do SnowSQL e seus valores atualmente definidos. Estas opções podem ser definidas usando o comando !set na sessão SnowSQL atual.

!pause¶

Pausa consultas em andamento. Pressione a tecla Return para continuar.

!print¶

Imprime o texto especificado para a tela e quaisquer arquivos que você estiver reproduzindo no momento.

Por exemplo:

user#> !print Include This Text

Copy

!queries¶

Lista todas as consultas que correspondem aos filtros especificados. Os filtros padrão são session e amount=25, que retornam as 25 consultas mais recentes na sessão atual.

Por exemplo:

• Retornar as 25 consultas mais recentes que foram feitas nesta sessão atual:

  !queries session
  

  Copy

• Retornar as 20 consultas mais recentes na conta:

  !queries amount=20
  

  Copy

• Retornar as 20 consultas mais recentes na conta que levaram mais de 200 milissegundos para serem executadas:

  !queries amount=20 duration=200
  

  Copy

• Retornar as 25 consultas mais recentes que foram feitas no warehouse especificado:

  !queries warehouse=mywh
  

  Copy

Este comando cria uma variável para cada ID de consulta retornada. Note que a substituição de variáveis deve estar habilitada para que você possa usar essas variáveis. Por exemplo:

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 (também CTRL + d)¶

Descarta todas as conexões e sai do SnowSQL.

!rehash¶

Sincroniza novamente os tokens de preenchimento automático.

O uso normal não requer repetir a sincronização dos tokens de preenchimento automático. Entretanto, forçar uma atualização dos tokens do lado do servidor pode ser útil em certos cenários (por exemplo, se uma nova função definida pelo usuário for criada em uma sessão diferente).

!result¶

Retorna o resultado de uma consulta concluída (especificado pela ID da consulta). As IDs de consulta podem ser obtidas na página History da interface da Web ou usando o comando !queries.

Se a consulta ainda estiver em execução, o comando espera até que a consulta seja concluída.

Por exemplo:

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

Copy

!set¶

Define a opção de configuração do SnowSQL especificada para um determinado valor usando o formato <opção>=<valor>.

Note que atualmente não há opção para remover um valor de opção. Para alterar o valor de uma opção, execute novamente o comando !set com o valor desejado.

Por exemplo:

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¶

Executa SQL a partir de um arquivo. Você pode usar SQL a partir de arquivos locais ou uma URL.

Por exemplo:

user#> !source example.sql

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

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

Copy

!spool¶

Este comando pode ser executado de duas maneiras:

• Habilite o spooling e grave os resultados de todas as instruções/consultas subsequentes no arquivo especificado:

  !spool <nome_do_arquivo>

• Desative o spooling dos resultados (se estiver habilitado):

  !spool off

Por exemplo:

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

Você pode mudar o formato de saída executando primeiro o comando !set output_format=<formato>. A opção suporta os seguintes valores:

• expanded

• fancy_grid

• grid

• html

• latex

• latex_booktabs

• mediawiki

• orgtbl

• pipe

• plain

• psql

• rst

• simple

• tsv

Valor recomendado: psql, fancy_grid ou grid

Por exemplo, para produzir uma saída em formato CSV:

user#> !set output_format=csv

user#> !spool /tmp/spool_example

Copy

!system¶

Executa um comando do shell.

!system <comando>

O seguinte exemplo executa o comando ls no diretório base do usuário:

user#> !system ls ~

Copy

!variables , !vars¶

Lista todas as variáveis atuais. Retorna cada par <nome_da_variável>=<valor_da_variável> atualmente definido.

Uma vez que uma variável é atribuída, ela não pode ser excluída, mas seu valor pode ser removido especificando-se o nome da variável sem nenhum valor. Por exemplo:

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

Para obter mais informações sobre a definição de variáveis, consulte Uso de variáveis (neste tópico).

Mensagem de erro: Variable is not defined¶

Causa

Se você vir esta mensagem de erro ao executar comandos no SnowSQL, a causa pode ser um E comercial (&) dentro de um comando CREATE FUNCTION. (O E comercial é o caráter de substituição de variáveis do SnowSQL). Por exemplo, executar o seguinte código no SnowSQL causa esse erro:

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

Copy

O erro ocorre quando a função é criada, e não quando a função é chamada.

Solução

Se você não pretende usar a substituição de variáveis no SnowSQL, você pode desativar explicitamente a substituição de variáveis executando o seguinte comando:

!set variable_substitution=false;

Copy

Para obter mais informações sobre a substituição de variáveis, consulte Uso de variáveis.