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.
O Databricks SQL CLI oferece suporte ao Databricks personal access tokens (PATs). Para usar a autenticação Databricks PAT, o senhor deve criar um access token pessoal. Para obter detalhes sobre esse processo, consulte Databricks personal access token authentication.
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.