Widgets do Databricks

Os widgets de entrada permitem que você adicione parâmetros aos seus blocos de anotações 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ê deve ter permissões CAN EDIT no bloco de anotações.

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

Os widgets Databricks são melhores para:

• Criação de um caderno ou painel que é executado novamente com diferentes parâmetros.
• Explorar rapidamente os resultados de uma única consulta com diferentes parâmetros.

Para visualizar a documentação da API de widgets 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).

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 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 de widgets e as caixas de texto aparecem imediatamente após a barra de ferramentas do notebook. Os widgets só aceitam valores de cadeia de caracteres.

Criar widgets

Esta secção mostra-lhe como criar widgets usando a interface ou programaticamente usando SQL Magics ou a API de widgets para Python, Scala e R.

Criar widgets usando a interface do usuário

Crie um widget usando a interface do utilizador do notebook. Se você estiver conectado a um armazém SQL, essa é a única maneira de criar widgets. Selecione Editar parâmetro Adicionar>.

Para editar as configurações do widget, clique no ícone de engrenagem.

Na caixa de diálogo de configurações do widget , você pode inserir o nome do widget, rótulo opcional, tipo, tipo de parâmetro, valores possíveis e 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 do widget é um nome opcional que aparece sobre o 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 fazer referência ao widget.

Criar widgets com SQL, Python, R e Scala

Crie widgets programaticamente em um bloco de anotações conectado a um cluster de computação.

A API de widgets foi concebida para ser consistente em Scala, Python e R. A API de widgets em SQL é ligeiramente diferente, mas equivalente às outras linguagens. Você gerencia widgets através da interface de referência das Databricks Utilities (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 padrão do widget.
• O terceiro argumento para todos os tipos de widget (exceto text) é choices, uma lista de valores que o widget pode assumir. Este argumento não é usado para widgets do tipo text.
• O último argumento é label, um valor opcional para o rótulo mostrado acima da caixa de texto ou lista suspensa do widget.

Python

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

linguagem de programação Scala

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

R

dbutils.widgets.dropdown("state", "CA",  list("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 a partir do painel do widget.

Interaja com o 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()

linguagem de programação Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

Finalmente, você pode remover um widget ou todos os widgets em um bloco de anotações:

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

linguagem de programação 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.

Usar valores de widget no Spark SQL e no SQL Warehouse

Spark SQL e SQL Warehouse acedem os valores dos widgets usando os marcadores de parâmetro . Os marcadores de parâmetro protegem seu código contra ataques de injeção de SQL separando claramente os valores fornecidos das instruções SQL.

Os marcadores de parâmetro para widgets estão disponíveis no Databricks Runtime 15.2 ou superior. As versões anteriores do Databricks Runtime devem usar a sintaxe antiga para Databricks Runtime 15.1 e inferiores.

Você pode acessar widgets definidos em qualquer idioma do Spark SQL enquanto executa blocos de anotações interativamente. Considere o seguinte fluxo de trabalho:

1. Crie um widget suspenso de todos os bancos de dados no catálogo atual:

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

2. Crie um widget de texto para especificar manualmente um nome de tabela:

   dbutils.widgets.text("table", "")
   

3. Execute uma consulta SQL para ver todas as tabelas em um banco de dados (selecionadas na lista suspensa):

   SHOW TABLES IN IDENTIFIER(:database)
   

   Nota

   Você deve usar a cláusula SQL IDENTIFIER() para analisar cadeias de caracteres como identificadores de objeto, como nomes para bancos de dados, tabelas, exibições, funções, colunas e campos.

4. Insira manualmente um nome de tabela no widget table.

5. Crie um widget de texto para especificar um valor de filtro:

   dbutils.widgets.text("filter_value", "")
   

6. 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
   

Configurar as definições de widgets

Você pode configurar o comportamento dos widgets quando um novo valor é selecionado, se o painel de widgets está sempre fixado na parte superior do bloco de anotações e alterar o layout dos widgets no bloco de anotações.

1. Clique no ícone na extremidade direita do painel Widget.

2. No diálogo pop-up Definições do Painel de Widgets, escolha o comportamento de execução do widget.

   

   • Executar o Caderno: Reexecute o caderno inteiro sempre que selecionar um novo valor.
   • Executar Comandos de Acesso: Reexecuta apenas células que recuperam os valores desse widget em particular sempre que seleciona um novo valor. Esta é a configuração padrão quando você cria um widget. As células SQL não são executadas novamente nesta configuração.
   • Não Fazer Nada: Não reexecuta nada quando seleciona um novo valor.

3. Para fixar os widgets na parte superior do bloco de anotações ou para colocá-los acima da primeira célula, clique em . A configuração é salva por usuário. Clique no ícone thumbtack novamente para redefinir para o comportamento padrão.

4. Se você tiver permissão CAN MANAGE para blocos de anotações, poderá configurar o layout do widget clicando em . A ordem e o tamanho de cada widget podem ser personalizados. Para salvar ou descartar as alterações, clique em .

   O layout do widget é salvo com o bloco de anotações. Se você alterar o layout do widget a partir da configuração padrão, novos widgets não serão adicionados em ordem alfabética.

5. Para redefinir o layout do widget para uma ordem e tamanho padrão, clique em para abrir a caixa de diálogo Configurações do Painel de Widget e, em seguida, clique em Redefinir layout. O comando removeAll() não redefine o layout do widget.

Widgets do Databricks em painéis

Quando você cria um painel a partir de um bloco de anotações com widgets de entrada, todos os widgets são exibidos na parte superior. No modo de apresentação, sempre que atualizar o valor de um widget, pode clicar no botão Atualizar para executar novamente o bloco de notas e atualizar o painel com novos valores.

Use widgets Databricks com %run

Caso execute um notebook que contenha widgets, o notebook especificado será executado com os valores predefinidos dos widgets.

Se o bloco de anotações estiver conectado a um cluster (não a um armazém SQL), você também poderá passar valores para widgets. Por exemplo:

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

Este exemplo executa o bloco de anotações especificado e passa 10 para o widget X e 1 para o widget Y.

Limitações

Consulte Limitações conhecidas dos cadernos Databricks para mais informações.