Pular para o conteúdo principal

Databricks SQL CLI

important

O Databricks SQL CLI não está em desenvolvimento ativo.

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.

Para definir a variável de ambiente somente para a sessão atual do terminal, execute o seguinte comando. Para definir a variável de ambiente para todas as sessões de terminal, insira o seguinte comando no arquivo shell startup e reinicie o terminal. No comando a seguir, substitua o valor de:

  • DBSQLCLI_HOST_NAME com o valor do nome de host do servidor do seu depósito a partir dos requisitos.
  • DBSQLCLI_HTTP_PATH com o valor do caminho HTTP do seu armazém a partir dos requisitos.
  • DBSQLCLI_ACCESS_TOKEN com o valor de seus tokens de acesso pessoal dos requisitos.
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