snow sql¶

Sintaxe¶

snow sql
  --query <query>
  --filename <files>
  --stdin
  --variable <data_override>
  --retain-comments
  --single-transaction / --no-single-transaction
  --enable-templating <enabled_templating>
  --project <project_definition>
  --env <env_overrides>
  --connection <connection>
  --host <host>
  --port <port>
  --account <account>
  --user <user>
  --password <password>
  --authenticator <authenticator>
  --workload-identity-provider <workload_identity_provider>
  --private-key-file <private_key_file>
  --token <token>
  --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.

--enable-templating [LEGACY|STANDARD|JINJA|ALL|NONE]

Sintaxe usada para resolver variáveis antes de passar consultas para o Snowflake. Padrão: [<_EnabledTemplating.LEGACY: “LEGACY”>, <_EnabledTemplating.STANDARD: “STANDARD”>].

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

--workload-identity-provider TEXT

Provedor de identidade de carga de trabalho (AWS, AZURE, GCP, OIDC). 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 TEXT

Token OAuth a ser usado ao se conectar ao Snowflake.

--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|JSON_EXT|CSV]

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

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

echo $?

2

snow sql

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

> create table my_table (c1 int);

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

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