Widgets

Input widgets allow you to add parameters to your notebooks and dashboards. The widget API consists of calls to create different types of input widgets, remove them, and get bound values.

Widgets are best for:

  • Building a notebook or dashboard that is re-executed with different parameters
  • Quickly exploring results of a single query with different parameters

Tip

View the documentation for the widget API in Scala, Python, and R with the following command:

dbutils.widgets.help()

Widget types

There are 4 types of widgets:

  • text - Input a value in a text box.
  • dropdown - Select a value from a list of provided values.
  • combobox - Combination of text and dropdown. Select a value from a provided list or input one in the text box.
  • multiselect - Select 1 or more values from a list of provided values.

Widget API

The widget API is designed to be consistent in Scala, Python, and R. The widget API in SQL is slightly different, but as powerful as the other languages. You manage widgets through the Databricks Utilities interface.

dbutils.widgets.dropdown("X123", "1", [str(x) for x in range(1, 10)])
dbutils.widgets.dropdown("1", "1", [str(x) for x in range(1, 10)], "hello this is a widget")
dbutils.widgets.dropdown("x123123", "1", [str(x) for x in range(1, 10)], "hello this is a widget")
dbutils.widgets.dropdown("x1232133123", "1", [str(x) for x in range(1, 10)], "hello this is a widget 2")

Widget example

Let’s create a simple dropdown widget.

dbutils.widgets.dropdown("X", "1", [str(x) for x in range(1, 10)])

Now you can interact with the widget on the top bar. You can access the current value of the widget with following call

dbutils.widgets.get("X")

Finally you can remove your widget (or all widgets in a notebook):

dbutils.widgets.remove("X")
dbutils.widgets.removeAll()

Widgets in Scala/Python/R

To see detailed API documentation for each method use dbutils.widgets.help("<method-name>"). The help API is identical in all languages. For example:

dbutils.widgets.help("dropdown")

You can create a dropdown widget by passing a unique identifying name, default value, and list of default choices and an optional label. Once created, a dropdown input widget appears at the top of the notebook. These input widgets are notebook-level entities.

If you try to create a widget that already exists, the configuration of the widget is overwritten with the new options.

Widgets in SQL

The API to create widgets in SQL is as powerful as other languages. Following is an example of creating a text input widget.

CREATE WIDGET TEXT y DEFAULT "10"

To specify default values of dropdown widgets in SQL you can write a subquery. The first column of the resulting table of the sub-query will determine default choices.

In the following cell, we first create a temporary table in R and then we use it to create a dropdown widget in SQL.

CREATE WIDGET DROPDOWN cuts DEFAULT "Good" CHOICES select distinct cut from diamonds

Note that the default value specified when creating dropdown widgets must be one of the default choices. To access the current selected value of an input widget in SQL you can use a special UDF function in your query. The function is getArgument(). For example:

select count(*) as numChoices, getArgument("cuts") as cuts from diamonds where cut = getArgument("cuts")

And finally we can remove the widgets we have created with a SQL command:

REMOVE WIDGET cuts

Legacy input widgets in SQL

The old way of creating SQL queries still works as before. Here is an example:

select * from diamonds where cut like '%$cuts%'

Configure widget settings

You can configure the execution behavior of widgets. Widget settings are accessible on the right end of the Widget bar via the gear icon.

In the pop-up Settings dialog box, you can choose the widget’s execution behavior.

Widget Settings
Run Notebook
Every time a user selects a new value through the widget, the entire notebook is rerun.
Run Accessed Commands

Every time a user selects the widget, only cells that retrieve the values for that particular widget are rerun.

Note

SQL cells are not rerun in this configuration.

Do Nothing
Every time a user selects the widget, nothing is rerun.

Widgets in dashboards

When you create a dashboard from a notebook that has input widgets, all the widgets display at the top of the dashboard. In presentation mode, every time you update value of a widget you can click the Update button to re-run the notebook and update your dashboard with new values.

Dashboard with Widgets

Use widgets with %run

If you run a notebook that contains widgets, the specified notebook is run with the widget’s default values. You can also pass in values to widgets. For example:

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

This example runs the specified notebook and passes 10 into widget X and 1 into widget Y.