How to create widgets in a Databricks notebook: step by step

Databricks widgets turn a static notebook into a reusable tool: instead of editing the code every time a date or a table changes, the user picks the value in a field at the top of the notebook. This parameterization is what separates a throwaway script from a production-ready notebook, and it becomes essential when you run it automatically in Jobs and Workflows. The steps below show how to create widgets, read their values, and use them in a real query.

Prerequisites

• Access to a Databricks workspace (the Community Edition is fine for practice).
• An active cluster attached to the notebook.
• A Python notebook — the dbutils.widgets API also exists in Scala, SQL, and R.
• Basic PySpark knowledge for the final example (optional).

Step 1: Create a text widget

The most common widget type is text, ideal for free values such as a date or a table name. Use dbutils.widgets.text with three arguments: the internal name, the default value, and the label shown on screen.

dbutils.widgets.text("data_inicio", "2026-01-01", "Data de início")

When you run the cell, a text box appears at the top of the notebook with the "Data de início" label and the default value already filled in. The default value matters: it ensures the notebook runs even before anyone touches the widget.

Tip: keep the internal name short and space-free (for example data_inicio). That is the name you use in code; the readable text goes in the third argument.

Step 2: Read the widget value

To use what the user typed, call dbutils.widgets.get with the widget name. The returned value is always a string, even if it looks like a number or a date — remember this, because it is the most common source of errors. It is common to place this read right at the top of the notebook so that every later cell uses the same value.

data_inicio = dbutils.widgets.get("data_inicio")
print(f"Vou filtrar a partir de {data_inicio}")

Step 3: Create a list widget (dropdown)

When it only makes sense to choose among known values — for example, the runtime environment — a dropdown prevents typos. Pass the list of valid options as the fourth argument.

dbutils.widgets.dropdown("ambiente", "dev", ["dev", "teste", "producao"], "Ambiente")
ambiente = dbutils.widgets.get("ambiente")

There are also the combobox (a list that also accepts free text) and multiselect (several options at once) types. The logic is always the same: create with a method, read with get.

Step 4: Use the widget in a query

The whole point of widgets is to feed the code. In the example below we read a table and filter the rows by the chosen date. Note that we compare the column with the widget string — for ISO dates (YYYY-MM-DD) the comparison works directly; in other cases, cast explicitly.

from pyspark.sql.functions import col

df = spark.read.table("vendas")
resultado = df.filter(col("data_venda") >= data_inicio)
display(resultado)

If you prefer SQL, you can reference the widget directly in a %sql cell using the ${data_inicio} syntax:

%sql
SELECT * FROM vendas WHERE data_venda >= '${data_inicio}'

Step 5: Remove widgets

During testing it is easy to accumulate old widgets you no longer use. Remove them one at a time or clear them all with a single command. Cleaning up the widgets at the end keeps the notebook tidy and avoids confusion when you share it with colleagues.

dbutils.widgets.remove("ambiente")   # remove apenas um
dbutils.widgets.removeAll()          # remove todos

Verify the result

Confirm that the widget bar appears at the top of the notebook with the "Data de início" and "Ambiente" fields. Change the date, run the Step 2 cell again, and watch the print reflect the new value. If you use the Step 4 example, the number of returned rows should vary with the chosen date. In the widget bar settings icon you can also choose whether the notebook re-runs automatically whenever a value changes.

Conclusion

With half a dozen lines you turned a rigid notebook into a parameterizable, production-ready tool: in Databricks Jobs and Workflows, widget values can be overridden by task parameters without touching the code. Keep the golden rule — dbutils.widgets.get always returns text, so cast to integer or date before doing calculations. What will be the first parameter you extract from your next notebook: the date, the environment, or the table name?