Widgets do Databricks

Os widgets de entrada permitem que o senhor adicione parâmetros ao seu Notebook e painéis. O senhor pode adicionar um widget a partir da UI do Databricks ou usando a API de widget. Para adicionar ou editar um widget, o senhor deve ter permissões CAN EDIT no site Notebook.

Se você estiver executando o Databricks Runtime 11.3 LTS ou acima, também poderá usar ipywidgets no Databricks Notebook.

Os widgets Databricks são melhores para:

Criar um Notebook ou painel que seja reexecutado com parâmetros diferentes.
Explorar rapidamente os resultados de uma única consulta com diferentes parâmetros.

Para visualizar a documentação da API do widget em Scala, Python ou R, use o seguinte comando: dbutils.widgets.help()

Tipos de widget Databricks

Existem 4 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 menu dropdown. Selecione um valor de uma lista fornecida ou insira um na caixa de texto.
multiselect: Selecione um ou mais valores em uma lista de valores fornecidos.

As caixas suspensas e de texto do widget aparecem imediatamente após a barra de ferramentas Notebook. Os widgets aceitam apenas valores de strings.

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.

Criar widgets usando a UI

Crie um widget usando a interface do usuário Notebook. Se o senhor estiver conectado a um site SQL warehouse, essa é a única maneira de criar widgets.

Selecione Edit (Editar) > Add widget (Adicionar widget). Na caixa de diálogo Add widget (Adicionar widget ), digite o nome do widget, o rótulo opcional, o tipo, o tipo de parâmetro, os valores possíveis e o valor opcional default. Na caixa de diálogo, Parameter Name é o nome que o senhor usa para fazer referência ao widget em seu código. O rótulo do widget é um nome opcional que aparece sobre o widget na interface do usuário.

Depois de criar um widget, o senhor pode passar o mouse sobre o nome do widget para exibir uma dica de ferramenta que descreve como fazer referência ao widget.

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

Criar widgets com SQL, Python, R e Scala

Crie widgets de forma programática em um Notebook anexado a um compute cluster.

A API de widget foi projetada para ser consistente em Scala, Python e R. A API de widget em SQL é ligeiramente diferente, mas equivalente às outras linguagens. O senhor gerencia widgets por meio da interface de referênciaDatabricks utilidades (dbutils).

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

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

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

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

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

Interaja com o widget no painel de widgets.

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

dbutils.widgets.get("state")

dbutils.widgets.getAll()

dbutils.widgets.get("state")

dbutils.widgets.getAll()

dbutils.widgets.get("state")

SELECT :state

Finalmente, você pode remover um widget ou todos os widgets de um notebook:

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

REMOVE WIDGET state

Se o senhor remover um widget, não poderá criar outro na mesma célula. O senhor deve criar o widget em outra célula.

Use os valores do widget em Spark SQL e SQL warehouse

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 de SQL, separando claramente os valores fornecidos das instruções SQL.

Os marcadores de parâmetros para widgets estão disponíveis em Databricks Runtime 15.2 e acima. As versões anteriores do site Databricks Runtime devem usar a sintaxe antiga para DBR 15.1 e abaixo.

Você pode acessar widgets definidos em qualquer linguagem do Spark SQL enquanto executa notebooks interativamente. Considere o seguinte fluxo de trabalho:

Criar um widget dropdown 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 (selecionadas na lista suspensa):
```
SHOW TABLES IN IDENTIFIER(:database)
```
Observação

O senhor deve usar a cláusula SQL IDENTIFIER() 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 precisar editar o conteúdo da consulta:

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

Usar valores de widget no Databricks Runtime 15.1 e abaixo

Esta seção descreve como passar os valores dos widgets Databricks para as células %sql Notebook em Databricks Runtime 15.1 e abaixo.

Crie widgets para especificar valores de texto.

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

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

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

 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 do caractere $ em uma string SQL literal, use \$. Por exemplo, para expressar a string $1,000, use "\$1,000". O caractere $ não pode ter escape para identificadores SQL.

Definir as configurações do widget

Você pode configurar o comportamento dos widgets quando um novo valor é selecionado, se o painel de widgets fica sempre fixo no topo do notebook e alterar o layout dos widgets no notebook.

Clique no ícone na extremidade direita do painel Widget.
Na caixa de diálogo Configurações do Painel de Widgets que aparece, escolha o comportamento de execução do widget.
- Executar Notebook: toda vez que um novo valor é selecionado, todo o notebook é 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 quando você cria um widget. As células SQL não são executadas novamente nessa configuração.
- Não fazer nada: toda vez que um novo valor é selecionado, nada é executado novamente.
Para fixar os widgets na parte superior do Notebook ou colocá-los acima da primeira célula, clique em . A configuração é salva por usuário. Clique no ícone de tachinha novamente para Reset o comportamento default .
Se o senhor tiver a permissão CAN gerenciar para o Notebook, poderá configurar a disposição do widget clicando em . A ordem e o tamanho de cada widget podem ser personalizados. Para salvar ou descartar suas alterações, clique em .

A disposição do widget é salva com o endereço Notebook. Se o senhor alterar a disposição do widget na configuração do default, os novos widgets não serão adicionados em ordem alfabética.
Para Reset a disposição do widget para uma ordem e tamanho default , clique em para abrir a caixa de diálogo Widget Panel Settings e clique em Reset disposição. O comando removeAll() não Reset a disposição do widget.

Exemplo de notebook

O site Notebook a seguir mostra como funciona a configuração de execução do comando acessado. O widget year é criado com a configuração 2014 e é usado em DataFrame API e SQL comando.

Quando você altera a configuração do widget year para 2007, o comando DataFrame é executado novamente, mas o comando SQL não é executado novamente.

Este Notebook ilustra o uso de widgets em um Notebook anexado a um cluster, não a um SQL warehouse.

Widgets de Databricks em painéis

Quando o senhor cria um painel a partir de um Notebook com widgets de entrada, todos os widgets são exibidos na parte superior. No modo de apresentação, sempre que o senhor atualizar o valor de um widget, poderá clicar no botão Update (Atualizar ) para reexecutar o Notebook e atualizar o painel com os novos valores.

Usar widgets do Databricks com %run

Se o senhor executar um Notebook que contenha widgets, o Notebook especificado será executado com os valores default do widget.

Se o Notebook estiver anexado a um cluster (e não a um SQL warehouse), o senhor também poderá passar valores para os widgets. Por exemplo:

%run /path/to/notebook $X="10" $Y="1"

Este exemplo executa o notebook especificado e passa 10 no widget X e 1 no widget Y.

Limitações

Consulte Limitações conhecidas Databricks Notebook para obter mais informações.