Pular para o conteúdo principal

Databricks SQL CLI

nota

Este artigo cobre o site Databricks SQL CLI, que é fornecido no estado em que se encontra e não é suportado pelo Databricks por meio do canal do cliente do suporte técnico. Perguntas e solicitações de recurso podem ser comunicadas por meio da página Issues do repositório databricks/databricks-sql-CLI em 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 Windows do 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 você ainda não tiver um.
  • Python 3.7 ou superior. Para verificar se o senhor tem o site Python instalado, execute o comando python --version no terminal ou no prompt de comando. (Em alguns sistemas, talvez seja necessário inserir python3 em vez disso.) Instale o Python, se o senhor ainda não o tiver instalado.
  • pip, o instalador do pacote para Python. As versões mais recentes de Python instalam pip por default. Para verificar se o senhor tem o site pip instalado, execute o comando pip --version no terminal ou no prompt de comando. (Em alguns sistemas, talvez seja necessário inserir pip3 em vez disso.) Instale o pip, se você ainda não o tiver instalado.
  • (Opcional) Um utilitário para criar e gerenciar Python ambientes virtuais, como o venv. Os ambientes virtuais ajudam a garantir que o senhor esteja usando as versões corretas do Python e do Databricks SQL CLI juntos. A configuração e o uso de ambientes virtuais estão fora do escopo deste artigo. Para obter mais informações, consulte Criação de ambientes virtuais.

Instalar o Databricks SQL CLI​

Depois de atender aos requisitos, instale o pacote Databricks SQL CLI a partir do Python Packaging Index (PyPI). O senhor pode usar pip para instalar o pacote Databricks SQL CLI a partir de PyPI executando pip com um dos seguintes comandos.

Bash
pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Para atualizar uma versão previamente instalada do Databricks SQL CLI, execute pip com um dos seguintes comandos.

Bash
pip install databricks-sql-cli --upgrade

# Or...

python -m pip install databricks-sql-cli --upgrade

Para verificar a versão instalada do site Databricks SQL CLI execute pip com um dos seguintes comandos.

Bash
pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Autenticação​

Para autenticar, o senhor deve fornecer à CLI do Databricks SQL os detalhes de conexão do seu depósito. Especificamente, você precisa dos valores do nome do host do servidor e do caminho HTTP . O senhor também deve fornecer 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 de tokens de acesso pessoal e, para Databricks SQL CLI versões 0.2.0 e acima, OAuth autenticação de usuário para 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 de tokens de acesso pessoal Databricks, o senhor deve criar um token de acesso pessoal. Para obter detalhes sobre esse processo, consulte Databricks autenticação de tokens de acesso pessoal.

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

O senhor pode fornecer essas informações de autenticação para o Databricks SQL CLI 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 toda vez que o senhor executar um comando com o Databricks SQL CLI). Consulte Arquivo de configurações.
  • Para Databricks autenticação de tokens de acesso pessoal, definindo as variáveis de ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN. Ver variável de ambiente.
  • Para Databricks OAuth autenticação U2M, definindo as variáveis de ambiente DBSQLCLI_HOST_NAME e DBSQLCLI_HTTP_PATH e especificando a opção --oauth comando-line ou definindo auth_type = "databricks-oauth" no arquivo de configurações dbsqlclirc. Ver variável de ambiente.
  • Para a autenticação de tokens de acesso pessoal Databricks, especifique as opções --hostname, --http-path e --access-token sempre que executar um comando com o Databricks SQL CLI. Consulte Opções de comando.
  • Para a autenticação Databricks OAuth U2M, especificando as opções --hostname e --http-path comando-line e especificando a opção --oauth comando-line ou definindo auth_type = "databricks-oauth" no arquivo de configurações dbsqlclirc, toda vez que o senhor executar um comando com o Databricks SQL CLI. Consulte Opções de comando.
nota

O arquivo de configurações dbsqlclirc deve estar presente, mesmo que o senhor defina a variável de ambiente anterior ou especifique as opções de comando anteriores ou ambas.

Sempre que o senhor executa o Databricks SQL CLI, ele procura os 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 de tokens de acesso pessoal 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 ao Databricks SQL CLI os detalhes de autenticação do seu depósito Databricks SQL, execute o Databricks SQL CLI pela primeira vez, como segue:

