snow sql

Executa a consulta Snowflake. Use a opção de consulta, nome de arquivo ou entrada. A consulta a ser executada pode ser especificada usando a opção de consulta, opção de nome de arquivo (todas as consultas do arquivo serão executadas) ou via stdin, canalizando a saída de outro comando. Por exemplo cat my.sql | snow sql -i. O comando oferece suporte à substituição de variáveis que acontece no lado do cliente.

Sintaxe

snow sql
  --query <query>
  --filename <files>
  --stdin
  --variable <data_override>
  --retain-comments
  --single-transaction / --no-single-transaction
  --project <project_definition>
  --env <env_overrides>
  --connection <connection>
  --host <host>
  --port <port>
  --account <account>
  --user <user>
  --password <password>
  --authenticator <authenticator>
  --private-key-file <private_key_file>
  --token-file-path <token_file_path>
  --database <database>
  --schema <schema>
  --role <role>
  --warehouse <warehouse>
  --temporary-connection
  --mfa-passcode <mfa_passcode>
  --enable-diag
  --diag-log-path <diag_log_path>
  --diag-allowlist-path <diag_allowlist_path>
  --oauth-client-id <oauth_client_id>
  --oauth-client-secret <oauth_client_secret>
  --oauth-authorization-url <oauth_authorization_url>
  --oauth-token-request-url <oauth_token_request_url>
  --oauth-redirect-uri <oauth_redirect_uri>
  --oauth-scope <oauth_scope>
  --oauth-disable-pkce
  --oauth-enable-refresh-tokens
  --oauth-enable-single-use-refresh-tokens
  --client-store-temporary-credential
  --format <format>
  --verbose
  --debug
  --silent
  --enhanced-exit-codes
Copy

Argumentos

Nenhum

Opções

--query, -q TEXT

Consulta a ser executada.

--filename, -f FILE

Arquivo a ser executado. Padrão: [].

--stdin, -i

Leia a consulta da entrada padrão. Use-a ao canalizar a entrada para este comando. Padrão: falso.

--variable, -D TEXT

Cadeia de caracteres no formato chave=valor. Se fornecido, o conteúdo SQL será tratado como modelo e renderizado usando os dados fornecidos.

--retain-comments

Retém comentários em consultas passadas para o Snowflake. Padrão: falso.

--single-transaction / --no-single-transaction

Conexão com confirmação automática desativada. Insere BEGIN/COMMIT ao redor das instruções s para executá-las como uma única transação, garantindo que todos os comandos sejam concluídos com sucesso ou que nenhuma mudança seja aplicada. Padrão: falso.

-p, --project TEXT

Caminho onde o projeto Snowflake está armazenado. O padrão é o diretório de trabalho atual.

--env TEXT

Cadeia de caracteres no formato key=value. Substitui as variáveis da seção env usada para modelos. Padrão: [].

--connection, -c, --environment TEXT

Nome da conexão, conforme definido no arquivo config.toml. Padrão: default.

--host TEXT

Endereço do host da conexão. Substitui o valor especificado para a conexão.

--port INTEGER

Porta para a conexão. Substitui o valor especificado para a conexão.

--account, --accountname TEXT

Nome atribuído à sua conta Snowflake. Substitui o valor especificado para a conexão.

--user, --username TEXT

Nome de usuário para se conectar ao Snowflake. Substitui o valor especificado para a conexão.

--password TEXT

Senha do Snowflake. Substitui o valor especificado para a conexão.

--authenticator TEXT

Autenticador Snowflake. Substitui o valor especificado para a conexão.

--private-key-file, --private-key-path TEXT

Caminho do arquivo de chave privada Snowflake. Substitui o valor especificado para a conexão.

--token-file-path TEXT

Caminho para o arquivo com um token OAuth a ser usado ao se conectar ao Snowflake.

--database, --dbname TEXT

Banco de dados a ser usado. Substitui o valor especificado para a conexão.

--schema, --schemaname TEXT

Esquema de banco de dados a ser usado. Substitui o valor especificado para a conexão.

--role, --rolename TEXT

Função a ser usada. Substitui o valor especificado para a conexão.

--warehouse TEXT

Warehouse a ser usado. Substitui o valor especificado para a conexão.

--temporary-connection, -x

