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

O Databricks SQL CLI oferece suporte a dois tipos de autenticação Databricks: Databricks autenticação pessoal access token e, para Databricks SQL CLI versões 0.2.0 e acima, OAuth autenticação usuário-máquina (U2M). A Databricks recomenda que o senhor use o OAuth para obter maior segurança e facilidade de uso.

Para usar a autenticação Databricks pessoal access token, o senhor deve criar um access token pessoal. Para obter detalhes sobre esse processo, consulte Databricks personal access token authentication.

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.