CLI do Databricks SQL
Observação
Este artigo aborda a CLI de SQL do Databricks, que é fornecida no estado em que se encontra e não tem suporte do Databricks por meio de canais de suporte técnico ao cliente. As dúvidas e solicitações de recursos podem ser comunicadas por meio da página Problemas do repositório databricks/databricks-sql-cli no GitHub.
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 --versionno terminal ou no prompt de comando. (Em alguns sistemas, talvez seja necessário inserirpython3.) 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
pippor padrão. Para verificar se opipestá instalado, execute o comandopip --versionno terminal ou no prompt de comando. (Em alguns sistemas, talvez seja necessário inserirpip3.) 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 (antigo Azure Active Directory).
Para usar a autenticação de token de acesso pessoal do Azure Databricks, crie um token de acesso pessoal da seguinte forma:
- No workspace do Azure Databricks, clique no nome de usuário do Azure Databricks na barra superior e selecione Configurações na lista suspensa.
- Clique em Desenvolvedor.
- Ao lado de Tokens de acesso, clique em Gerenciar.
- Clique em Gerar novo token.
- (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).
- Clique em Gerar.
- Copie o token exibido para um local seguro e clique em Concluído.
Observação
Lembre-se de salvar o token copiado em um local seguro. Não compartilhe seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente aquele mesmo token. Em vez disso, será necessário repetir esse procedimento para criar um novo token. Caso você tenha perdido o token copiado ou acredite que ele tenha sido comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu workspace clicando no ícone de lixeira (Revogar) ao lado do token na página de Tokens de acesso.
Se você não conseguir criar ou usar tokens em seu workspace, isso pode ocorrer porque o administrador do workspace desabilitou tokens ou não deu permissão para criar ou usar tokens. Veja o administrador do workspace ou o seguinte:
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
dbsqlclircno local padrão (ou especificando um arquivo de configurações alternativo por meio da opção--clircsempre 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_PATHeDBSQLCLI_ACCESS_TOKEN. Confira Variáveis de ambiente. - Especificando as opções e
--hostname,--http-pathe--access-tokensempre que você executar um comando com a CLI do Databricks SQL. Confira Opções de comando.
Observação
O arquivo de configurações dbsqlclirc deverá estar presente, mesmo se você definir as variáveis de ambiente anteriores ou especificar as opções de comando anteriores, ou ambos.
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:
- As opções
--hostname,--http-pathe--access-token. - As variáveis de ambiente
DBSQLCLI_HOST_NAME,DBSQLCLI_HTTP_PATHeDBSQLCLI_ACCESS_TOKEN. - O arquivo de configurações
dbsqlclircno 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:
Use um editor de texto para abrir e editar o arquivo
dbsqlclirc.Role para a seguinte seção:
# [credentials] # host_name = "" # http_path = "" # access_token = ""Remova os quatro caracteres
#e:- Ao lado de
host_name, insira o valor de Nome do host do servidor do warehouse necessário entre os caracteres"". - Ao lado de
http_path, insira o valor de Caminho HTTP do warehouse necessário entre os caracteres"". - 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"- Ao lado de
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_NAMEcom o valor de Nome do host do servidor do warehouse necessário.DBSQLCLI_HTTP_PATHcom o valor de Caminho HTTP do warehouse necessário.DBSQLCLI_ACCESS_TOKENpelo 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_NAMEcom o valor de Nome do host do servidor do warehouse necessário.DBSQLCLI_HTTP_PATHcom o valor de Caminho HTTP do warehouse necessário.DBSQLCLI_ACCESS_TOKENpelo 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_NAMEcom o valor de Nome do host do servidor do warehouse necessário.DBSQLCLI_HTTP_PATHcom o valor de Caminho HTTP do warehouse necessário.DBSQLCLI_ACCESS_TOKENpelo 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
--hostnamee o valor de Nome de host do servidor do warehouse necessário. - Especifique a opção
--http-pathe o valor de Caminho HTTP do warehouse necessário. - Especifique a opção
--access-tokene 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ções.
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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de