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 interface de linha de comando do Databricks SQL(Databricks SQL CLI) permite que o senhor execute consultas SQL em seus depósitos existentes do Databricks SQL a partir do seu terminal ou do prompt de comando do Windows, em vez de locais como o editor do Databricks SQL 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 inserir python3 .) 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ê tem pip instalado, execute o comando pip --version de seu terminal ou prompt de comando. (Em alguns sistemas, pode ser necessário inserir pip3 .) 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 do SQL do Databricks dá suporte a dois tipos de autenticação do Databricks: autenticação access token pessoal do Databricks e, para as versões 0.2.0 e acima da CLI do SQL do Databricks, autenticação usuário-máquina (U2M) do OAuth.

Para utilizar a autenticação access token pessoal do Databricks, crie um access token pessoal da seguinte forma:

  1. Em seu Databricks workspace, clique em seu nome de usuário Databricks na barra superior e selecione Settings (Configurações ) no menu suspenso.

  2. Clique em Desenvolvedor.

  3. Ao lado do access token, clique em gerenciar.

  4. Clique em Gerar novos tokens.

  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 vida útil (não recomendado), deixe a caixa Duração (dias) vazia (em branco).

  6. Clique em Gerar.

  7. 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 não for possível criar ou usar tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou os tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do workspace ou o seguinte:

Não há requisitos de configuração para usar a autenticação OAuth U2M.

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.

  • Para autenticação access token pessoal do Databricks, definindo a variável de ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN. Veja variável de ambiente.

  • Para autenticação U2M do Databricks OAuth, definindo a variável de ambiente DBSQLCLI_HOST_NAME e DBSQLCLI_HTTP_PATH e especificando a opção de linha de comando --oauth ou definindo auth_type = "databricks-oauth" no arquivo de configurações dbsqlclirc . Veja variável de ambiente.

  • Para autenticação access token pessoal do Databricks, especificando as opções --hostname, --http-path e --access-token sempre que você executa um comando com a CLI Databricks SQL . Consulte Opções de comando.

  • Para autenticação Databricks OAuth U2M, especificando as opções de linha de comando --hostname e --http-path e especificando a opção de linha de comando --oauth ou definindo auth_type = "databricks-oauth" no arquivo de configurações dbsqlclirc, 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:

  1. As opções --hostname, --http-path e --access-token ou --oauth .

  2. As variáveis de ambiente DBSQLCLI_HOST_NAME e DBSQLCLI_HTTP_PATH (e, para autenticação access token pessoal do Databricks, a variável de ambiente DBSQLCLI_ACCESS_TOKEN).

  3. 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:

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

  2. Role até a seguinte seção:

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

  3. Remova os quatro caracteres # e:

    1. Ao lado de host_name, insira o valor hostnamedo servidor de seu armazém dos requisitos entre os caracteres "".

    2. Ao lado de http_path, insira o valor do caminho HTTP de seu depósito a partir dos requisitos entre os caracteres "" .

    3. Ao lado de access_token, insira o valor de seus access tokens pessoal dos requisitos entre os caracteres "".

      Observação

      Para a autenticação U2M do Databricks OAuth, você deve substituir access_token por auth_type = "databricks-oauth" ou especificar a opção de linha de comando --oauth em cada chamada para a CLI Databricks SQL .

    Por exemplo:

    [credentials]
host_name = "dbc-a1b2345c-d6e78.cloud.databricks.com"
http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
access_token = "dapi12345678901234567890123456789012"

  4. 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 as variáveis de ambiente DBSQLCLI_HOST_NAME e DBSQLCLI_HTTP_PATH (e, para autenticação access token pessoal do Databricks, a variável de ambiente DBSQLCLI_ACCESS_TOKEN) para fornecer à CLI Databricks SQL detalhes de autenticação para seu warehouse Databricks SQL , faça o seguinte.

Observação

Para a autenticação U2M do Databricks OAuth, você deve definir auth_type = "databricks-oauth" no arquivo de configurações dbsqlclirc ou especificar a opção de comando --oauth com cada chamada para a CLI Databricks SQL .

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="dbc-a1b2345c-d6e78.cloud.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="dbc-a1b2345c-d6e78.cloud.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 "dbc-a1b2345c-d6e78.cloud.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 ou --oauth para fornecer à CLI do Databricks SQL detalhes de autenticação para seu warehouse SQL do Databricks, 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.

  • Para autenticação access token pessoal do Databricks, especifique a opção --access-token e o valor access token pessoal dos requisitos.

  • Para autenticação Databricks OAuth U2M, especifique --oauth.

    Observação

    Para a autenticação U2M do Databricks OAuth, você deve especificar auth_type = "databricks-oauth" no arquivo de configurações dbsqlclirc ou especificar a opção de comando --oauth com cada chamada para a CLI Databricks SQL .

Por exemplo:

Para autenticação access token pessoal do Databricks:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "dbc-a1b2345c-d6e78.cloud.databricks.com" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"

Para autenticação Databricks OAuth U2M:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "dbc-a1b2345c-d6e78.cloud.databricks.com" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--oauth

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.