Notebook Widgets: Adding Interactive Parameters
Notebook widgets add interactive input controls — text boxes, dropdowns, comboboxes, and multiselects — to the top of a Databricks notebook, letting users parameterise execution without editing code. Widgets make notebooks reusable across different datasets, date ranges, and configurations, and their values can be passed as parameters when scheduling notebooks as jobs.
- Create and use the four widget types: text, dropdown, combobox, and multiselect
- Access widget values in Python, SQL, Scala, and R
- Pass widget values as job parameters for scheduled execution
Who this is for: Data engineers and analysts who build reusable, parameterised notebooks for both interactive and scheduled use.
Part of the Databricks Notebooks section of the Databricks tutorial series.
Architecture / Concept Overview: Notebook Widgets: Adding Interactive Parameters
Widgets are registered with the notebook session via dbutils.widgets and rendered as interactive controls in the notebook header. When a cell references a widget value, it reads the current selection at execution time. This lets users re-run the same notebook with different inputs without modifying code. In scheduled jobs, widget values are populated from base_parameters in the job configuration.
*Widgets render in the notebook header, accept user input, and provide values to code at execution time.*
*Four widget types serve different input patterns: free text, single select, type-or-select, and multi-select.*
*Widgets accept values from interactive UI input or from job parameters in scheduled execution.*
Key Terms
- Widget
- An interactive input control rendered in the notebook header for parameterising execution.
- Text Widget
- A free-form text input for arbitrary string values.
- Dropdown Widget
- A single-select list of predefined choices.
- Combobox Widget
- A text input with autocomplete suggestions from a predefined list.
- Multiselect Widget
- A multi-select list allowing multiple choices.
dbutils.widgets- The API for creating, reading, and removing notebook widgets.
Prerequisites and Setup
- A Databricks notebook attached to compute
- Understanding of the parameters your notebook needs
- For scheduled use: a job definition with
base_parametersmatching widget names - Python, SQL, Scala, or R familiarity
Step-by-Step Implementation
Configuration Reference
| Widget Type | Method | Use Case | Input Style |
|---|---|---|---|
| Text | dbutils.widgets.text() | Dates, IDs, free-form input | Text field |
| Dropdown | dbutils.widgets.dropdown() | Fixed list of options | Single select |
| Combobox | dbutils.widgets.combobox() | Suggested options with custom input | Type or select |
| Multiselect | dbutils.widgets.multiselect() | Multiple selections | Checkboxes |
| Get value | dbutils.widgets.get("name") | Read current value | N/A |
| Remove | dbutils.widgets.remove("name") | Clean up | N/A |
| Remove all | dbutils.widgets.removeAll() | Reset all widgets | N/A |
Monitoring, Cost, and Security Considerations
Monitoring
Widget values are logged in job run parameters, providing an audit trail of what inputs were used for each execution. Review job run history to see which parameter combinations were used.
Cost Optimisation
- Widgets enable one notebook to serve multiple use cases, reducing notebook sprawl and maintenance overhead.
- Use widgets with dropdown constraints to prevent users from selecting overly broad date ranges or resource-intensive configurations.
- Test with small data ranges before running full production parameters.
Security and Governance
- Widget values are strings; always validate and sanitise inputs before using them in SQL queries to prevent injection.
- Use parameterised queries or Spark's built-in parameter binding instead of string interpolation where possible.
- Widget values in job parameters are visible to anyone with job read access.
Common Pitfalls and Recommended Patterns
- Using string interpolation for SQL with widget values: this is vulnerable to SQL injection; use
getArgument()in SQL or parameterised queries. - Creating widgets in the middle of the notebook: place all widget definitions at the top for clarity.
- Forgetting default values: always set meaningful defaults so the notebook works without manual input.
- Not validating widget inputs: add validation cells that check widget values before processing.
- Over-parameterising: too many widgets make notebooks confusing; keep to 3-5 essential parameters.
- Not documenting widget purposes: add a markdown cell explaining what each parameter controls.
Frequently Asked Questions
Do widget values persist between sessions?
Widget definitions persist in the notebook, and default values are restored when a new session starts. User-selected values persist only during the active session.
Can I dynamically populate dropdown options?
Yes. Query a table to get the list of options, then pass the result to dbutils.widgets.dropdown(). The options update when the cell is re-run.
How do widgets work with scheduled jobs?
Job base_parameters map directly to widget names. When the job runs, dbutils.widgets.get("param") returns the job parameter value instead of the UI default.
Can I use widgets in SQL-only notebooks?
Yes. Use getArgument('widget_name') or :widget_name syntax to reference widget values in SQL cells.