Como executar instruções SQL¶

Como usar ariáveis para modelos SQL¶

Em certas situações, você pode querer mudar suas consultas SQL baseadas no contexto. O comando snow sql oferece suporte à substituição de variável do lado do cliente, o que permite que você use variáveis no comando que são resolvidas localmente antes de enviar a consulta. As variáveis na cadeia de caracteres SQL assumem o formato <% variable_name %> e a opção -D (ou --variable) especifica o valor da variável.

Nota

Atualmente, é possível usar a sintaxe SnowSQL &variable_name e <% variable_name %> para modelos. Entretanto, a Snowflake recomenda usar a sintaxe <% variable_name %>.

Por exemplo, para especificar um banco de dados usando uma variável do lado do cliente, você pode inserir um comando semelhante ao seguinte:

snow sql -q "select * from <% database %>.logs" -D "database=dev"

Quando executado, o comando substitui o valor dev na variável <% database %> para criar o nome de arquivo dev.logs e envia a consulta SQL select * from dev.logs ao Snowflake para processamento.

Você também pode especificar várias entradas variáveis, conforme mostrado:

snow sql \
-q "grant usage on database <% database %> to <% role %>" \
-D "database=dev" \
-D "role=eng_rl"

Este exemplo gera a seguinte consulta SQL:

grant usage on database dev to eng_rl

Armazenamento de variáveis no arquivo de definição de projeto snowflake.yml¶

Especificar variáveis como opções de linha de comando snow sql pode não ser sempre prático, ou talvez você não queira especificar valores confidenciais na linha de comando. Nesses casos, você pode definir variáveis e valores no arquivo de definição de projeto snowflake.yml. Se for esse o caso, é possível simplesmente especificar os nomes da variável no formato <% ctx.env.<variable_name> %> em vez de usar a opção -D "<variável> = <valor>".

Usando o exemplo da seção anterior, você pode armazenar as variáveis de banco de dados e de função no arquivo snowflake.yml e alterar a consulta para:

snow sql -q "grant usage on database <% ctx.env.database %> to <% ctx.env.role %>"

Neste exemplo, o comando snow sql procura as definições de variável no arquivo de definição do projeto e extrai os valores sem torná-los visíveis na linha de comando. O arquivo snowflake.yml deve estar localizado no diretório de trabalho atual ou no local especificado com a opção -p.

Para obter mais informações sobre como armazenar esses valores no arquivo de definição do projeto, consulte Usos das variáveis em SQL.

Executar consultas SQL de forma assíncrona¶

Snowflake CLI permite que você execute uma ou mais consultas SQL de forma assíncrona. Em vez de esperar por um resultado, o comando snow sql agenda as consultas no Snowflake e retorna um ID de consulta. Após a conclusão de uma consulta, você pode obter o resultado usando o comando de consulta !result ou o comando SQL RESULT_SCAN.

Para executar uma consulta SQL de forma assíncrona, encerre a consulta com ;> em vez de ;, conforme mostrado:

snow sql -q 'select "My async query" ;>'

O exemplo a seguir executa uma única consulta de forma assíncrona:

snow sql -q "select 'This is async query';>"

select 'This is async query'
+--------------------------------------+
| scheduled query ID                   |
|--------------------------------------|
| 01bc3011-080f-f2d7-0001-c1be14bae7c2 |
+--------------------------------------+

Em seguida, você pode usar o ID de consulta retornado no comando de consulta !result para exibir o resultado da consulta:

snow sql -q '!result 01bc3011-080f-f2d7-0001-c1be14bae7c2'

path-to-private-key-file
+-----------------------+
| 'THIS IS ASYNC QUERY' |
|-----------------------|
| This is async query   |
+-----------------------+

Você também pode executar várias consultas na cadeia de caracteres de consulta, tanto de forma assíncrona quanto síncrona, conforme mostrado:

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

Trabalhar com os comandos de consulta SQL¶

