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

  • Статья

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

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

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

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

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

Типы мини-приложений Databricks

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

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

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

Widget in header

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

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

create widget dialog

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

widget tooltip

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

widget kebab menu

Использование мини-приложений Databricks в вычислительном кластере

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

API мини-приложения Databricks (кластер)

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

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

Пример мини-приложения Databricks (кластер)

Чтобы просмотреть подробную документацию по API для каждого метода, воспользуйтесь dbutils.widgets.help("<method-name>"). API справки идентичен на всех языках. Например:

dbutils.widgets.help("dropdown")

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

Python

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

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

Interact with widget

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

Python

dbutils.widgets.get("state")

SQL

SELECT "${state}"

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

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

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

Использование значений мини-приложений в Spark SQL (кластер)

Spark SQL обращается к значениям мини-приложения как к строковым литералам, которые можно использовать в запросах.

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

  1. Создайте мини-приложение с раскрывающимся списком всех баз данных в текущем каталоге:

    dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])

  2. Создайте текстовое мини-приложение, чтобы вручную указать имя таблицы:

    dbutils.widgets.text("table", "")

  3. Выполните SQL-запрос для просмотра всех таблиц в базе данных (выбранной в раскрывающемся списке):

    SHOW TABLES IN ${database}

  4. Вручную введите имя таблицы в мини-приложении table.

  5. Просмотрите содержимое таблицы, не изменяя содержимое запроса:

    SELECT *
FROM ${database}.${table}
LIMIT 100

Примечание.

Как правило, мини-приложения нельзя использовать для передачи аргументов между различными языками в записной книжке. Вы можете создать мини-приложение arg1 в ячейке Python и использовать его в ячейке SQL или Scala при одновременном запуске одной ячейки. Однако это не работает, если вы используете команду "Выполнить все" или запустить записную книжку в качестве задания.

Решения.

  • Для записных книжек, не смешивающих языки, можно создать записную книжку для каждого языка и передать аргументы при запуске записной книжки.
    • Вы можете получить доступ к мини-приложению spark.sql() с помощью вызова. Например, в Python: spark.sql("select getArgument('arg1')").take(1)[0][0]

Примечание.

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

Использование мини-приложений Databricks в хранилище SQL

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

Чтобы ссылаться на значения мини-приложений в хранилище SQL, используйте синтаксис :param, а не $param. Например, если у вас есть мини-приложение с именем fare_amount, используйте следующий код:

SELECT * FROM samples.nyctaxi.trips WHERE fare_amount < :fare_amount

IDENTIFIER Используйте ключевое слово для идентификации таких объектов, как таблицы, представления, схемы и столбцы. Например, если для мини-приложения с именем table_name задано samples.nyctaxi.tripsзначение :

SELECT * FROM IDENTIFIER(:table_name)

Дополнительные сведения см. в предложении IDENTIFIER.

Дополнительные сведения о синтаксисе маркера параметра см. в разделе "Маркеры параметров".

Настройка параметров мини-приложения

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

  1. gear icon Щелкните значок в правом конце панели мини-приложения.

  2. Во всплывающем диалоговом окне параметров на панели мини-приложения выберите поведение выполнения мини-приложения.

    Widget settings

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

  3. Чтобы закрепить мини-приложения в верхней части записной книжки или поместить мини-приложения над первой ячейкой, щелкните pin icon. Параметр сохраняется отдельно для каждого пользователя. Щелкните значок отпечатка еще раз, чтобы сбросить поведение по умолчанию.

  4. Если у вас есть разрешение CAN MANAGE для записных книжек, можно настроить макет мини-приложения, щелкнув edit icon. Порядок и размер каждого мини-приложения можно настроить. Чтобы сохранить или закрыть изменения, нажмите кнопку accept and cancel icons.

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

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

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

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

Widgets

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

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

Записная книжка с демонстрацией мини-приложения

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

Мини-приложения Databricks на панелях мониторинга

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

Dashboard with widgets

Использование мини-приложений Databricks с %run

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

Если записная книжка подключена к кластеру (т. е. не к хранилищу SQL), можно также передать значения в мини-приложения. Например:

%run /path/to/notebook $X="10" $Y="1"

В этом примере указанная записная книжка запускается и передает 10 в мини-приложение X и 1 в мини-приложение Y.

Ограничения

  • Следующие ограничения применяются к мини-приложениям:
    • В записной книжке можно создать не более 512 мини-приложений.
    • Имя мини-приложения ограничено 1024 символами.
    • Метка мини-приложения ограничена 2048 символами.
    • Максимум 2048 символов можно ввести в текстовое мини-приложение.
    • Для нескольких выборов, полей со списком или раскрывающегося списка может быть не более 1024.
  • Существует известная проблема, из-за которой состояние мини-приложения может неправильно очиститься после нажатия клавиши Run All, даже после очистки или удаления мини-приложения в коде. Если это произойдет, вы увидите несоответствие между визуальным состоянием мини-приложения и его печатным состоянием. Повторное выполнение ячеек по отдельности может обойти эту проблему. Чтобы полностью избежать этой проблемы, Databricks рекомендует использовать ipywidgets.