Databricks SQL CLI

Статья
11/16/2024

Примечание.

В этой статье рассматривается Databricks SQL CLI, который предоставляется на условиях "как есть" и не поддерживается через каналы технической поддержки Databricks. Вопросы и запросы функций можно оставлять на странице Проблемы в репозитории GitHub databricks/databricks-sql-cli.

Интерфейс командной строки Databricks SQL (Databricks SQL CLI) позволяет выполнять SQL-запросы к существующим хранилищам Databricks SQL из окна терминала или командной строки Windows вместо таких расположений, как редактор Databricks SQL или записная книжка Azure Databricks. В командной строке вы получаете дополнительные возможности для повышения производительности, в том числе предложения и выделение синтаксиса.

Требования

По меньшей мере одно хранилище Databricks SQL. Создайте хранилище, если у вас еще нет.
Python 3.7 или более поздней версии. Чтобы проверить, установлен ли Python, выполните команду python --version из терминала или командной строки. (В некоторых системах вместо этого придется ввести python3.) Установите Python, если он еще не установлен.
Установщик пакетов для Python pip. Более новые версии Python содержат pip по умолчанию. Чтобы проверить, установлен ли pip, выполните команду pip --version из терминала или командной строки. (В некоторых системах вместо этого придется ввести pip3.) Установите pip, если он еще не установлен.
(Необязательно) Служебная программа для создания виртуальных сред Python и управления ими, таких как venv. Виртуальные среды помогают гарантировать правильные сочетания версий Python и Databricks SQL CLI. Настройка и использование виртуальных сред выходят за рамки этой статьи. Дополнительные сведения см. в разделе Создание виртуальных сред.

Установка интерфейса командной строки Databricks SQL

Выполнив предварительные требования, установите пакет интерфейса командной строки Databricks SQL из списка пакетов Python (PyPI). Вы можете установить pip пакет ИНТЕРФЕЙСА командной строки SQL Databricks из PyPI, выполнив pip одну из следующих команд.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Чтобы обновить ранее установленную версию интерфейса командной строки SQL Databricks, выполните pip одну из следующих команд.

pip install databricks-sql-cli --upgrade

# Or...

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

Чтобы проверить установленную версию интерфейса командной строки SQL Databricks, выполните pip одну из следующих команд.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Проверка подлинности

Чтобы пройти проверку подлинности, необходимо указать интерфейс командной строки SQL Databricks с сведениями о подключении к хранилищу. В частности, вам потребуются значения имени узла сервера и пути HTTP. Кроме того, необходимо продукт databricks SQL CLI с соответствующими учетными данными проверки подлинности.

Интерфейс командной строки SQL Databricks поддерживает личные маркеры доступа Databricks (PATs). Чтобы использовать проверку подлинности Azure Databricks PAT, необходимо создать личный маркер доступа. Дополнительные сведения об этом процессе см. в статье Azure Databricks с проверкой подлинности личного маркера доступа.

Маркеры идентификатора Microsoft Entra не поддерживаются.

Эти сведения проверки подлинности можно указать в интерфейсе командной строки SQL Databricks несколькими способами:

В файле параметров dbsqlclirc, расположенного в стандартном каталоге (или в любом альтернативном файле параметров, расположение которого указывается в параметре --clirc при каждом выполнении команды в Databricks SQL CLI). См. раздел Файл параметров.
Путем настройки переменных среды DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH и DBSQLCLI_ACCESS_TOKEN. См. раздел Переменные среды.
Указывая параметры --hostname, --http-path и --access-token при каждом выполнении команды в Databricks SQL CLI. См. раздел Параметры команды.

Примечание.

Файл параметров dbsqlclirc должен присутствовать, даже если вы задали предыдущие переменные среды или указали предыдущие параметры команды или и то, и другое одновременно.

При запуске интерфейса командной строки SQL Databricks он ищет сведения о проверке подлинности в следующем порядке и останавливается при поиске первого набора сведений:

параметры --hostname, --http-path и --access-token;
переменные среды DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH и DBSQLCLI_ACCESS_TOKEN;
файл параметров dbsqlclirc в стандартном расположении (или альтернативный файл параметров, если он задан параметром--clirc).

Файл параметров

Чтобы использовать файл параметров dbsqlclirc для передачи в Databricks SQL CLI сведений об аутентификации в хранилище Databricks SQL, для первого запуска Databricks SQL CLI используйте следующий метод:

dbsqlcli

Databricks SQL CLI создаст файл параметров в каталоге ~/.dbsqlcli/dbsqlclirc (Unix, Linux и macOS), %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc или %USERPROFILE%\.dbsqlcli\dbsqlclirc (Windows). Чтобы изменить этот файл, выполните следующее.

Откройте файл dbsqlclirc для правки в текстовом редакторе.
Прокрутите содержимое вниз до следующего раздела.
```
# [credentials]
# host_name = ""
# http_path = ""
# access_token = ""
```
Удалите четыре символа #.
1. Рядом с host_name введите значение имени узла сервера хранилища, которое вы получили на этапе подготовки предварительных требований, заключив его между символами "".
2. Рядом с http_path введите значение пути HTTP хранилища, которое вы получили на этапе подготовки предварительных требований, заключив его между символами "".
3. Рядом с access_token введите значение личного маркера доступа, которое вы получили на этапе подготовки предварительных требований, заключив его между символами "".
Например:
```
[credentials]
host_name = "adb-12345678901234567.8.azuredatabricks.net"
http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
access_token = "dapi12345678901234567890123456789012"
```
Сохраните файл dbsqlclirc.

