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
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 comandosnow sql
, comocat 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"
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; $$ ;
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 comandosnow 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-sucedida2
: problemas com os parâmetros de comando5
: problemas de execução de consultas1
: 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 $?
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ída5
para indicar um erro de consulta:snow sql --enhanced-exit-codes -q 'slect 1' echo $?
5
Sem a opção
--enhanced-exit-codes
, o comando retorna um código de saída1
para indicar um erro genérico (outro):snow sql --enhanced-exit-codes -q 'slect 1' echo $?
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
Conclusão de código durante a digitação
Histórico pesquisável
Para pesquisar seu histórico de comandos, pressione CTRL-R:
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.|
+-------------------------------------+
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
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"
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
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"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();'
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"
Quando executado, o comando substitui o valor
dev
na variável<% database %>
para criar o identificadordev.logs
e então envia a consulta SQLselect * 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
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';
Quando você executa o seguinte comando,
-- My comment
aparece nos resultados de consulta.snow sql -f example.sql --retain-comments
select 'column1'; +-----------+ | 'COLUMN1' | |-----------| | ABC | +-----------+ -- My comment select 'bar'; +-----------+ | 'COLUMN2' | |-----------| | 123 | +-----------+