Databricks SQL CLI

Статья
05/14/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. Маркеры идентификатора Microsoft Entra (ранее — Azure Active Directory) не поддерживаются.

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

В рабочей области Azure Databricks щелкните имя пользователя Azure Databricks в верхней строке и выберите Параметры в раскрывающемся списке.
Щелкните "Разработчик".
Рядом с маркерами доступа нажмите кнопку "Управление".
Щелкните Generate new token (Создание нового маркера).
(Необязательно) Введите комментарий, который поможет определить этот маркер в будущем и изменить время существования маркера по умолчанию в течение 90 дней. Чтобы создать маркер без времени существования (не рекомендуется), оставьте поле время существования (дни) пустым (пустым).
Щелкните Создать.
Скопируйте отображаемый маркер в безопасное расположение и нажмите кнопку "Готово".

Примечание.

Не забудьте сохранить скопированный маркер в безопасном расположении. Не делитесь скопированным маркером с другими пользователями. Если вы потеряете скопированный маркер, вы не сможете повторно создать тот же маркер. Вместо этого необходимо повторить эту процедуру, чтобы создать новый маркер. Если вы потеряете скопированный маркер или считаете, что маркер скомпрометирован, Databricks настоятельно рекомендует немедленно удалить этот маркер из рабочей области, щелкнув значок корзины (отозвать) рядом с маркером на странице маркеров доступа.

Если вы не можете создавать или использовать маркеры в рабочей области, это может быть связано с тем, что администратор рабочей области отключил маркеры или не предоставил вам разрешение на создание или использование маркеров. Обратитесь к администратору рабочей области или следующему:

Эти сведения проверки подлинности можно указать в интерфейсе командной строки 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

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

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

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

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

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