Usa uma conexão definida com parâmetros de linha de comando, em vez de uma definida na configuração. Padrão: falso.

--mfa-passcode TEXT

Token a ser usado para autenticação multifator (MFA).

--enable-diag

Se deve gerar um relatório de diagnóstico de conexão. Padrão: falso.

--diag-log-path TEXT

Caminho para o relatório gerado. O padrão é o diretório temporário do sistema. Padrão: <system_temporary_directory>.

--diag-allowlist-path TEXT

Caminho para um arquivo JSON que contém parâmetros da lista de permissões.

--oauth-client-id TEXT

Valor do ID de cliente fornecido pelo provedor de identidade para integração com o Snowflake.

--oauth-client-secret TEXT

Valor do segredo do cliente fornecido pelo provedor de identidade para integração com o Snowflake.

--oauth-authorization-url TEXT

Ponto de extremidade do provedor de identidade que fornece o código de autorização ao driver.

--oauth-token-request-url TEXT

Ponto de extremidade do provedor de identidade que fornece os tokens de acesso ao driver.

--oauth-redirect-uri TEXT

URI a ser usado para redirecionamento de código de autorização.

--oauth-scope TEXT

Escopo solicitado na solicitação de autorização do provedor de identidade.

--oauth-disable-pkce

Desativa o Proof Key for Code Exchange (PKCE). Padrão: False.

--oauth-enable-refresh-tokens

Permite uma reautenticação silenciosa quando o token de acesso real fica desatualizado. Padrão: False.

--oauth-enable-single-use-refresh-tokens

Se o usuário deve optar pela semântica de token de atualização de uso único. Padrão: False.

--client-store-temporary-credential

Armazena a credencial temporária.

--format [TABLE|JSON]

Especifica o formato de saída. Padrão: TABLE.

--verbose, -v

Exibe entradas de log para os níveis de log info e superiores. Padrão: falso.

--debug

Exibe entradas de log para níveis de log de depuração e superiores; os logs de depuração contêm informações adicionais. Padrão: falso.

--silent

Desliga a saída intermediária para o console. Padrão: falso.

--enhanced-exit-codes

Diferencia os códigos de erro de saída com base no tipo de falha. Padrão: falso.

--help

Exibe o texto de ajuda para este comando.

Notas de uso

Você pode especificar a consulta SQL para execução usando uma das seguintes opções

  • Especifique a cadeia de caracteres de consulta usando a opção --query.

  • Use a opção --filename para executar um ou mais arquivos que contenham uma ou mais consultas SQL. Por exemplo:

    • snow sql -f myfile.sql

    • snow sql -f file1.sql -f file2.sql

  • Especifique a consulta como stdin e canal para o comando snow sql, como cat my.sql | snow sql.

  • Se sua consulta contiver caracteres especiais, como o cifrão em funções SYSTEM, que você não quer que o shell interprete, você pode fazer qualquer um dos seguintes:

    • Coloque a consulta entre aspas simples em vez de aspas duplas, como em:

      snow sql -q 'SELECT SYSTEM$CLIENT_VERSION_INFO()'

    • Escape do caractere especial, como em:

      snow sql -q "SELECT SYSTEM\$CLIENT_VERSION_INFO()"

  • Use variáveis para modelar consultas SQL com a combinação de um espaço reservado <% variable_name %> em suas consultas SQL e uma opção de linha de comando -D, no formato:

    snow sql -q "select * from my-database order by <% column_name %>" -D "column_name=Country"
    
    Copy

    Nota

    Atualmente, você pode usar a sintaxe SnowSQL &variable_name e <% variable_name %> para modelos. No entanto, o Snowflake recomenda o uso da sintaxe <% variable_name %>.

  • Especifique um bloco de script em consultas. Por exemplo:

    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;
    $$
    ;
    
    Copy

    Nota

    Ao especificar o bloco de script diretamente na linha de comando Snowflake CLI, os delimitadores $$ podem não funcionar em alguns shells porque eles interpretam esse delimitador como outra coisa. Por exemplo, os shells bash e zsh o interpretam como o ID do processo (PID). Para resolver essa limitação, você pode usar as seguintes alternativas:

    • Se ainda quiser especificar o bloco de script na linha de comando, você pode fazer o escape dos delimitadores $$, como em \$\$.

    • Você também pode colocar o bloco de script com os delimitadores padrão $$ em um arquivo separado e chamá-lo com o comando snow sql -f <filename>.