Bash
dbsqlcli

A CLI do Databricks SQL cria um arquivo de configurações para o senhor, em ~/.dbsqlcli/dbsqlclirc no Unix, Linux e macOS, e em %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc ou %USERPROFILE%\.dbsqlcli\dbsqlclirc no Windows. Para personalizar esse arquivo:

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

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

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

  3. Remova os quatro caracteres # e:

    1. Ao lado de host_name, insira o valor do nome de host do servidor do seu depósito a partir dos requisitos entre os caracteres "".

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

    3. Ao lado de access_token, digite o valor de seus tokens de acesso pessoal a partir dos requisitos entre os caracteres "".

nota

Para a autenticação Databricks OAuth U2M, o senhor 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 do Databricks SQL.

Por exemplo:

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

Como alternativa, em vez de usar o arquivo dbsqlclirc em seu local default, o senhor 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 de tokens de acesso pessoal Databricks, a variável de ambiente DBSQLCLI_ACCESS_TOKEN) para fornecer ao Databricks SQL CLI os detalhes de autenticação do seu depósito Databricks SQL, faça o seguinte.

nota

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

To set the environment variables for only the current terminal session, run the following commands. To set the environment variables for all terminal sessions, enter the following commands into your shell’s startup file and then restart your terminal. In the following commands, replace the value of:

  • DBSQLCLI_HOST_NAME with your warehouse’s Server hostname value from the requirements.
  • DBSQLCLI_HTTP_PATH with your warehouse’s HTTP path value from the requirements.
  • DBSQLCLI_ACCESS_TOKEN with your personal access token value from the requirements.
Bash
export DBSQLCLI_HOST_NAME="dbc-a1b2345c-d6e78.cloud.databricks.com"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export 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 os detalhes de autenticação do seu depósito do Databricks SQL, faça o seguinte:

Faça o seguinte sempre que o senhor executar um comando com o Databricks SQL CLI:

  • Especifique a opção --hostname e o valor do nome de host do servidor do seu depósito a partir dos requisitos.

  • Especifique a opção --http-path e o valor do caminho HTTP do seu depósito a partir dos requisitos.

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

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

nota

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

Por exemplo:

Para Databricks autenticação de tokens de acesso pessoal:

Bash
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 a autenticação OAuth U2M da Databricks:

Bash
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​

O site Databricks SQL CLI permite que o senhor execute consultas das seguintes maneiras:

Strings de consulta​

Para executar uma consulta como uma cadeia de caracteres, use a opção -e seguida da consulta, representada como uma cadeia de caracteres. Por exemplo:

Bash
dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2"

Saída:

Bash
_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:

Bash
dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" --table-format ascii

Saída:

Bash
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 dos valores de formato de saída disponíveis, consulte os comentários sobre a configuração table_format no arquivo dbsqlclirc.

Arquivo​

Para executar um arquivo que contenha SQL, use a opção -e seguida do caminho para um arquivo .sql. Por exemplo:

Bash
dbsqlcli -e my-query.sql

Conteúdo do arquivo de exemplo my-query.sql:

SQL
SELECT * FROM default.diamonds LIMIT 2;

Saída:

Bash
_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:

Bash
dbsqlcli -e my-query.sql --table-format ascii

Saída:

Bash
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 dos valores de formato de saída disponíveis, consulte os comentários sobre a configuração table_format no arquivo dbsqlclirc.

RESPONDER​

Para entrar no modo REPL (read-evaluate-print loop) com escopo para o banco de dados default, execute o seguinte comando:

Bash
dbsqlcli

O senhor também pode entrar no modo REPL com escopo de um banco de dados específico, executando o seguinte comando:

Bash
dbsqlcli <database-name>

Por exemplo:

Bash
dbsqlcli default

Para sair do modo REPL, execute o seguinte comando:

Bash
exit

No modo REPL, o senhor pode usar os seguintes caracteres e teclas:

  • Use o ponto e vírgula (;) para finalizar 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:

Bash
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​

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.

Recurso adicional​

Última atualização em