Databricks SQL CLI

A interface de linha de comando do Databricks SQL (Databricks SQL CLI) permite executar consultas SQL nos seus armazéns de SQL Databricks existentes a partir do terminal ou do Prompt de Comando do Windows em vez de locais como o editor 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 armazém SQL Databricks. Crie um armazém, se ainda não tiver um.
• Python 3.7 ou superior. Para verificar se você tem o Python instalado, execute o comando python --version a partir do seu terminal ou prompt de comando. (Em alguns sistemas, talvez seja necessário inserir python3 .) Instale o Python, se ainda não o tiver instalado.
• pip, o instalador de pacotes para Python. As versões mais recentes do Python são instaladas pip por padrão. Para verificar se você instalou pip , execute o comando pip --version no seu terminal ou prompt de comando. (Em alguns sistemas, talvez seja necessário inserir pip3 .) Instale o pip, se ainda não o tiver instalado.
• (Opcional) Um utilitário para criar e gerenciar ambientes virtuais Python, como venv. Os ambientes virtuais ajudam a garantir que você esteja usando as versões corretas do Python e da CLI SQL do Databricks juntas. A configuração e o uso de ambientes virtuais estão fora do escopo deste artigo. Para obter mais informações, consulte Criando ambientes virtuais.

Instalar a CLI do Databricks SQL

Depois de atender aos requisitos, instale o pacote Databricks SQL CLI do Python Packaging Index (PyPI). Você pode usar pip para instalar o pacote Databricks SQL CLI 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 instalada anteriormente da CLI 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 a versão instalada da CLI 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 SQL do Databricks os detalhes de conexão do seu depósito. Especificamente, você precisa dos valores de nome de host do Server e de caminho HTTP . Você também deve produzir a CLI do Databricks SQL com as credenciais de autenticação adequadas.

A CLI do Databricks SQL suporta tokens de acesso pessoal do Databricks (PATs). Para usar a autenticação PAT do Azure Databricks, você deve criar um token de acesso pessoal. Para obter detalhes sobre este processo, veja Autenticar com tokens de acesso pessoal do Azure Databricks (legado).

Não há suporte para tokens de ID do Microsoft Entra.

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

• dbsqlclirc No arquivo de configurações no seu local padrão (ou especificando um arquivo de configurações alternativo através da opção --clirc cada vez que se executa um comando com a CLI SQL Databricks). Consulte Arquivo de configurações.
• Definindo as variáveis de ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN. Consulte Variáveis de ambiente.
• Especificando as opções --hostname, --http-path e --access-token sempre que executares um comando com a CLI SQL do Databricks. Consulte Opções de comando.

Sempre que o utilizador executa a CLI SQL do Databricks, procura os detalhes de autenticação na seguinte ordem e interrompe quando encontra 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 dbsqlclirc arquivo de configurações na sua localização padrão (ou um arquivo de configurações alternativo especificado pela opção --clirc).

Arquivo de configurações

Para usar o dbsqlclirc arquivo de configurações para fornecer à CLI do Databricks SQL detalhes de autenticação para seu armazém SQL do Databricks, execute a CLI do Databricks SQL pela primeira vez, da seguinte maneira:

dbsqlcli

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

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

2. Desloque-se para a seguinte secção:

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

3. Remova os quatro # caracteres e:

   1. Ao lado de host_name, insira entre os caracteres o valor do "" do seu depósito conforme os requisitos.
   2. Ao lado de http_path, insira o valor do caminho HTTP do seu depósito a partir dos requisitos entre os "" caracteres.
   3. Ao lado de access_token, insira o valor do seu token pessoal de acesso conforme os 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. Guarde o ficheiro dbsqlclirc.

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

Variáveis de ambiente

Para utilizar as variáveis de ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN para fornecer à CLI do Databricks SQL os detalhes de autenticação para o seu armazém SQL do Databricks, faça o seguinte:

Unix, Linux e macOS

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

• DBSQLCLI_HOST_NAME com o valor nome de host do servidor do seu armazém conforme definido nos requisitos.
• DBSQLCLI_HTTP_PATH com o valor do caminho HTTP do seu armazém segundo os requisitos.
• DBSQLCLI_ACCESS_TOKEN com o valor do seu token de acesso pessoal nos requisitos.

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

Mac OS

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

• DBSQLCLI_HOST_NAME com o valor nome de host do servidor do seu armazém conforme definido nos requisitos.
• DBSQLCLI_HTTP_PATH com o valor do caminho HTTP do seu armazém segundo os requisitos.
• DBSQLCLI_ACCESS_TOKEN com o valor do seu token de acesso pessoal conforme especificado nos 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 nome de host do servidor do seu armazém conforme definido nos requisitos.
• DBSQLCLI_HTTP_PATH com o valor do caminho HTTP do seu armazém segundo os requisitos.
• DBSQLCLI_ACCESS_TOKEN com o valor do seu token de acesso pessoal nos 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 para fornecer à CLI do Databricks SQL os detalhes de autenticação para o seu armazém de SQL do Databricks, faça o seguinte:

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

• Especifique a opção e o --hostname valor do nome de host do servidor do seu depósito a partir dos requisitos.
• Especifique a opção --http-path e o valor do caminho HTTP do seu armazém a partir dos requisitos.
• Especifique a opção --access-token e o valor do token de acesso pessoal conforme os 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:

• A partir de uma string de consulta.
• A partir de um ficheiro.
• Numa abordagem de ciclo de leitura-avaliação-impressão (REPL). Essa abordagem fornece sugestões à medida que você digita.

Cadeias de consulta

Para executar uma consulta como uma cadeia de caracteres, use a -e opção 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 alternar formatos 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, consulte os comentários para a configuração de table_format no arquivo dbsqlclirc.

Ficheiro

Para executar um arquivo que contém SQL, use a -e opção seguida pelo caminho para um .sql arquivo. 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 alternar formatos 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, consulte os comentários para a configuração de table_format no arquivo dbsqlclirc.

REPL (Read-Eval-Print Loop - Ler-Avaliar-Imprimir Loop)

Para entrar no modo de ciclo de leitura-avaliação-impressão (REPL) limitado à base de dados padrão, execute o seguinte comando:

dbsqlcli

Você também pode entrar no modo REPL com escopo para 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 teclas:

• Use o ponto-e-vírgula (;) para encerrar uma linha.
• Use F3 para alternar o modo de várias linhas.
• Use a barra de espaço para mostrar sugestões no ponto de inserção, se as sugestões ainda não forem exibidas.
• Use as setas para cima e para baixo para navegar pelas sugestões.
• Use a seta para a direita para completar 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

Registo

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 log_file valor da configuração no dbsqlclircarquivo de configurações.

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

Recursos adicionais

• Leiame da CLI SQL do Databricks
• Tutorial da API de execução de instrução SQL do Databricks