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

Статья
2025-03-28

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

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

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

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

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

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

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списке.

Питон

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

язык программирования Scala

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

Р

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"))

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

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

Питон

dbutils.widgets.get("state")

dbutils.widgets.getAll()

язык программирования Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Р

dbutils.widgets.get("state")

SQL

SELECT :state

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

Питон

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

язык программирования Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

Р

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

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

Виджеты Spark SQL и SQL Warehouse используют значения с помощью маркеров параметров . Маркеры параметров защищают код от атак внедрения 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
```

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

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

Питон

 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")

Р

 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 (Запускать записную книжку). При каждом выборе нового значения вся записная книжка будет перезапускаться.
- Запуск доступных команд. При каждом выборе нового значения повторно выполняются только ячейки, которые извлекают значения для этого конкретного виджета. Это параметр по умолчанию при создании мини-приложения. В этой конфигурации ячейки SQL не перезапускаются.
- Ничего не делать. При каждом выборе нового значения никакие процессы не перезапускаются.
Чтобы закрепить мини-приложения в верхней части записной книжки или поместить мини-приложения над первой ячейкой, щелкните . Параметр сохраняется отдельно для каждого пользователя. Щелкните значок кнопки еще раз, чтобы сбросить настройки по умолчанию.
Если у вас есть разрешение CAN MANAGE для записных книжек, можно настроить макет мини-приложения, щелкнув . Можно настроить порядок и размер каждого виджета. Чтобы сохранить или закрыть изменения, нажмите кнопку .

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