Мини-приложения Databricks

Статья
06/28/2024

Мини-приложения для ввода, позволяющие добавлять параметры в записные книжки и на панели мониторинга. Вы можете добавить мини-приложение из пользовательского интерфейса Databricks или с помощью API мини-приложения. Чтобы добавить или изменить мини-приложение, необходимо иметь разрешения CAN EDIT в записной книжке.

Если вы используете Databricks Runtime 11.3 LTS или более поздней версии, вы также можете использовать ipywidgets в записных книжках Databricks.

Мини-приложения Databricks лучше всего подходят для следующих целей:

Создание записной книжки или панели мониторинга, которая выполняется повторно с разными параметрами.
Быстро просматривайте результаты одного запроса с разными параметрами.

Чтобы просмотреть документацию по API мини-приложений в Scala, Python или R, используйте следующую команду: dbutils.widgets.help()

Есть четыре типа мини-приложений:

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

Раскрывающиеся списки мини-приложений и текстовые поля отображаются сразу после панели инструментов записной книжки. Мини-приложения принимают только строковые значения.

Создание мини-приложений

В этом разделе показано, как создавать мини-приложения с помощью пользовательского интерфейса или программно с помощью магии SQL или API мини-приложений для Python, Scala и R.

Создание мини-приложений с помощью пользовательского интерфейса

Создайте мини-приложение с помощью пользовательского интерфейса записной книжки. Если вы подключены к хранилищу SQL, это единственный способ создания мини-приложений.

Выберите "Изменить > мини-приложение". В диалоговом окне "Добавление мини-приложения" введите имя мини-приложения, необязательную метку, тип, тип параметра, возможные значения и необязательное значение по умолчанию. В диалоговом окне имя параметра — это имя, которое вы используете для ссылки на мини-приложение в коде. Метка мини-приложения — это необязательное имя, которое отображается над мини-приложением в пользовательском интерфейсе.

После создания мини-приложения можно навести указатель мыши на имя мини-приложения, чтобы отобразить подсказку, описывающую ссылку на мини-приложение.

Для редактирования или удаления мини-приложения можно использовать меню кебаб:

Создание мини-приложений с помощью SQL, Python, R и Scala

Программное создание мини-приложений в записной книжке, подключенной к вычислительному кластеру.

API мини-приложения предназначен для согласованности в Scala, Python и R. API мини-приложения в SQL немного отличается, но эквивалентен другим языкам. Вы управляете мини-приложениями с помощью эталонного интерфейса Databricks Utilities (dbutils).

Первым аргументом для всех типов мини-приложений является name. Это имя, которое вы используете для доступа к мини-приложению.
Второй аргумент — это defaultValueпараметр по умолчанию мини-приложения.
Третий аргумент для всех типов мини-приложений (кроме text) — choicesэто список значений, которые может взять на себя мини-приложение. Этот аргумент не используется для text мини-приложений типов.
Последним аргументом является необязательное значение метки, отображаемой в текстовом поле мини-приложения или раскрывающемся labelсписке.

Python

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

Scala

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

R

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

SQL

CREATE WIDGET DROPDOWN state DEFAULT "CA" CHOICES SELECT * FROM (VALUES ("CA"), ("IL"), ("MI"), ("NY"), ("OR"), ("VA"))

Взаимодействуйте с мини-приложением с помощью панели мини-приложения.

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

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Наконец, вы можете удалить мини-приложение или все мини-приложения в записной книжке:

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

Если вы удалите мини-приложение, его нельзя создать в одной ячейке. Мини-приложение необходимо создать в другой ячейке.

Значения мини-приложений доступа к хранилищу SQL и Spark SQL с помощью маркеров параметров. Маркеры параметров защищают код от атак внедрения SQL, четко разделяя предоставленные значения от инструкций SQL.

Маркеры параметров для мини-приложений доступны в Databricks Runtime 15.2 и выше. Предыдущие версии Databricks Runtime должны использовать старый синтаксис для DBR 15.1 и ниже.

При интерактивном выполнении записных книжек из Spark SQL можно обращаться к мини-приложениям, определенным на любом языке. Рабочий процесс состоит из следующих шагов:

