Como criar widgets num notebook Databricks: passo a passo

Os widgets do Databricks permitem transformar um notebook fixo numa ferramenta reutilizável: em vez de editar o código sempre que muda uma data ou uma tabela, o utilizador escolhe o valor num campo no topo do notebook. Esta parametrização é o que separa um script descartável de um notebook pronto para produção e torna-se indispensável quando o executa de forma automática em Jobs e Workflows. Os passos seguintes mostram como criar widgets, ler os seus valores e usá-los numa consulta real.

Pré-requisitos

• Acesso a um workspace Databricks (a Community Edition serve para praticar).
• Um cluster ativo ligado ao notebook.
• Um notebook em Python — a API dbutils.widgets também existe em Scala, SQL e R.
• Noções básicas de PySpark para o exemplo final (opcional).

Passo 1: Criar um widget de texto

O tipo de widget mais comum é o de texto, ideal para valores livres como uma data ou o nome de uma tabela. Use dbutils.widgets.text com três argumentos: o nome interno, o valor por omissão e a etiqueta que aparece no ecrã.

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

Ao executar a célula, surge uma caixa de texto no topo do notebook com a etiqueta "Data de início" e o valor por omissão já preenchido. O valor por omissão é importante: garante que o notebook corre mesmo antes de alguém tocar no widget.

Dica: mantenha o nome interno curto e sem espaços (por exemplo data_inicio). É esse nome que usa no código; o texto legível fica no terceiro argumento.

Passo 2: Ler o valor do widget

Para usar o que o utilizador escreveu, chame dbutils.widgets.get com o nome do widget. O valor devolvido é sempre uma string, mesmo que pareça um número ou uma data — guarde esta ideia, porque é a causa de erro mais comum. É habitual colocar esta leitura logo no início do notebook, para que todas as células seguintes usem o mesmo valor.

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

Passo 3: Criar um widget de lista (dropdown)

Quando só faz sentido escolher entre valores conhecidos — por exemplo, o ambiente de execução — um dropdown evita erros de escrita. Passe a lista de opções válidas no quarto argumento.

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

Existem ainda os tipos combobox (lista com escrita livre) e multiselect (várias opções em simultâneo). A lógica é sempre a mesma: criar com um método, ler com get.

Passo 4: Usar o widget numa consulta

O objetivo dos widgets é alimentar o código. No exemplo seguinte lemos uma tabela e filtramos as linhas pela data escolhida. Repare que comparamos a coluna com a string do widget — em datas no formato ISO (AAAA-MM-DD) a comparação funciona diretamente; noutros casos, faça o cast explícito.

from pyspark.sql.functions import col

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

Se preferir SQL, pode referir o widget diretamente numa célula %sql com a sintaxe ${data_inicio}:

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

Passo 5: Remover widgets

Durante os testes é fácil acumular widgets antigos que já não usa. Remova um de cada vez ou limpe todos com um único comando. Limpar os widgets no fim mantém o notebook arrumado e evita confusões quando o partilha com colegas.

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

Verificar o resultado

Confirme que a barra de widgets aparece no topo do notebook com os campos "Data de início" e "Ambiente". Mude a data, volte a executar a célula do Passo 2 e veja o print refletir o novo valor. Se usar o exemplo do Passo 4, o número de linhas devolvidas deve variar conforme a data escolhida. No ícone de definições da barra de widgets pode ainda escolher se o notebook re-executa automaticamente sempre que um valor muda.

Conclusão

Com meia dúzia de linhas transformou um notebook rígido numa ferramenta parametrizável e pronta para produção: em Databricks Jobs e Workflows, os valores dos widgets podem ser sobrepostos por parâmetros da tarefa, sem tocar no código. Guarde a regra de ouro — dbutils.widgets.get devolve sempre texto, por isso faça o cast para inteiro ou data antes de cálculos. Qual vai ser o primeiro parâmetro que extrai do seu próximo notebook: a data, o ambiente, ou o nome da tabela?