Pular para o conteúdo principal

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,CAN EDIT o senhor deve ter as permissões no Notebook.

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

Os widgets Databricks são melhores para:

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

Para view a documentação do widget API em Scala, Python, ou R, use o seguinte comando: dbutils.widgets.help(). O senhor também pode consultar a documentação sobre utilidades de widgets (dbutils.widgets).

Tipos de widgets do 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 do Notebook. Os widgets aceitam apenas valores de strings.

Widget no cabeçalho

Crie 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 UI do Notebook. Se o senhor estiver conectado a um site SQL warehouse, essa é a única maneira de criar widgets.

Selecione Editar > 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, Nome do parâmetro é o nome que você usa para referenciar o widget em seu código. O rótulo do widget é um nome opcional que aparece sobre o widget na interface do usuário.

caixa de diálogo de criação de 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 referenciar o widget.

dica de ferramenta de widget

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

menu de widget de kebab

Criar widgets com SQL, Python, R e Scala​

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

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. O senhor gerencia os 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.
Python
dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

Interaja com o widget no painel de widgets.

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

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

Python
dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

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 nos depósitos Spark SQL e SQL​

Spark SQL e o armazém SQL acessa 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:

  1. Criar um widget dropdown de todos os bancos de dados no catálogo atual:

    Python
    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:

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

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

    SQL
    SHOW TABLES IN IDENTIFIER(:database)
nota

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.

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

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

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

  3. Visualize o conteúdo de uma tabela sem precisar editar o conteúdo da consulta:

    SQL
    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 do Notebook em 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")

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

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

Para escapar do caractere $ em um literal de cadeia de caracteresSQL, use \$. Por exemplo, para expressar as cadeias de caracteres $1,000, use "\$1,000". O caractere $ não pode ser escapado 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.

  1. Clique no ícone ícone de engrenagem à direita do painel do Widget.

  2. Na caixa de diálogo Configurações do Painel de Widgets que aparece, escolha o comportamento de execução do widget.

    Configurações 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.

  3. Para fixar os widgets na parte superior do notebook ou colocar os widgets acima da primeira célula, clique em ícone de alfinete. A configuração é salva por usuário. Clique no ícone de miniatura novamente para redefinir o comportamento padrão.

  4. Se o senhor tiver permissão CAN MANAGE para o Notebook, poderá configurar a disposição do widget clicando em ícone de edição. A ordem e o tamanho de cada widget podem ser personalizados. Para salvar ou ignorar suas alterações, clique em aceitar e cancelar ícones.

    A disposição do widget é salva com o Notebook. Se o senhor alterar a disposição dos widgets na configuração do site default, os novos widgets não serão adicionados em ordem alfabética.

  5. Para redefinir a disposição do widget para uma ordem e tamanho default, clique em ícone de engrenagem para abrir a caixa de diálogo Widget Panel Settings e, em seguida, clique em Reset disposição . O comando removeAll() não redefine o widget disposição.

Widgets do 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, toda vez 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.

Painel com widgets

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 clustering (não a um SQL warehouse), o senhor também poderá passar valores para os widgets. Por exemplo:

Bash
%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.

Última atualização em