Widgets do Databricks

  • Artigo

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 bloco de anotações ou painel que é reexecutado com diferentes parâmetros.
  • 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(). 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 bloco de anotações. Os widgets só aceitam valores de cadeia de caracteres.

Widget no cabeçalho

Criar widgets

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

Criar widgets usando a interface do usuário

Crie um widget usando a interface do usuário do bloco de anotações. Se você estiver conectado a um armazém SQL, essa é a única maneira de criar widgets.

Selecione Editar widget Adicionar>. Na caixa de diálogo Adicionar widget, insira 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.

caixa de diálogo criar widget

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.

dica de ferramenta do widget

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

menu kebab widget

Crie 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 do widget foi projetada para ser consistente em Scala, Python e R. A API do widget em SQL é ligeiramente diferente, mas equivalente às outras linguagens. Você gerencia widgets através da interface de referência 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. Esse argumento não é usado para text widgets de tipo.
  • O último argumento é label, um valor opcional para o rótulo mostrado na caixa de texto ou 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 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()

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

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 acessar valores de widget usando 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 e superior. As versões anteriores do Databricks Runtime devem usar a sintaxe antiga para DBR 15.1 e inferior.

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 table widget.

  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

Usar valores de widget no Databricks Runtime 15.1 e abaixo

Esta seção descreve como passar valores de widgets Databricks para %sql células de bloco de anotações no Databricks Runtime 15.1 e abaixo.

  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 ${param} sintaxe.

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

Nota

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

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 de engrenagem ícone na extremidade direita do painel Widget.

  2. Na caixa de diálogo pop-up Configurações do painel do widget, escolha o comportamento de execução do widget.

    Configurações do widget

    • Executar bloco de anotações: sempre que um novo valor é selecionado, todo o bloco de anotações é executado novamente.
    • Executar comandos acessados: sempre que um novo valor é selecionado, apenas as células que recuperam os valores desse widget específico são executadas novamente. 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: sempre que um novo valor é selecionado, nada é executado novamente.

  3. Para fixar os widgets na parte superior do bloco de anotações ou para colocá-los acima da primeira célula, clique em ícone de pino. 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 ícone de edição. A ordem e o tamanho de cada widget podem ser personalizados. Para salvar ou descartar as alterações, clique em aceitar e cancelar ícones.

    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 ícone de engrenagem para abrir a caixa de diálogo Configurações do painel do widget e, em seguida, clique em Redefinir layout. O removeAll() comando não redefine o layout do widget.

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

Painel com widgets

Use widgets Databricks com %run

Se você executar um bloco de anotações que contenha widgets, o bloco de anotações especificado será executado com os valores padrão do widget.

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 blocos de anotações Databricks para obter mais informações.