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
View the documentation for the widget API in Scala, Python, and R with the following command:
There are 4 types of widgets:
- Input a value in a text box.
- Select a value from a list of provided values.
- Combination of text and dropdown. Select a value from a provided list or input one in the text box.
- Select 1 or more values from a list of provided values.
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")
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:
Finally you can remove a widget or all widgets in a notebook:
To see detailed API documentation for each method use
dbutils.widgets.help("<method-name>"). The help API is identical in all languages. For example:
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.
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
You can configure the execution behavior of widgets. Widget settings are accessible on the right end of the Widget bar via the icon.
In the pop-up Settings dialog box, you can choose the widget’s execution behavior when a new value is selected.
- 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.
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.
When you change the setting of the
year widget to
2007, the DataFrame command reruns, but the SQL command is not rerun.
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.
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.