Databricks SQL
Observação
Este artigo aborda a CLI SQL do Databricks, que é fornecida como está e não é suportada pelo Databricks por meio do canal do cliente do suporte técnico. Perguntas e solicitações de recursos podem ser comunicadas por meio da página Problemas do repositório databricks/databricks-sql-cli no GitHub.
A Databricks SQL interface de linha do comando ( ) permiteDatabricks SQL CLI que o SQL senhor execute consultas em seus Databricks SQL armazéns existentes a partir do terminal ou do Windows prompt de comando em vez de locais como o Databricks SQL editor ou um Databricks Notebook. Na linha de comando, o senhor obtém recursos de produtividade, como sugestões e realce de sintaxe.
Requisitos
Pelo menos um Databricks SQL armazém. Crie um depósito, se o senhor ainda não tiver um.
Python 3.7 ou superior. Para verificar se você possui o Python instalado, execute o comando
python --version
no seu terminal ou Prompt de Comando. (Em alguns sistemas, pode ser necessário inserirpython3
.) Instale o Python, caso ainda não o tenha instalado.pip, o instalador do pacote para Python. Versões mais recentes do Python instalam
pip
por default. Para verificar se você tempip
instalado, execute o comandopip --version
de seu terminal ou prompt de comando. (Em alguns sistemas, pode ser necessário inserirpip3
.) Instale o pip, caso ainda não o tenha instalado.(Opcional) A utilidade para criação e gerenciamento de ambientes virtuais Python, como venv. Os ambientes virtuais ajudam a garantir que você está usando as versões corretas do Python e do Databricks SQL CLI juntos. Configurar e usar ambientes virtuais está fora do escopo deste artigo. Para mais informações, consulte Criando Ambientes Virtuais.
Instalar a CLI 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 do PyPI executando pip
com um dos comandos a seguir.
pip install databricks-sql-cli
# Or...
python -m pip install databricks-sql-cli
Para atualizar uma versão instalada anteriormente do Databricks SQL CLI, execute pip
com um dos comandos a seguir.
pip install databricks-sql-cli --upgrade
# Or...
python -m pip install databricks-sql-cli --upgrade
Para verificar sua versão instalada da execução da CLI Databricks SQL pip
com um dos comandos a seguir.
pip show databricks-sql-cli
# Or...
python -m pip show databricks-sql-cli
Autenticação
Para autenticar, você deve fornecer à CLI Databricks SQL os detalhes de conexão do seu warehouse. Especificamente, você precisa dos valores hostnamedo servidor e do caminho HTTP . Você também deve produzir o Databricks SQL CLI com as credenciais de autenticação adequadas.
A CLI Databricks SQL dá suporte à autenticação access token pessoal do Databricks.
Para utilizar a autenticação access token pessoal do Databricks, crie um access token pessoal da seguinte forma:
Em seu Databricks workspace, clique em seu nome de usuário Databricks na barra superior e selecione Settings (Configurações ) no menu suspenso.
Clique em Desenvolvedor.
Ao lado do access token, clique em gerenciar.
Clique em Gerar novos tokens.
(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 vida útil (não recomendado), deixe a caixa Duração (dias) vazia (em branco).
Clique em Gerar.
Copie o token exibido em um local seguro e clique em Concluído.
Observação
Certifique-se de salvar os tokens copiados em um local seguro. Não compartilhe seus tokens copiados com outras pessoas. Se você perder os tokens copiados, não poderá regenerar exatamente os mesmos tokens. Em vez disso, você deve repetir este procedimento para criar novos tokens. Se você perder os tokens copiados ou acreditar que os tokens foram comprometidos, o Databricks recomenda fortemente que você exclua imediatamente esses tokens do seu workspace clicando no ícone da lixeira (Revogar) ao lado dos tokens na página access tokens .
Se o senhor não conseguir criar ou usar o site tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou o tokens ou não lhe deu permissão para criar ou usar o tokens. Consulte o administrador do site workspace ou os tópicos a seguir:
Você pode fornecer essas informações de autenticação à CLI do Databricks SQL de várias maneiras:
No arquivo de configurações
dbsqlclirc
em seu local default (ou especificando um arquivo de configurações alternativo por meio da opção--clirc
sempre que você executar um comando com a CLI Databricks SQL ). Consulte Arquivo de configurações.Definindo a variável de ambiente
DBSQLCLI_HOST_NAME
,DBSQLCLI_HTTP_PATH
eDBSQLCLI_ACCESS_TOKEN
. Veja variável de ambiente.Especificando as opções
--hostname
,--http-path
e--access-token
sempre que você executar um comando com a CLI Databricks SQL . Consulte Opções de comando.
Observação
O arquivo de configurações dbsqlclirc
deve estar presente, mesmo se você definir a variável de ambiente anterior ou especificar as opções de comando anteriores ou ambos.
Sempre que você executa a CLI Databricks SQL , ele procura detalhes de autenticação na seguinte ordem e para quando encontra o primeiro conjunto de detalhes:
As opções
--hostname
,--http-path
e--access-token
.As variáveis de ambiente
DBSQLCLI_HOST_NAME
,DBSQLCLI_HTTP_PATH
eDBSQLCLI_ACCESS_TOKEN
.O arquivo de configurações
dbsqlclirc
em seu local default (ou um arquivo de configurações alternativo especificado pela opção--clirc
).
Arquivo de configurações
Para usar o arquivo de configurações dbsqlclirc
para fornecer a CLI Databricks SQL com detalhes de autenticação para seu armazém Databricks SQL , execute a CLI Databricks SQL pela primeira vez, da seguinte maneira:
dbsqlcli
A CLI Databricks SQL cria um arquivo de configurações para você, em ~/.dbsqlcli/dbsqlclirc
no Unix, Linux e 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 até a seguinte seção:
# [credentials] # host_name = "" # http_path = "" # access_token = ""
Remova os quatro caracteres
#
e:Ao lado de
host_name
, insira o valor hostnamedo servidor de seu armazém dos requisitos entre os caracteres""
.Ao lado de
http_path
, insira o valor do caminho HTTP de seu depósito a partir dos requisitos entre os caracteres""
.Ao lado de
access_token
, insira o valor de seus access tokens pessoal dos requisitos entre os caracteres""
.
Por exemplo:
[credentials] host_name = "12345678901234567.8.gcp.databricks.com" http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a" access_token = "dapi12345678901234567890123456789012"
Salve o arquivo
dbsqlclirc
.
Como alternativa, em vez de usar o arquivo dbsqlclirc
em seu local default , 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 deve estar em conformidade com a sintaxe anterior.
variável de ambiente
Para usar a variável de ambiente DBSQLCLI_HOST_NAME
, DBSQLCLI_HTTP_PATH
e DBSQLCLI_ACCESS_TOKEN
para fornecer a CLI Databricks SQL com detalhes de autenticação para seu armazém Databricks SQL , faça o seguinte:
Para definir a variável de ambiente apenas para a sessão de terminal atual, execute os seguintes comandos. Para definir a variável de ambiente para todas as sessões de terminal, insira os seguintes comandos no arquivo startup do shell e reinicie o terminal. Nos comandos a seguir, substitua o valor de:
DBSQLCLI_HOST_NAME
com o valor hostnamedo servidor de seu armazém dos requisitos.DBSQLCLI_HTTP_PATH
com o valor do caminho HTTP de seu armazém dos requisitos.DBSQLCLI_ACCESS_TOKEN
com seu valor access tokens pessoal dos requisitos.
export DBSQLCLI_HOST_NAME="12345678901234567.8.gcp.databricks.com"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"
Para definir a variável 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 hostnamedo servidor de seu armazém dos requisitos.DBSQLCLI_HTTP_PATH
com o valor do caminho HTTP de seu armazém dos requisitos.DBSQLCLI_ACCESS_TOKEN
com seu valor access tokens pessoal dos requisitos.:
set DBSQLCLI_HOST_NAME="12345678901234567.8.gcp.databricks.com"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"
Para definir a variável de ambiente para todas as sessões do Prompt de Comando, execute os seguintes comandos e reinicie o seu Prompt de Comando, substituindo o valor de:
DBSQLCLI_HOST_NAME
com o valor hostnamedo servidor de seu armazém dos requisitos.DBSQLCLI_HTTP_PATH
com o valor do caminho HTTP de seu armazém dos requisitos.DBSQLCLI_ACCESS_TOKEN
com seu valor access tokens pessoal dos requisitos.
setx DBSQLCLI_HOST_NAME "12345678901234567.8.gcp.databricks.com"
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 a CLI Databricks SQL com detalhes de autenticação para seu depósito Databricks SQL , faça o seguinte:
Faça o seguinte sempre que executar um comando com a CLI Databricks SQL :
Especifique a opção
--hostname
e o valor hostnamedo servidor de seu warehouse nos requisitos.Especifique a opção
--http-path
e o valor do caminho HTTP de seu warehouse nos requisitos.Especifique a opção
--access-token
e o valor de seus access tokens pessoal nos requisitos.
Por exemplo:
dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "12345678901234567.8.gcp.databricks.com" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"
Fontes de consulta
A CLI do Databricks SQL permite que você execute query das seguintes maneiras:
De uma stringsde consulta.
De um arquivo.
Em uma abordagem de loop de leitura-avaliação-impressão (REPL). Essa abordagem fornece sugestões enquanto você digita.
stringsde consulta
Para executar uma query como strings, use a opção -e
seguida da query, representada como strings. 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 os formatos de saída, use a opção --table-format
junto com um valor como ascii
para 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 table_format
no arquivo dbsqlclirc
.
Arquivo
Para executar um arquivo que contém SQL, use a opção -e
seguida do caminho para um arquivo .sql
. Por exemplo:
dbsqlcli -e my-query.sql
Conteúdo do arquivo my-query.sql
de exemplo:
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 os formatos de saída, use a opção --table-format
junto com um valor como ascii
para 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 table_format
no arquivo dbsqlclirc
.
REPL
Para entrar no modo de loop read-evaluate-print (REPL) com escopo para o banco de dados default , 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 key:
Use o ponto e vírgula (
;
) para terminar uma linha.Use F3 para alternar o modo multilinha.
Use a barra de espaço para mostrar sugestões no ponto de inserção, se as sugestões ainda não estiverem exibidas.
Use as setas para cima e para baixo para navegar pelas sugestões.
Use a seta para a direita para concluir a sugestão destacada.
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
Registro em log
O Databricks SQL CLI logs suas mensagens para o arquivo ~/.dbsqlcli/app.log
pelo default. Para alterar o nome ou o local desse arquivo, altere o valor da configuração log_file
no arquivo de configurações dbsqlclirc
.
Em default, as mensagens são registradas no nível INFO
log e abaixo. Para alterar o nível do log, altere o valor da configuração log_level
no arquivo de configurações dbsqlclirc
. Os valores de nível disponíveis em log incluem CRITICAL
, ERROR
, WARNING
, INFO
e DEBUG
e são avaliados nessa ordem. NONE
desativa o registro em log.