Códigos de erro aprimorados

A opção --enhanced-exit-codes fornece informações que ajudam a identificar se os problemas resultam da execução da consulta ou de opções de comando inválidas. Com essa opção, o comando snow sql fornece os seguintes códigos de retorno:

  • 0: execução bem-sucedida

  • 2: problemas com os parâmetros de comando

  • 5: problemas de execução de consultas

  • 1: outros tipos de problemas

Após a execução do comando, você pode usar o comando shell echo $? para ver o código de retorno.

Neste exemplo, o comando contém um parâmetro de consulta (-q 'select 1') e um parâmetro de arquivo de consulta (-f my.query), que é uma combinação de parâmetros inválida:

snow sql --enhanced-exit-codes -q 'select 1' -f my.query

echo $?
Copy
2

Os exemplos a seguir mostram o efeito da opção --enhanced-exit-codes quando o comando contém uma consulta inválida (slect está escrito incorretamente):

  • Com a opção --enhanced-exit-codes, o comando retorna um código de saída 5 para indicar um erro de consulta:

    snow sql --enhanced-exit-codes -q 'slect 1'
    
    echo $?
    
    Copy
    5
    
  • Sem a opção --enhanced-exit-codes, o comando retorna um código de saída 1 para indicar um erro genérico (outro):

    snow sql --enhanced-exit-codes -q 'slect 1'
    
    echo $?
    
    Copy
    1
    

Como alternativa, você pode definir a variável de ambiente SNOWFLAKE_ENHANCED_EXIT_CODES como 1 para enviar os códigos de retorno aprimorados para todos os comandos snow sql.

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

    Realce de sintaxe no modo interativo
  • Conclusão de código durante a digitação

    Conclusão do código no modo interativo
  • Histórico pesquisável

    Para pesquisar seu histórico de comandos, pressione CTRL-R:

    Histórico pesquisável no modo interativo
  • 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.

    Entrada de várias linhas no modo interativo

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

snow sql
Copy

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);
Copy
+-------------------------------------+
| status                              |
|-------------------------------------|
| Table MY_TABLE successfully created.|
+-------------------------------------+

Nota

Você deve terminar cada instrução SQL com um ponto e vírgula (;).

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

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

Exemplos

  • O exemplo a seguir usa a função SQL SYSTEM$CLIENT_VERSION_INFO do sistema para retornar informações de versão sobre clientes e drivers.

    snow sql --query 'SELECT SYSTEM$CLIENT_VERSION_INFO();'
    
    Copy
    select current_version();
    +-------------------+
    | CURRENT_VERSION() |
    |-------------------|
    | 8.25.1            |
    +-------------------+
    
  • O exemplo a seguir mostra como você pode especificar um banco de dados usando uma variável do lado do cliente:

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

    Quando executado, o comando substitui o valor dev na variável <% database %> para criar o identificador dev.logs e então envia a consulta SQL select * from dev.logs para processamento no Snowflake.

    Nota

    Atualmente, você pode usar a sintaxe SnowSQL &variable_name e & { variable_name } para modelos. Entretanto, a Snowflake recomenda usar a sintaxe <% variable_name %>.

  • Este exemplo mostra como passar variáveis de ambiente usando a opção --env:

    snow sql -q "select '<% ctx.env.test %>'" --env test=value_from_cli
    
    Copy
  • Por padrão, o Snowflake CLI remove da saída os comentários da consulta SQL. O exemplo a seguir usa a opção --retain-comments para incluir os comentários nos resultados de consulta.

    Suponha que o arquivo example.sql contenha as seguintes instruções e comentários:

    select 'column1';
    -- My comment
    select 'column2';
    
    Copy

    Quando você executa o seguinte comando, -- My comment aparece nos resultados de consulta.

    snow sql -f example.sql --retain-comments
    
    Copy
    select 'column1';
    +-----------+
    | 'COLUMN1' |
    |-----------|
    | ABC       |
    +-----------+
    
    -- My comment
    select 'bar';
    +-----------+
    | 'COLUMN2' |
    |-----------|
    | 123       |
    +-----------+
    
    Copy