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 the call:

dbutils.widgets.get("X")

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

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

Widgets in Scala, Python, and 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 the choices in a dropdown widget in SQL you can write a sub-query. The first column of the resulting table of the sub-query will determine the choices.

The following cell creates a temporary table in R that we use to create a dropdown widget in SQL.

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

The default value specified when creating dropdown widgets must be one of the choices, and must be specified as a string literal. 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")

Finally you can remove the widget 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 when a new value is selected.

Widget Settings
Run Notebook
Every time a new value is selected, the entire notebook is rerun.
Run Accessed Commands

Every time a new value is selected, 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 new value is selected, nothing is rerun. This is the default setting when you create a widget.

You can see a demo of how the Run Accessed Commands setting works in the following notebook. The year widget is created with setting 2014 and is used in DataFrame API and SQL commands.

Widgets

When you change the setting of the year widget to 2007, the DataFrame command reruns, but the SQL command is not 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.