Создайте мини-приложение с раскрывающимся списком всех баз данных в текущем каталоге:
```
dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])
```
Создайте текстовое мини-приложение, чтобы вручную указать имя таблицы:
```
dbutils.widgets.text("table", "")
```
Выполните SQL-запрос для просмотра всех таблиц в базе данных (выбранной в раскрывающемся списке):
```
SHOW TABLES IN IDENTIFIER(:database)
```
Примечание.

Необходимо использовать предложение SQL IDENTIFIER() для анализа строк в качестве идентификаторов объектов для баз данных, таблиц, представлений, функций, столбцов и полей.
Вручную введите имя таблицы в мини-приложении table.
Создайте текстовое мини-приложение, чтобы указать значение фильтра:
```
dbutils.widgets.text("filter_value", "")
```
Просмотрите содержимое таблицы, не изменяя содержимое запроса:
```
SELECT *
FROM IDENTIFIER(:database || '.' || :table)
WHERE col == :filter_value
LIMIT 100
```

В этом разделе описывается передача значений %sql мини-приложений Databricks в ячейки записной книжки в Databricks Runtime 15.1 и ниже.

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

Python

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

Scala

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

R

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

SQL

 CREATE WIDGET TEXT database DEFAULT ""
 CREATE WIDGET TEXT table DEFAULT ""
 CREATE WIDGET TEXT filter_value DEFAULT "100"

Передайте значения мини-приложения с помощью синтаксиса ${param} .
```
SELECT *
FROM ${database}.${table}
WHERE col == ${filter_value}
LIMIT 100
```

Примечание.

Экранировать символ $ в строковом литерале SQL можно с помощью \$. Например, чтобы выразить строку $1,000, используйте "\$1,000". Символ $ нельзя экранировать для идентификаторов SQL.

Вы можете настраивать поведение мини-приложений при выборе нового значения, независимо от того, будет ли панель мини-приложения всегда закреплена в верхней части записной книжки, и изменять макет мини-приложений в записной книжке.

Щелкните значок в правом конце панели мини-приложения.
Во всплывающем диалоговом окне параметров на панели мини-приложения выберите поведение выполнения мини-приложения.
- Run Notebook (Запускать записную книжку). При каждом выборе нового значения вся записная книжка будет перезапускаться.
- Run Accessed Commands (Выполнять команды, к которым осуществлялся доступ). При каждом выборе нового значения будут перезапускаться только ячейки, которые получают значения для этого конкретного мини-приложения. Это параметр по умолчанию при создании мини-приложения. В этой конфигурации ячейки SQL не перезапускаются.
- Действие не требуется. При каждом выборе нового значения перезапуск не выполняется.
Чтобы закрепить мини-приложения в верхней части записной книжки или поместить мини-приложения над первой ячейкой, щелкните . Параметр сохраняется отдельно для каждого пользователя. Щелкните значок отпечатка еще раз, чтобы сбросить поведение по умолчанию.
Если у вас есть разрешение CAN MANAGE для записных книжек, можно настроить макет мини-приложения, щелкнув . Порядок и размер каждого мини-приложения можно настроить. Чтобы сохранить или закрыть изменения, нажмите кнопку .

Макет мини-приложения сохраняется вместе с записной книжкой. Если изменить макет мини-приложения из конфигурации по умолчанию, новые мини-приложения не добавляются в алфавитном порядке.
Чтобы сбросить макет мини-приложения в порядок и размер по умолчанию, щелкните диалоговое окно "Параметры панели мини-приложений" и нажмите кнопку "Сбросить макет". Команда removeAll() не сбрасывает макет мини-приложения.

Пример записной книжки

В следующей записной книжке показано, как работает параметр запускаемых команд . Мини-приложение year создается с параметром 2014 и используется в командах API кадра данных и SQL.

При изменении параметра мини-приложения year на 2007 происходит повторная попытка выполнить команду кадра данных, но команда SQL не выполняется повторно.

Эта записная книжка иллюстрирует использование мини-приложений в записной книжке, подключенной к кластеру, а не в хранилище SQL.

Получить записную книжку