Partilhar via

Databricks SQL CLI

  • Artigo

Nota

Este artigo aborda a CLI SQL do Databricks, que é fornecida no estado em que se encontra e não é suportada pelo Databricks através de canais de suporte técnico ao cliente. Perguntas e solicitações de recursos podem ser comunicadas através da página Problemas do repositório databricks/databricks-sql-cli no GitHub.

A interface de linha de comando do Databricks SQL (Databricks SQL CLI) permite que você execute consultas SQL em seus armazéns SQL Databricks existentes a partir do seu terminal ou Prompt de Comando do Windows em vez de locais como o editor SQL Databricks ou um bloco de anotações 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 servidor e caminho HTTP. Você também deve produzir a CLI do Databricks SQL com as credenciais de autenticação adequadas.

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

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

  1. No seu espaço de trabalho do Azure Databricks, clique no seu nome de utilizador do Azure Databricks na barra superior e, em seguida, selecione Definições na lista pendente.
  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 o ajude 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 Generate (Gerar).
  7. Copie o token exibido para um local seguro e clique em Concluído.

Nota

Certifique-se de salvar o token copiado em um local seguro. Não partilhe o seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente o mesmo token. Em vez disso, você deve repetir esse procedimento para criar um novo token. Se você perder o token copiado ou acreditar que o token foi comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu espaço de trabalho clicando no ícone da lixeira (Revogar) ao lado do token na página de tokens do Access.

Se você não conseguir criar ou usar tokens em seu espaço de trabalho, isso pode ser porque o administrador do espaço de trabalho desabilitou tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do espaço de trabalho ou os seguintes tópicos:

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 em seu local padrão (ou especificando um arquivo de configurações alternativo através da --clirc opção cada vez que você executa um comando com a CLI SQL Databricks). Consulte Arquivo de configurações.
  • Definindo as DBSQLCLI_HOST_NAMEvariáveis , DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN ambiente. Consulte Variáveis de ambiente.
  • Especificando as --hostnameopções , --http-pathe --access-token sempre que você executa um comando com a CLI SQL do Databricks. Consulte Opções de comando.

Nota

O dbsqlclirc arquivo de configurações deve estar presente, mesmo se você definir as variáveis de ambiente anteriores ou especificar as opções de comando anteriores ou ambas.

Sempre que você executa a CLI SQL do Databricks, ela procura detalhes de autenticação na seguinte ordem e para quando encontra o primeiro conjunto de detalhes:

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

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 o valor do nome de host do servidor do seu depósito a partir dos requisitos entre os "" caracteres.
    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 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. 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 usar as DBSQLCLI_HOST_NAMEvariáveis , DBSQLCLI_HTTP_PATHe de DBSQLCLI_ACCESS_TOKEN ambiente para fornecer à CLI do Databricks SQL detalhes de autenticação para 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_NAMEcom o valor de nome de host do servidor do seu armazém a partir dos requisitos.
  • DBSQLCLI_HTTP_PATHcom o valor do caminho HTTP do seu armazém a partir dos requisitos.
  • DBSQLCLI_ACCESS_TOKEN com o valor do seu 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 atual do Prompt de Comando, execute os seguintes comandos, substituindo o valor de:

  • DBSQLCLI_HOST_NAMEcom o valor de nome de host do servidor do seu armazém a partir dos requisitos.
  • DBSQLCLI_HTTP_PATHcom o valor do caminho HTTP do seu armazém a partir dos requisitos.
  • DBSQLCLI_ACCESS_TOKEN com o valor do seu 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_NAMEcom o valor de nome de host do servidor do seu armazém a partir dos requisitos.
  • DBSQLCLI_HTTP_PATHcom o valor do caminho HTTP do seu armazém a partir dos requisitos.
  • DBSQLCLI_ACCESS_TOKEN com o valor do seu 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 --hostnameopções , --http-pathe --access-token para fornecer à CLI do Databricks SQL detalhes de autenticação para seu armazém 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 e o --http-path valor do caminho HTTP do seu armazém a partir dos requisitos.
  • Especifique a opção e o --access-token valor do token de acesso pessoal a partir 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:

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 --table-format opção 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 table_format configuração no dbsqlclirc arquivo.

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 --table-format opção 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 table_format configuração no dbsqlclirc arquivo.

REPL

Para inserir o modo de loop de leitura-avaliação-impressão (REPL) com escopo no banco 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 dbsqlclirc arquivo 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 log_level valor da configuração no dbsqlclirc arquivo de configurações. 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