CLI do Databricks SQL

A CLI (interface de linha de comando) do SQL do Databricks permite executar consultas SQL em SQL warehouses existentes do Databricks por meio do terminal ou do prompt de comando do Windows em vez de por meio de locais como o editor do SQL do Databricks ou um notebook do Azure Databricks. Na linha de comando, você obtém recursos de produtividade, como sugestões e realce de sintaxe.

Requisitos

• Pelo menos um SQL warehouse do Databricks. Crie um warehouse, se ainda não tiver um.
• Python 3.7 ou superiores. Para verificar se o Python está instalado, execute o comando python --version no terminal ou no prompt de comando. (Em alguns sistemas, talvez seja necessário inserir python3.) Instale o Python, se ele ainda não estiver instalado.
• pip, o instalador de pacote para Python. As versões mais recentes do Python instalam o pip por padrão. Para verificar se o pip está instalado, execute o comando pip --version no terminal ou no prompt de comando. (Em alguns sistemas, talvez seja necessário inserir pip3.) Instale o pip, se ele ainda não estiver instalado.
• (Opcional) Um utilitário para criar e gerenciar ambientes virtuais Python, como o venv. Os ambientes virtuais ajudam a garantir o uso das versões corretas do Python e da CLI do Databricks SQL em conjunto. A configuração e o uso de ambientes virtuais estão fora do escopo deste artigo. Para obter mais informações, confira Como criar ambientes virtuais.

Instalar a CLI de SQL do Databricks

Depois de atender aos requisitos, instale o pacote da CLI de SQL do Databricks do PyPI (Índice de Empacotamento de Python). Você pode usar pip para instalar o pacote CLI do SQL do Databricks do PyPI executando pip com um dos seguintes comandos.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Para atualizar uma versão previamente instalada da CLI do SQL do Databricks, execute pip com um dos seguintes comandos.

pip install databricks-sql-cli --upgrade

# Or...

python -m pip install databricks-sql-cli --upgrade

Para verificar sua versão instalada da CLI do SQL do Databricks, execute pip com um dos seguintes comandos.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Autenticação

Para autenticar, você deve fornecer à CLI do SQL do Databricks os detalhes da conexão do seu warehouse. Você precisará especificamente dos valores de Nome do host do servidor e Caminho HTTP. Você também deve produzir a CLI do SQL do Databricks com as credenciais de autenticação adequadas.

A CLI do SQL do Databricks dá suporte para autenticação de token de acesso pessoal do Databricks. Não há suporte para tokens do Microsoft Entra ID.

Para usar a autenticação de token de acesso pessoal do Azure Databricks, crie um token de acesso pessoal da seguinte forma:

1. No workspace do Azure Databricks, clique no nome de usuário do Azure Databricks na barra superior e selecione Configurações na lista suspensa.
2. Clique em Desenvolvedor.
3. Ao lado de Tokens de acesso, clique em Gerenciar.
4. Clique em Gerar novo token.
5. (Opcional) Insira um comentário que ajude você a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem tempo de vida (não recomendado), deixe a caixa Tempo de vida (dias) vazia (em branco).
6. Clique em Gerar.
7. Copie o token exibido para um local seguro e clique em Concluído.

Você pode fornecer essas informações de autenticação para o CLI do SQL do Databricks de várias maneiras:

• No arquivo de configurações dbsqlclirc no local padrão (ou especificando um arquivo de configurações alternativo por meio da opção --clirc sempre que você executar um comando com a CLI do Databricks SQL). Confira o Arquivo de configurações.
• Configurando as variáveis de ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN. Confira Variáveis de ambiente.
• Especificando as opções e --hostname, --http-path e --access-tokensempre que você executar um comando com a CLI do Databricks SQL. Confira Opções de comando.

Sempre que você executar a CLI do SQL do Databricks, ela procurará detalhes de autenticação na seguinte ordem e parará quando encontrar o primeiro conjunto de detalhes:

1. As opções --hostname, --http-path e --access-token.
2. As variáveis de ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN.
3. O arquivo de configurações dbsqlclirc no local padrão (ou um arquivo de configurações alternativo especificado pela opção --clirc).

Arquivo de configurações

Para usar o arquivo de configurações dbsqlclirc a fim de fornecer à CLI do SQL do Databricks os detalhes de autenticação do SQL warehouse do Databricks, execute-a pela primeira vez da seguinte maneira:

