Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Notebooks and Jobs

Widgets and Parameters

Make Databricks notebooks reusable with widgets: text, dropdown and multiselect inputs, reading values with dbutils.widgets.get, SQL parameter markers and job parameters.

A notebook that has the date "2026-01-01" typed into its code is a script for one day. A notebook that reads the date from a widget is a tool you can run for any day, by hand or from a job. Widgets are the standard way to pass parameters into Databricks notebooks.

Databricks widgets cannot run on this site. The code is shown read-only; the runnable blocks are labelled stand-ins that reproduce the parameter logic (defaults, validation, overriding) in plain Python.

Creating widgets

Widgets appear in a bar at the top of the notebook. You create them in code, usually in the first cell.

Python
dbutils.widgets.text("run_date", "2026-01-01", "Run date")
dbutils.widgets.dropdown("env", "dev", ["dev", "test", "prod"], "Environment")
dbutils.widgets.multiselect("regions", "EU", ["EU", "US", "APAC"], "Regions")
dbutils.widgets.combobox("table", "orders", ["orders", "customers"], "Table")

Each call takes a name (used in code), a default value, optional choices, and an optional label shown to people. The four types:

Type Use it for
text Free text: dates, IDs, paths
dropdown One value from a fixed list
multiselect Several values (returned as one comma-separated string)
combobox A suggested list that also accepts typing

Reading values

Python
run_date = dbutils.widgets.get("run_date")
env = dbutils.widgets.get("env")
regions = dbutils.widgets.get("regions").split(",")

df = spark.read.table(f"main_{env}.sales.orders").where(f"order_date = '{run_date}'")

Every widget value is a string. Convert it yourself (int(...), date.fromisoformat(...)) and validate it. To remove widgets, use dbutils.widgets.remove("name") or dbutils.widgets.removeAll().

Do not build SQL by pasting a widget value into a string that users can influence. Prefer parameter markers (below) so the value is treated as data, never as SQL text.

Parameter markers in SQL

Modern Databricks SQL cells and spark.sql accept named markers that are bound to values:

Python
spark.sql(
    "SELECT * FROM main.sales.orders WHERE order_date = :day AND region = :region",
    args={"day": run_date, "region": "EU"},
)

In a SQL cell, a widget named run_date can be used as :run_date. The marker is bound as a typed value, which also protects against SQL injection.

Parameters from jobs

When a notebook runs as a task in a job (see Jobs and Schedules), the job passes parameters by widget name. If the job sets run_date = 2026-02-14, then dbutils.widgets.get("run_date") returns that string and the default is ignored. Calling one notebook from another uses the same mechanism:

Python
result = dbutils.notebook.run("load_orders", 900, {"run_date": "2026-02-14"})

The second argument is a timeout in seconds; the child can hand back a string with dbutils.notebook.exit("ok: 120 rows").

Jobs can also pass dynamic value references, written with double braces, such as {{job.start_time.iso_date}} or {{tasks.extract.values.rows}}. They are resolved when the run starts, so one job definition can process "today".

A parameter layer you can test

The key habit: put parsing and validation in a plain function so it can be tested outside Databricks. The stand-in below mimics a widget store with defaults and overrides (what a job does).

Python Stand-in: widgets with defaults and job overrides

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Parameterised queries, safely

The next stand-in shows why markers matter, using Python's built-in sqlite3, which has the same bound-parameter idea. It is not Spark SQL.

Python Stand-in: bound parameters vs string pasting

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical tips

  • Give every widget a sensible default so the notebook works when opened by hand.
  • Use dropdowns for environments, so a typo cannot select a table that does not exist.
  • Print the resolved parameters at the top of a job run; it makes logs self-explanatory.
  • Keep widget names identical to job parameter names.
  • For many parameters, read them once into a dictionary or dataclass and pass that around.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What type does dbutils.widgets.get always return?

    All widget values are strings; convert and validate them yourself.
  2. 2. A job passes run_date=2026-02-14 to a notebook whose widget default is 2026-01-01. Which value does the notebook read?

    Job parameters override the widget default.
  3. 3. Why use :name parameter markers instead of f-strings in SQL?

    A bound value can never change the structure of the statement.
  4. 4. How does a multiselect widget return its value?

    Split it yourself, for example with .split(',').

Summary

  • Widgets (text, dropdown, multiselect, combobox) turn a notebook into a reusable tool.
  • Values are strings; parse and validate them in one function.
  • Jobs override widget defaults by name; dbutils.notebook.run does the same for child notebooks.
  • Use bound parameter markers instead of building SQL strings.

Next: Jobs and Schedules