Widgets do Databricks

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 e R, use o seguinte comando: dbutils.widgets.help()

Tipos de widget do Databricks

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.

Use os valores do widget no Spark SQL e no 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 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:

1. 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()])
   

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

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 a necessidade de editar o conteúdo da consulta:

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

Utilize os valores dos widgets no Databricks Runtime 15.1 e versões anteriores

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.

1. 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"

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

Configurações de widget

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

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

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

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

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

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

Caderno de exemplo

O seguinte notebook mostra como funciona a configuração de Executar comandos acessados. O widget year é criado com a configuração 2014 e é usado na API do DataFrame e nos comandos SQL.

Ao alterar a configuração do widget year para 2007, o comando DataFrame executa 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.

Notebook de demonstração do widget

Obter notebook

Widgets do Databricks em dashboards

Quando você cria um painel a partir de um notebook com widgets de entrada, todos os widgets são exibidos no topo. No modo de apresentação, sempre que você atualizar o valor de um widget, poderá clicar no botão Atualizar para executar novamente o notebook e atualizar seu painel com novos valores.

Usar widgets do Databricks com %run

Se você executar um notebook que contém widgets, o notebook especificado será executado com os valores padrão do widget.

Se o notebook estiver anexado a um cluster (não a um SQL Warehouse), você também poderá passar valores para widgets. Por exemplo:

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

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

Limitações

• Os seguintes limites se aplicam aos widgets:

  • Um máximo de 512 widgets pode ser criado em um notebook.
  • O nome do widget está limitado a 1024 caracteres.
  • Um rótulo do widget está limitado a 2048 caracteres.
  • Um máximo de 2048 caracteres pode ser inserido em um widget de texto.
  • Pode haver um máximo de 1024 opções para um widget de seleção múltipla, caixa de combinação ou menu suspenso.

• Existe um problema conhecido em que um estado de widget pode não ser limpo corretamente depois de pressionar Executar Todos, mesmo depois de limpar ou remover o widget no código. Se isso acontecer, você verá uma discrepância entre o estado visual e impresso do widget. Executar novamente as células individualmente pode ignorar esse problema. Para evitar esse problema completamente, o Databricks recomenda usar ipywidgets.

• Você não deve acessar o estado do widget diretamente em contextos assíncronos, como threads, subprocessos ou Fluxo Estruturado (foreachBatch), pois o estado do widget pode ser alterado enquanto o código assíncrono está em execução. Se você precisar acessar o estado do widget em um contexto assíncrono, passe-o como um argumento. Por exemplo, se você tiver o seguinte código que usa threads:

  import threading
  
  def thread_func():
    # Unsafe access in a thread
    value = dbutils.widgets.get('my_widget')
    print(value)
  
  thread = threading.Thread(target=thread_func)
  thread.start()
  thread.join()
  

  Você deve gravá-lo desta forma:

  # Access widget values outside the asynchronous context and pass them to the function
  value = dbutils.widgets.get('my_widget')
  
  def thread_func(val):
    # Use the passed value safely inside the thread
    print(val)
  
  thread = threading.Thread(target=thread_func, args=(value,))
  thread.start()
  thread.join()
  

• Em geral, os widgets não podem passar argumentos entre diferentes linguagens dentro de um notebook. É possível criar um widget arg1 em uma célula do Python e usá-lo em uma célula do SQL ou Scala se você executar uma célula de cada vez. No entanto, isso não funcionará se você usar Executar todos ou executar o notebook como trabalho. Algumas soluções alternativas são:

  • Para notebooks que não combinam idiomas, você pode criar um notebook para cada idioma e passar os argumentos ao executar o notebook.
  • Você pode acessar o widget usando uma chamada spark.sql(). Por exemplo, em Python: spark.sql("select getArgument('arg1')").take(1)[0][0].