dbsqlcli

A CLI do Databricks SQL cria um arquivo de configurações para você, em ~/.dbsqlcli/dbsqlclirc no Unix, no Linux e no macOS e em %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc ou %USERPROFILE%\.dbsqlcli\dbsqlclirc no Windows. Para personalizar este arquivo:

1. Use um editor de texto para abrir e editar o arquivo dbsqlclirc.

2. Role para a seguinte seção:

   # [credentials]
   # host_name = ""
   # http_path = ""
   # access_token = ""
   

3. Remova os quatro caracteres # e:

   1. Ao lado de host_name, insira o valor de Nome do host do servidor do warehouse necessário entre os caracteres "".
   2. Ao lado de http_path, insira o valor de Caminho HTTP do warehouse necessário entre os caracteres "".
   3. Ao lado de access_token, insira o valor do token de acesso pessoal dos requisitos entre os caracteres "".

   Por exemplo:

   [credentials]
   host_name = "adb-12345678901234567.8.azuredatabricks.net"
   http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
   access_token = "dapi12345678901234567890123456789012"
   

4. Salve o arquivo dbsqlclirc.

Como alternativa, em vez de usar o arquivo dbsqlclirc no local padrão, você pode especificar um arquivo em um local diferente adicionando a opção de comando --clirc e o caminho para o arquivo alternativo. O conteúdo desse arquivo alternativo precisa estar em conformidade com a sintaxe anterior.

Variáveis de ambiente

Para usar as variáveis de ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN a fim de fornecer à CLI do SQL do Databricks os detalhes de autenticação do SQL warehouse do Databricks, faça o seguinte:

Unix, Linux, e macOS

Para definir as variáveis de ambiente apenas para a sessão do terminal atual, execute os comandos a seguir. Para definir as variáveis de ambiente para todas as sessões do terminal, insira os comandos a seguir no arquivo de inicialização do shell e reinicie o terminal. Nos seguintes exemplos, substitua o valor de:

• DBSQLCLI_HOST_NAME com o valor de Nome do host do servidor do warehouse necessário.
• DBSQLCLI_HTTP_PATH com o valor de Caminho HTTP do warehouse necessário.
• DBSQLCLI_ACCESS_TOKEN pelo valor do token de acesso pessoal dos requisitos.

export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

Para definir as variáveis de ambiente apenas para a sessão do prompt de comando atual, execute os seguintes comandos, substituindo o valor de:

• DBSQLCLI_HOST_NAME com o valor de Nome do host do servidor do warehouse necessário.
• DBSQLCLI_HTTP_PATH com o valor de Caminho HTTP do warehouse necessário.
• DBSQLCLI_ACCESS_TOKEN pelo valor do token de acesso pessoal dos requisitos:

set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Para definir as variáveis de ambiente para todas as sessões do prompt de comando, execute os seguintes comandos e reinicie o prompt de comando, substituindo o valor de:

• DBSQLCLI_HOST_NAME com o valor de Nome do host do servidor do warehouse necessário.
• DBSQLCLI_HTTP_PATH com o valor de Caminho HTTP do warehouse necessário.
• DBSQLCLI_ACCESS_TOKEN pelo valor do token de acesso pessoal dos requisitos.

setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

Opções de comando

Para usar as opções --hostname, --http-path e --access-token a fim de fornecer à CLI do SQL do Databricks os detalhes de autenticação do SQL warehouse do Databricks, faça o seguinte:

Faça o seguinte toda vez que executar um comando com a CLI do SQL do Databricks:

• Especifique a opção --hostname e o valor de Nome de host do servidor do warehouse necessário.
• Especifique a opção --http-path e o valor de Caminho HTTP do warehouse necessário.
• Especifique a opção --access-token e o valor do token de acesso pessoal dos requisitos.

Por exemplo:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "adb-12345678901234567.8.azuredatabricks.net" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"

Fontes de consulta

A CLI do Databricks SQL permite que você execute consultas das seguintes maneiras:

• Usando uma cadeia de caracteres de consulta.
• Usando um arquivo.
• Em uma abordagem REPL (loop de leitura-avaliação-impressão). Essa abordagem oferece sugestões conforme você digita.

Cadeia de consulta

Para executar uma consulta como uma cadeia de caracteres, use a opção -e seguida pela consulta, representada como uma cadeia de caracteres. Por exemplo:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2"

