Cómo crear widgets en un notebook de Databricks: paso a paso

Los widgets de Databricks convierten un notebook estático en una herramienta reutilizable: en lugar de editar el código cada vez que cambia una fecha o una tabla, el usuario elige el valor en un campo en la parte superior del notebook. Esta parametrización es lo que separa un script desechable de un notebook listo para producción, y se vuelve esencial cuando lo ejecutas de forma automática en Jobs y Workflows. Los pasos siguientes muestran cómo crear widgets, leer sus valores y usarlos en una consulta real.

Requisitos previos

• Acceso a un workspace de Databricks (la Community Edition sirve para practicar).
• Un cluster activo conectado al notebook.
• Un notebook en Python — la API dbutils.widgets también existe en Scala, SQL y R.
• Nociones básicas de PySpark para el ejemplo final (opcional).

Paso 1: Crear un widget de texto

El tipo de widget más común es el de texto, ideal para valores libres como una fecha o el nombre de una tabla. Usa dbutils.widgets.text con tres argumentos: el nombre interno, el valor por defecto y la etiqueta que aparece en pantalla.

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

Al ejecutar la celda, aparece un cuadro de texto en la parte superior del notebook con la etiqueta "Data de início" y el valor por defecto ya rellenado. El valor por defecto es importante: garantiza que el notebook se ejecuta incluso antes de que alguien toque el widget.

Consejo: mantén el nombre interno corto y sin espacios (por ejemplo data_inicio). Ese es el nombre que usas en el código; el texto legible va en el tercer argumento.

Paso 2: Leer el valor del widget

Para usar lo que el usuario escribió, llama a dbutils.widgets.get con el nombre del widget. El valor devuelto es siempre una cadena, aunque parezca un número o una fecha — recuérdalo, porque es la causa de error más común. Es habitual colocar esta lectura al principio del notebook, para que todas las celdas siguientes usen el mismo valor.

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

Paso 3: Crear un widget de lista (dropdown)

Cuando solo tiene sentido elegir entre valores conocidos — por ejemplo, el entorno de ejecución — un dropdown evita errores de escritura. Pasa la lista de opciones válidas como cuarto argumento.

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

También existen los tipos combobox (una lista que además acepta texto libre) y multiselect (varias opciones a la vez). La lógica es siempre la misma: crear con un método, leer con get.

Paso 4: Usar el widget en una consulta

El objetivo de los widgets es alimentar el código. En el ejemplo siguiente leemos una tabla y filtramos las filas por la fecha elegida. Fíjate en que comparamos la columna con la cadena del widget — con fechas en formato ISO (AAAA-MM-DD) la comparación funciona directamente; en otros casos, haz el cast explícito.

from pyspark.sql.functions import col

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

Si prefieres SQL, puedes referenciar el widget directamente en una celda %sql con la sintaxis ${data_inicio}:

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

Paso 5: Eliminar widgets

Durante las pruebas es fácil acumular widgets antiguos que ya no usas. Elimínalos de uno en uno o bórralos todos con un solo comando. Limpiar los widgets al final mantiene el notebook ordenado y evita confusiones cuando lo compartes con colegas.

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

Verificar el resultado

Comprueba que la barra de widgets aparece en la parte superior del notebook con los campos "Data de início" y "Ambiente". Cambia la fecha, vuelve a ejecutar la celda del Paso 2 y observa cómo el print refleja el nuevo valor. Si usas el ejemplo del Paso 4, el número de filas devueltas debería variar según la fecha elegida. En el icono de ajustes de la barra de widgets también puedes elegir si el notebook se vuelve a ejecutar automáticamente cada vez que cambia un valor.

Conclusión

Con media docena de líneas has convertido un notebook rígido en una herramienta parametrizable y lista para producción: en Databricks Jobs y Workflows, los valores de los widgets pueden sobrescribirse con parámetros de la tarea, sin tocar el código. Recuerda la regla de oro — dbutils.widgets.get siempre devuelve texto, así que haz el cast a entero o fecha antes de hacer cálculos. ¿Cuál será el primer parámetro que extraigas de tu próximo notebook: la fecha, el entorno o el nombre de la tabla?