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.

A CLI do Databricks SQL oferece suporte aos tokens de acesso pessoal (PATs) do Databricks. Para usar a autenticação Databricks PAT, o senhor deve criar tokens de acesso pessoal. Para obter detalhes sobre esse processo, consulte Databricks autenticação de tokens de acesso pessoal.

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.
  • Ao definir o DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN variável de ambiente. Ver variável de ambiente.
  • Especificando as opções --hostname, --http-path e --access-token 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.
  2. Os senhores podem acessar DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN variável de ambiente.
  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 "".

    Por exemplo:

    [credentials]
    host_name = "12345678901234567.8.gcp.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, 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, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN para fornecer ao Databricks SQL CLI os detalhes de autenticação do seu depósito Databricks SQL, faça o seguinte:

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="12345678901234567.8.gcp.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 para fornecer à CLI do Databricks SQL os detalhes de autenticação do 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.
  • Especifique a opção --access-token e o valor de seus tokens de acesso pessoal de acordo com os requisitos.

Por exemplo:

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

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