Кроме того, вместо использования файла dbsqlclirc в стандартном расположении, вы можете указать другое расположение для этого файла, добавив параметр команды --clirc с путем к альтернативному файлу. Содержимое альтернативного файла должно соответствовать описанному выше синтаксису.

Переменные среды

Чтобы использовать переменные среды DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH и DBSQLCLI_ACCESS_TOKEN для предоставления в Databricks SQL CLI сведений об аутентификации в хранилище Databricks SQL, сделайте следующее:

Unix, Linux и macOS

Чтобы задать переменные среды только для текущего сеанса терминала, выполните следующие команды. Чтобы задать переменные среды для всех сеансов терминала, введите следующие команды в файл запуска оболочки и перезапустите терминал. В следующих командах замените указанные значения:

DBSQLCLI_HOST_NAME значением имени узла сервера хранилища, которое вы получили на этапе подготовки предварительных требований.
DBSQLCLI_HTTP_PATH значением пути HTTP хранилища, которое вы получили на этапе подготовки предварительных требований.
замените DBSQLCLI_ACCESS_TOKEN значением личного маркера доступа конечной точки, которое вы получили на этапе подготовки предварительных требований.

export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

Чтобы задать переменные среды только для текущего сеанса командной строки, выполните следующие команды, заменив в них следующие значения:

DBSQLCLI_HOST_NAME значением имени узла сервера хранилища, которое вы получили на этапе подготовки предварительных требований.
DBSQLCLI_HTTP_PATH значением пути HTTP хранилища, которое вы получили на этапе подготовки предварительных требований.
замените DBSQLCLI_ACCESS_TOKEN значением личного маркера доступа конечной точки, которое вы получили на этапе подготовки предварительных требований.

set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Чтобы задать переменные среды для всех сеансов командной строки, выполните следующие команды и перезапустите командную строку, заменив в них следующие значения:

DBSQLCLI_HOST_NAME значением имени узла сервера хранилища, которое вы получили на этапе подготовки предварительных требований.
DBSQLCLI_HTTP_PATH значением пути HTTP хранилища, которое вы получили на этапе подготовки предварительных требований.
замените DBSQLCLI_ACCESS_TOKEN значением личного маркера доступа конечной точки, которое вы получили на этапе подготовки предварительных требований.

setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

Параметры команды

Чтобы использовать параметры --hostname, --http-path и --access-token для предоставления в Databricks SQL CLI сведений об аутентификации в хранилище Databricks SQL, сделайте следующее:

Выполните следующие действия при каждом выполнении команды с помощью интерфейса командной строки SQL Databricks:

укажите параметр --hostname со значением имени узла сервера хранилища, которое вы получили на этапе подготовки предварительных требований;
укажите параметр --http-path со значением пути HTTP хранилища, которое вы получили на этапе подготовки предварительных требований;
укажите параметр --access-token со значением личного маркера доступа для конечной точки, которое вы получили на этапе подготовки предварительных требований.

Например:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "adb-12345678901234567.8.azuredatabricks.net" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"

Источники запросов

Databricks SQL CLI позволяет выполнять запросы следующими способами:

из строки запроса;
из файла;
в цикле read–eval–print loop (REPL). Этот подход предоставляет предложения по мере ввода.

Строка запроса

Чтобы выполнить запрос в формате строки, используйте параметр -e и укажите после него запрос, представленный в виде строки. Например:

dbsqlcli -e "SELECT * FROM default.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

Чтобы изменить формат выходных данных, используйте параметр --table-format с указанием нужного значения, например ascii обозначает формат таблицы ASCII:

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

Выходные данные:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

Список доступных значений для формата выходных данных см. в комментариях к параметру table_format в файле dbsqlclirc.

Файлы

Чтобы запустить файл, который содержит код SQL, используйте параметр -e, за которым указан путь к файлу .sql. Например:

dbsqlcli -e my-query.sql

Содержимое примера файла my-query.sql:

SELECT * FROM default.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

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

Выходные данные:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

Список доступных значений для формата выходных данных см. в комментариях к параметру table_format в файле dbsqlclirc.

REPL

Чтобы перейти в режим read–eval–print loop (REPL) в области действия базы данных по умолчанию, выполните следующую команду:

dbsqlcli

Вы также можете перейти в режим REPL в области действия конкретной базы данных, выполнив следующую команду:

dbsqlcli <database-name>

Например:

dbsqlcli default

Чтобы выйти из режима REPL, выполните следующую команду:

exit

В режиме REPL можно использовать следующие символы и клавиши:

Точка с запятой (;) обозначает завершение строки.
Клавиша F3 переключает многострочный режим.
Пробел отображает предложения для текущей точки вставки, если они еще не отображаются.
Стрелки вверх и вниз выполняют переход между предложениями.
Стрелка вправо применяет выделенное предложение.

Например:

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

Ведение журнала

Интерфейс командной строки SQL Databricks записывает сообщения в файл ~/.dbsqlcli/app.log по умолчанию. Чтобы изменить имя файла или расположение, измените значение log_file параметра в dbsqlclirc файле параметров.

По умолчанию сообщения регистрируются на INFO уровне журнала и ниже. Чтобы изменить этот уровень журнала, измените значение log_level параметра в dbsqlclirc файле параметров. Доступные значения уровня журнала включают CRITICAL, ERROR, INFOWARNINGи DEBUG вычисляются в этом порядке. NONE отключает ведение журнала.

Поделиться через

Databricks SQL CLI

Требования

Установка интерфейса командной строки Databricks SQL

Проверка подлинности

Файл параметров

Переменные среды

Unix, Linux и macOS

Windows

Параметры команды

Источники запросов

Строка запроса

Файлы

REPL

Ведение журнала

Дополнительные ресурсы

Обратная связь

Дополнительные ресурсы