Widgets do Databricks

Artigo
12/03/2024

Os widgets de entrada permitem adicionar parâmetros aos seus notebooks e painéis. Você pode adicionar um widget da interface do usuário do Databricks ou usando a API do widget. Para adicionar ou editar um widget, você precisa ter as permissões PODE EDITAR no notebook.

Se você estiver executando o Databricks Runtime 11.3 ou superior, também poderá usar ipywidgets em notebooks do Databricks.

Os widgets do Databricks são melhores para:

Compilar um notebook ou um painel que é executado novamente com parâmetros diferentes.
Explorar rapidamente os resultados de uma única consulta com parâmetros diferentes.

Para exibir a documentação da API do widget em Scala, Python ou R, use o seguinte comando: dbutils.widgets.help(). Você também pode consultar a documentação do utilitário widgets (dbutils.widgets).

Há quatro tipos de widgets:

text: Insira um valor em uma caixa de texto.
dropdown: Selecione um valor de uma lista de valores fornecidos.
combobox: Combinação de texto e lista suspensa. Selecione um valor de uma lista fornecida ou insira um na caixa de texto.
multiselect: Selecione um ou mais valores de uma lista de valores fornecidos.

As listas suspensas e caixas de texto do widget aparecem imediatamente após a barra de ferramentas do notebook. Os widgets aceitam apenas valores de cadeia de caracteres.

Criar widgets

Esta seção mostra como criar widgets usando a interface do usuário ou programaticamente usando SQL magics ou a API de widget para Python, Scala e R.

Crie widgets usando a interface do usuário

Crie um widget usando a interface do usuário do notebook. Se você estiver conectado a um armazém de dados SQL, esta é a única maneira de criar widgets.

Selecione Editar > Adicionar widget. Na caixa de diálogo Adicionar widget, insira o nome do widget, o rótulo opcional, o tipo, o tipo de parâmetro, os valores possíveis e o valor padrão opcional. Na caixa de diálogo, Nome do Parâmetro é o nome que você usa para fazer referência ao widget em seu código. Rótulo de Widget é um nome opcional que aparece no widget na interface do usuário.

Depois de criar um widget, você pode passar o mouse sobre o nome do widget para exibir uma dica de ferramenta que descreve como referenciá-lo.

Você pode usar o menu kebab para editar ou remover o widget:

Crie widgets com SQL, Python, R e Scala

Crie widgets programaticamente em um notebook conectado a um cluster de computação.

A API do widget foi projetada para ser consistente em Scala, Python e R. A API do widget no SQL é um pouco diferente, mas equivalente a outras linguagens. Você gerencia os widgets por meio da interface de referência dos Utilitários do Databricks (dbutils).

O primeiro argumento para todos os tipos de widget é name. Esse é o nome que você usa para acessar o widget.
O segundo argumento é defaultValue, a configuração padrão do widget.
O terceiro argumento para todos os tipos de widget, exceto para text é choices, uma lista de valores que o widget pode assumir. Esse argumento não é usado para widgets de tipo text.
O último argumento é label, um valor opcional para o rótulo mostrado na caixa de texto ou na lista suspensa do widget.

Python

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

Scala

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

R

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

SQL

CREATE WIDGET DROPDOWN state DEFAULT "CA" CHOICES SELECT * FROM (VALUES ("CA"), ("IL"), ("MI"), ("NY"), ("OR"), ("VA"))

Interaja com o widget no painel de widget.

Você pode acessar o valor atual do widget ou obter um mapeamento de todos os widgets:

Python

dbutils.widgets.get("state")

dbutils.widgets.getAll()

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Por fim, você pode remover um widget ou todos os widgets em um notebook:

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

Se você remover um widget, não poderá criar um na mesma célula. Você deve criar o widget em outra célula.

Spark SQL e SQL Warehouse acessam os valores do widget usando marcadores de parâmetros. Os marcadores de parâmetros protegem seu código contra ataques de injeção SQL ao separar claramente os valores fornecidos das instruções SQL.

Os marcadores de parâmetros para widgets estão disponíveis no Databricks Runtime 15.2 e superior. Versões anteriores do Databricks Runtime devem usar a sintaxe antiga para DBR 15.1 e abaixo.

Você pode acessar widgets definidos em qualquer idioma do Spark SQL durante a execução interativa de notebooks. Considere o seguinte fluxo de trabalho:

Crie um widget de lista suspensa de todos os bancos de dados no catálogo atual:

dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])

Crie um widget de texto para especificar manualmente um nome de tabela:
```
dbutils.widgets.text("table", "")
```
Execute uma consulta SQL para ver todas as tabelas em um banco de dados (selecionados na lista suspensa):
```
SHOW TABLES IN IDENTIFIER(:database)
```
Observação

Você deve usar a cláusula IDENTIFIER() SQL para analisar strings como identificadores de objeto, como nomes de bancos de dados, tabelas, visualizações, funções, colunas e campos.
Insira manualmente um nome de tabela no widget table.
Crie um widget de texto para especificar um valor de filtro:
```
dbutils.widgets.text("filter_value", "")
```

Visualize o conteúdo de uma tabela sem a necessidade de editar o conteúdo da consulta:

SELECT *
FROM IDENTIFIER(:database || '.' || :table)
WHERE col == :filter_value
LIMIT 100

Esta seção descreve como passar os valores dos widgets do Databricks para células do %sql notebook no Databricks Runtime 15.1 e versões anteriores.

Crie widgets para especificar valores de texto.

Python

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

Scala

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

R

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

SQL

 CREATE WIDGET TEXT database DEFAULT ""
 CREATE WIDGET TEXT table DEFAULT ""
 CREATE WIDGET TEXT filter_value DEFAULT "100"

Passe os valores do widget usando a sintaxe ${param}.

SELECT *
FROM ${database}.${table}
WHERE col == ${filter_value}
LIMIT 100

Observação

Para escapar o caractere $ em um literal de cadeia de caracteres do SQL, use \$. Por exemplo, para expressar a cadeia de caracteres $1,000, use "\$1,000". O caractere $ não pode ser escapado para identificadores de SQL.

É possível configurar o comportamento de widgets quando um novo valor é selecionado, se o painel de widget sempre está fixado na parte superior do notebook e altera o layout dos widgets no notebook.

Clique no ícone do na extremidade direita do painel do Widget.
Na caixa de diálogo aparecerá Configurações do painel do Widge, escolha o comportamento de execução do Widget.
- Executar o Notebook: sempre que um novo valor for selecionado, todo o bloco de anotações será executado novamente.
- Executar comandos acessados: sempre que um novo valor é selecionado, somente as células que recuperam os valores desse widget específico são executadas novamente. Essa é a configuração padrão ao criar um widget. As células do SQL não são executadas novamente nesta configuração.
- Não fazer nada: sempre que um novo valor for selecionado, nada será executado novamente.
Para fixar os widgets na parte superior do notebook ou posicionar os widgets acima da primeira célula, clique em . A configuração é salva em uma base por usuário. Clique no ícone de miniatura novamente para redefinir como o comportamento padrão.
Se você tiver a permissão PODE GERENCIAR para notebooks, poderá configurar o layout do widget clicando em . A ordem e o tamanho de cada widget podem ser personalizados. Para salvar ou descartar suas alterações, clique nos .

O layout do widget é salvo com o notebook. Se você alterar o layout do widget da configuração padrão, novos widgets não serão adicionados alfabeticamente.
Para redefinir o layout do widget para uma ordem e tamanho padrão, clique no para abrir o diálogo Configurações do Painel do Widget e clique em Redefinir Layout. O comando removeAll() não redefine o layout do widget.