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.

Widget no cabeçalho

Criar widget usando a IU

Para criar um widget, selecione Editar > Adicionar widget. 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 default 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. O rótulo do widget é um nome opcional que aparece sobre o widget na UI.

caixa de diálogo criar widget

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.

dica de widget

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

menu de widget de kebab

Use os widgets do Databricks em um cluster de computação

Esta seção descreve como usar os widgets do Databricks em um Notebook anexado a um cluster compute. Para usar widgets em um Notebook que está anexado a um SQL warehouse, consulte Use Databricks widgets on a SQL warehouse.

API de widget do Databricks (clusters)

A API do widget foi projetada para ser consistente em Scala, Python e R. A API do widget em SQL é um pouco diferente, mas equivalente às outras linguagens. Você gerencia widgets através da interface de referência do Databricks russas (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 widgets de tipotext.

  • O último argumento é label, um valor opcional para o rótulo mostrado sobre a caixa de texto ou menu suspenso do widget.

Exemplo de widget do Databricks (clusters)

Para ver a documentação detalhada da API para cada método, use dbutils.widgets.help("<method-name>"). A API de ajuda é idêntica em todos os idiomas. Por exemplo:

dbutils.widgets.help("dropdown")

Crie um widget dropdown simples.

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.

Interaja com o widget

Você pode acessar o valor atual do widget com a chamada:

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

REMOVE WIDGET state

Se você remover um widget, não poderá criar um widget na mesma célula. Você deve criar o widget em outra célula.

Uso de valores de widget no Spark SQL (clusters)

Spark SQL acessa valores de widget como literais de string que podem ser utilizados em consultas.

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:

    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 ${database}

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

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

    SELECT *
FROM ${database}.${table}
LIMIT 100

Observação

Normalmente, não é possível utilizar widgets para transferir argumentos entre diferentes linguagens dentro de um notebook.Você pode criar um widget arg1 em uma célula Python e utilizá-lo em uma célula SQL ou Scala se você executar uma célula de cada vez. No entanto, isto não funciona se você utilizar Executar Tudo ou executar o notebook como um trabalho.

Soluções alternativas:

  • Para Notebook que não misturam idiomas, você pode criar um Notebook para cada idioma e passar os argumentos ao executar o Notebook.

    • Você pode acessar o widget usando uma spark.sql() chamada. Por exemplo, em Python: spark.sql("select getArgument('arg1')").take(1)[0][0].

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.

Use os widgets do Databricks em um SQL warehouse

Esta seção descreve como usar os widgets do Databricks em um Notebook anexado a um SQL warehouse. Para usar widgets em um Notebook que está anexado a um cluster compute, consulte Usar widgets do Databricks em um cluster compute .

Para fazer referência aos valores do widget em um SQL warehouse, use a sintaxe :param, não $param. Por exemplo, se o senhor tiver um widget chamado fare_amount, use um código semelhante ao seguinte:

SELECT * FROM samples.nyctaxi.trips WHERE fare_amount < :fare_amount

Use a palavra-chave IDENTIFIER para identificar objetos como tabelas, visualizações, esquemas e colunas. Por exemplo, se o widget chamado table_name for definido como samples.nyctaxi.trips:

SELECT * FROM IDENTIFIER(:table_name)

Para obter detalhes, consulte a cláusula IDENTIFIER.

Para obter detalhes sobre a sintaxe do marcador de parâmetro, consulte Marcadores de parâmetro.

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 de engrenagem ícone na extremidade direita do painel 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 colocá-los acima da primeira célula, clique em ícone de alfinete. A configuração é salva por usuário. Clique no ícone de tachinha novamente para Reset o comportamento default .

  4. Se o senhor tiver a permissão CAN gerenciar 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 descartar suas alterações, clique em aceitar e cancelar ícones.

    O layout do widget é salvo com o notebook. Se você alterar o layout dos widgets da configuração padrão, os novos widgets não serão adicionados em ordem alfabética.

  5. Para Reset 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 clique em Reset disposição. O comando removeAll() não Reset a disposição do widget.

Exemplo de notebook

Você pode visualizar uma demonstração de como a configuração Execução de Comandos Acessados funciona no seguinte notebook. O widget year é criado com a configuração 2014 e é utilizado nos comandos DataFrame API e SQL.

Widgets

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.

Notebook de demonstração de widget

Abra o bloco de anotações em outra guia

Widgets de Databricks em painéis

Quando você cria um painel a partir de um notebook que tem widgets de entrada, todos os widgets são exibidos na parte superior do painel. No modo de apresentação, toda vez que você atualiza o valor de um widget, você pode clicar no botão Atualizar para executar novamente o notebook e atualizar seu painel com 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 cluster (ou seja, não for 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

  • Os seguintes limites se aplicam a widgets:

    • Um máximo de 512 widgets podem ser criados em um Notebook.

    • O nome de um widget é limitado a 1.024 caracteres.

    • Um rótulo de widget é limitado a 2.048 caracteres.

    • Um máximo de 2.048 caracteres podem ser inseridos em um widget de texto.

    • Pode haver no máximo 1.024 opções para uma seleção múltipla, caixa de combinação ou widget dropdown .

  • Existe um problema conhecido em que o estado de um widget pode não ser limpo corretamente após pressionar Executar tudo, mesmo depois de limpar ou remover o widget no código. Se isso acontecer, você verá uma discrepância entre o estado visual do widget e seu estado impresso. A reexecução das células individualmente pode contornar esse problema. Para evitar totalmente esse problema, o Databricks recomenda que você use ipywidgets.

  • O senhor não deve acessar o estado do widget diretamente em contextos assíncronos, como threads, subprocessos ou transmissão estruturada(foreachBatch), pois o estado do widget pode mudar enquanto o código assíncrono estiver em execução. Se precisar acessar o estado do widget em um contexto assíncrono, passe-o como um argumento. Por exemplo, se o senhor 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()

    Então, em vez disso, o senhor deve escrever 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()