Snowflake CLI fornece os seguintes comandos que você pode usar em suas consultas SQL:

• !source, que executa SQL em arquivos locais ou URLs.

• !queries, que lista todas as consultas SQL.

• !result, que exibe o resultado de uma consulta SQL.

• !abort, que aborta uma consulta SQL ativa.

snow sql -q '!source my_sql_code.sql'

select emp_id FROM employees;
!source code_file_2.sql

snow sql -q '!result 01bc3011-080f-f2d7-0001-c1be14bae7c2'

+-----------------------+
| 'THIS IS ASYNC QUERY' |
|-----------------------|
| This is async query   |
+-----------------------+

snow sql -q '!abort 01bc3011-080f-f2d7-0001-c1be14bae7c2'

+-------------------------------------------------------------+
| SYSTEM$CANCEL_QUERY('01BC3011-080F-F2D7-0001-C1BE14BAE7C2') |
|-------------------------------------------------------------|
| Identified SQL statement is not currently executing.        |
+-------------------------------------------------------------+

Inserção de vários comandos em uma única transação¶

A opção --single-transaction permite que você insira vários comandos SQL para serem executados como um conjunto de comandos do tipo “tudo ou nada”. Ao executar comandos em uma única transação, você pode garantir que todos os comandos sejam concluídos com sucesso antes de confirmar qualquer alteração. Se algum dos comandos falhar, nenhuma das alterações dos comandos bem-sucedidos persistirá.

Os exemplos a seguir mostram transações bem e malsucedidas:

• Execução bem-sucedida do comando

  snow sql -q "insert into my_tbl values (123); insert into my_tbl values (124);" --single-transaction
  

  Copy

  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. |
  +----------------------------------+
  

  Você pode então verificar se os comandos foram confirmados no banco de dados:

  snow sql -q "select count(*) from my_tbl"
  

  Copy

  select count(*) from my_tbl
  +----------+
  | COUNT(*) |
  |----------|
  | 2        |
  +----------+
  

• Transação única malsucedida

  snow sql -c patcli -q "insert into my_tbl values (123); insert into my_tbl values (124); select BAD;" --single-transaction
  

  Copy

  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'                                                              │
  ╰───────────────────────────────────────────────────────────────────────────────────────╯
  

Você pode então verificar se os comandos não foram confirmados no banco de dados:

snow sql -q "select count(*) from my_tbl"

Copy

select count(*) from my_tbl
+----------+
| COUNT(*) |
|----------|
| 0        |
+----------+

Inserção de comandos SQL no modo interativo¶

O comando snow sql é compatível com um modo interativo que permite que você insira os comandos SQL um de cada vez. O modo interativo oferece os seguintes recursos:

• Realce de sintaxe

  

• Conclusão de código durante a digitação

  

• Histórico pesquisável

  Pressionar CTRL-R: permite que você pesquise o histórico de comandos:

  

• Entrada de várias linhas

  Pressionar ENTER em uma linha que não termina com ponto e vírgula (;) move o cursor para a próxima linha para mais comandos até que uma instrução termine com ponto e vírgula.

  

Para usar o modo interativo, insira o comando snow sql seguido de ENTER, conforme mostrado:

snow sql

O comando abre um sub-shell com um prompt > onde você pode inserir comandos SQL de forma interativa:

$ snow sql
  ╭───────────────────────────────────────────────────────────────────────────────────╮
  │ Welcome to Snowflake-CLI REPL                                                     │
  │ Type 'exit' or 'quit' to leave                                                    │
  ╰───────────────────────────────────────────────────────────────────────────────────╯
  >

Você pode então inserir os comandos SQL, conforme mostrado:

> create table my_table (c1 int);

+-------------------------------------+
| status                              |
|-------------------------------------|
| Table MY_TABLE successfully created.|
+-------------------------------------+

Para sair do modo interativo, insira exit, quit ou CTRL-D.