Saída:

_c0,carat,cut,color,clarity,depth,table,price,x,y,z
1,0.23,Ideal,E,SI2,61.5,55,326,3.95,3.98,2.43
2,0.21,Premium,E,SI1,59.8,61,326,3.89,3.84,2.31

Para mudar de formato de saída, use a opção --table-format junto com um valor, como ascii, para o formato de tabela ASCII, por exemplo:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" --table-format ascii

Saída:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _c0 | carat | cut     | color | clarity | depth | table | price | x    | y    | z    |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| 1   | 0.23  | Ideal   | E     | SI2     | 61.5  | 55    | 326   | 3.95 | 3.98 | 2.43 |
| 2   | 0.21  | Premium | E     | SI1     | 59.8  | 61    | 326   | 3.89 | 3.84 | 2.31 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

Para obter uma lista de valores de formato de saída disponíveis, confira os comentários da configuração table_format no arquivo dbsqlclirc.

Arquivo

Para executar um arquivo que contém SQL, use a opção -e seguida pelo caminho para um arquivo .sql. Por exemplo:

dbsqlcli -e my-query.sql

Conteúdo do arquivo de exemplo my-query.sql:

SELECT * FROM default.diamonds LIMIT 2;

Saída:

_c0,carat,cut,color,clarity,depth,table,price,x,y,z
1,0.23,Ideal,E,SI2,61.5,55,326,3.95,3.98,2.43
2,0.21,Premium,E,SI1,59.8,61,326,3.89,3.84,2.31

Para mudar de formato de saída, use a opção --table-format junto com um valor, como ascii, para o formato de tabela ASCII, por exemplo:

dbsqlcli -e my-query.sql --table-format ascii

Saída:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _c0 | carat | cut     | color | clarity | depth | table | price | x    | y    | z    |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| 1   | 0.23  | Ideal   | E     | SI2     | 61.5  | 55    | 326   | 3.95 | 3.98 | 2.43 |
| 2   | 0.21  | Premium | E     | SI1     | 59.8  | 61    | 326   | 3.89 | 3.84 | 2.31 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

Para obter uma lista de valores de formato de saída disponíveis, confira os comentários da configuração table_format no arquivo dbsqlclirc.

REPL

Para entrar no modo REPL (loop de leitura-avaliação-impressão) no escopo do banco de dados padrão, execute o seguinte comando:

dbsqlcli

Você também pode entrar no modo REPL no escopo de um banco de dados específico, executando o seguinte comando:

dbsqlcli <database-name>

Por exemplo:

dbsqlcli default

Para sair do modo REPL, execute o seguinte comando:

exit

No modo REPL, você pode usar os seguintes caracteres e chaves:

• Use o ponto e vírgula (;) para encerrar uma linha.
• Use F3 para alternar para o modo multilinha.
• Use a barra de espaços para mostrar sugestões no ponto de inserção, quando as sugestões ainda não estão exibidas.
• Use as setas para cima e para baixo para navegar nas sugestões.
• Use a seta para a direita para concluir a sugestão realçada.

Por exemplo:

dbsqlcli default

hostname:default> SELECT * FROM diamonds LIMIT 2;

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _c0 | carat | cut     | color | clarity | depth | table | price | x    | y    | z    |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| 1   | 0.23  | Ideal   | E     | SI2     | 61.5  | 55    | 326   | 3.95 | 3.98 | 2.43 |
| 2   | 0.21  | Premium | E     | SI1     | 59.8  | 61    | 326   | 3.89 | 3.84 | 2.31 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

2 rows in set
Time: 0.703s

hostname:default> exit

Log

A CLI do Databricks SQL registra suas mensagens no arquivo ~/.dbsqlcli/app.log por padrão. Para alterar esse nome de arquivo ou local, altere o valor da configuração log_file no dbsqlclircarquivo de configuração.

Por padrão, as mensagens são registradas no nível do log INFO e abaixo. Para alterar esse nível de log, altere o valor da configuração log_level no arquivo de configurações dbsqlclirc. Os valores de nível de log disponíveis incluem CRITICAL, ERROR, WARNING, INFO e DEBUG e são avaliados nessa ordem. NONE desabilita o registro em log.

Recursos adicionais

• LEIA-ME da CLI do Databricks SQL
• Tutorial da API de Execução de Instrução SQL do Databricks