Widgets Databricks

Les widgets d’entrée vous permettent d’ajouter des paramètres à vos notebooks et tableaux de bord. Vous pouvez ajouter un widget à partir de l’interface utilisateur Databricks ou à l’aide de l’API de widget. Pour ajouter ou modifier un widget, vous devez disposer des autorisations PEUT MODIFIER sur le notebook.

Dans Databricks Runtime 11.3 LTS et versions ultérieures, vous pouvez également utiliser des ipywidgets dans les notebooks Databricks.

Les widgets Databricks sont parfaitement adaptés pour :

• Génération d’un notebook ou d’un tableau de bord réexécuté avec des paramètres différents.
• Exploration rapide des résultats d’une requête unique avec des paramètres différents.

Consultez la documentation de l’API Widget dans Scala, Python et R avec la commande suivante : dbutils.widgets.help()

Types de widgets Databricks

Il existe 4 types de widgets :

• text : entrée d’une valeur dans une zone de texte.
• dropdown : sélection d’une valeur dans une liste de valeurs fournies.
• combobox : combinaison de texte et de liste déroulante. Sélectionnez une valeur dans la liste fournie ou entrez-en une dans la zone de texte.
• multiselect : sélection d’une ou plusieurs valeurs dans une liste de valeurs fournies.

Les listes déroulantes et zones de texte des widgets apparaissent immédiatement après la barre d’outils du notebook. Les widgets acceptent uniquement les valeurs de chaîne.

Créer des widgets

Cette section vous montre comment créer des widgets à l’aide de l’interface utilisateur ou programmatiquement à l’aide de magics SQL ou de l’API de widget pour Python, Scala et R.

Créer des widgets à l’aide de l’interface utilisateur

Créez un widget à l’aide de l’interface utilisateur de notebook. Si vous êtes connecté à un entrepôt SQL, il s’agit de la seule façon de créer des widgets.

Sélectionnez Modifier > Ajouter un widget. Dans la boîte de dialogue Ajouter un widget, entrez le nom du widget, l’étiquette facultative, le type, le type de paramètre, les valeurs possibles et la valeur par défaut facultative. Dans la boîte de dialogue, le champ Nom du paramètre est le nom que vous utilisez pour référencer le widget dans votre code. Le champ Étiquette du widget est un nom facultatif qui apparaît sur le widget dans l’interface utilisateur.

Une fois que vous avez créé un widget, vous pouvez pointer sur le nom du widget pour afficher une info-bulle qui décrit comment référencer le widget.

Vous pouvez utiliser le menu kebab pour modifier ou supprimer le widget :

Créer des widgets avec SQL, Python, R et Scala

Créez par programmation des widgets dans un notebook attaché à un cluster de calcul.

L’API de widget est conçue pour être homogène dans Scala, Python et R. L’API de widget dans SQL est légèrement différente, mais aussi puissante que celle des autres langages. Vous gérez les widgets via l'interface de référence Databricks Utilities (dbutils).

• Le premier argument de tous les types de widgets est name. Il s’agit du nom que vous utilisez pour accéder au widget.
• Le deuxième argument est defaultValue, la valeur par défaut du widget.
• Pour tous les types de widgets, le troisième argument (à l’exception de text) est choices, une liste de valeurs que le widget peut prendre. Cet argument n’est pas utilisé pour les widgets de type text.
• Le dernier argument est label, une valeur facultative pour l’étiquette affichée sur la zone de texte ou la liste déroulante du 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"))

Interagissez avec le widget à partir du panneau de celui-ci.

Vous pouvez accéder à la valeur actuelle du widget ou obtenir un mappage de tous les 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

Enfin, vous pouvez supprimer un widget ou tous les widgets d’un 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

Si vous supprimez un widget, vous ne pouvez pas en créer un dans la même cellule. Vous devez créer le widget dans une autre cellule.

Utiliser des valeurs de widget dans Spark SQL et SQL Warehouse

Spark SQL et SQL Warehouse accèdent aux valeurs du widget à l’aide de marqueurs de paramètres. Les marqueurs de paramètres protègent votre code contre les attaques par injection de code SQL en séparant clairement les valeurs fournies des instructions SQL.

Les marqueurs de paramètres pour les widgets sont disponibles dans Databricks Runtime 15.2 et versions ultérieures. Les versions précédentes de Databricks Runtime doivent utiliser l’ancienne syntaxe de DBR 15.1 et versions inférieures.

Vous pouvez accéder aux widgets définis dans n’importe quel langage à partir de Spark SQL lors de l’exécution interactive de notebooks. Observez le flux de travail suivant :

1. Créez un widget de liste déroulante de toutes les bases de données dans le catalogue actuel :

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

2. Créez un widget de texte pour spécifier manuellement un nom de table :

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

3. Exécutez une requête SQL pour afficher toutes les tables d’une base de données (sélectionnées dans la liste déroulante) :

   SHOW TABLES IN IDENTIFIER(:database)
   

   Remarque

   Vous devez utiliser la clause SQL IDENTIFIER() pour analyser des chaînes en tant qu’identificateurs d’objet tels que les noms des bases de données, des tables, des vues, des fonctions, des colonnes et des champs.

4. Entrez manuellement un nom de table dans le widget table.

5. Créez un widget de texte pour spécifier une valeur de filtre :

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

6. Affichez un aperçu du contenu d’une table sans avoir à modifier le contenu de la requête :

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

Utiliser des valeurs de widget dans Databricks Runtime 15.1 et versions inférieures

Cette section explique comment transmettre des valeurs de widgets Databricks aux cellules de notebook %sql dans Databricks Runtime 15.1 et versions inférieures.

1. Créez des widgets pour spécifier des valeurs de texte.

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. Transmettez les valeurs du widget à l’aide de la syntaxe ${param}.

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

Remarque

Pour échapper le caractère $ dans un littéral de chaîne SQL, utilisez \$. Par exemple, pour exprimer la chaîne $1,000, utilisez "\$1,000". Le caractère $ ne peut pas être échappé pour des identificateurs SQL.

Configurer des paramètres de widgets

Vous pouvez configurer le comportement des widgets lors de la sélection d’une nouvelle valeur si le panneau du widget est toujours épinglé en haut du notebook et si vous modifiez la disposition des widgets dans le notebook.

1. Cliquez sur l’icône à l’extrémité droite du panneau de widget.

2. Dans la boîte de dialogue contextuelle Paramètres du panneau du widget, choisissez le comportement d’exécution du widget.

   

   • Exécuter le notebook : chaque fois qu’une nouvelle valeur est sélectionnée, le notebook entier est réexécuté.
   • Exécuter les commandes accessibles : chaque fois qu’une nouvelle valeur est sélectionnée, seules les cellules qui récupèrent les valeurs de ce widget particulier sont réexécutées. Il s’agit du paramètre par défaut quand vous créez un widget. Les cellules SQL ne sont pas réexécutées dans cette configuration.
   • Ne rien faire : chaque fois qu’une nouvelle valeur est sélectionnée, rien n’est réexécuté.

3. Pour épingler les widgets en haut du notebook ou placer les widgets au-dessus de la première cellule, cliquez sur . Le paramètre est enregistré au niveau de chaque utilisateur. Cliquez à nouveau sur l’icône en forme de punaise pour rétablir le comportement par défaut.

4. Si vous disposez de l’autorisation PEUT GÉRER pour les notebooks, vous pouvez configurer la disposition du widget en cliquant sur . L’ordre et la taille de chaque widget peuvent être personnalisés. Pour enregistrer ou ignorer vos modifications, cliquez sur .

   La disposition du widget est enregistrée avec le notebook. Si vous modifiez la disposition des widgets par rapport à la configuration par défaut, les nouveaux widgets ne sont pas ajoutés par ordre alphabétique.

5. Pour rétablir la disposition du widget sur un ordre et une taille par défaut, cliquez sur afin d’ouvrir la boîte de dialogue Paramètres du panneau du widget, puis cliquez sur Rétablir la disposition. La commande removeAll() ne réinitialise pas la disposition des widgets.

Exemple de bloc-notes

Le notebook suivant montre comment fonctionne le paramètre Exécuter les commandes sollicitées. Le widget year est créé avec le paramètre 2014 et utilisé dans l’API DataFrame et les commandes SQL.

Lorsque vous modifiez le paramètre du widget year en 2007, la commande DataFrame se réexécute, mais la commande SQL n’est pas réexécutée.

Ce notebook illustre l’utilisation de widgets dans un notebook attaché à un cluster, et non à un entrepôt SQL.

Notebook de démonstration du widget

Obtenir le notebook

Widgets Databricks dans les tableaux de bord

Lorsque vous créez un tableau de bord à partir d’un notebook avec des widgets d’entrée, tous les widgets s’affichent en haut. En mode présentation, chaque fois que vous mettez à jour la valeur d’un widget, vous pouvez cliquer sur le bouton Mettre à jour pour réexécuter le notebook et mettre à jour votre tableau de bord avec les nouvelles valeurs.

Utiliser les widgets Databricks avec %run

Si vous exécutez un notebook contenant des widgets, le notebook spécifié est exécuté avec les valeurs par défaut du widget.

Si le notebook est attaché à un cluster (pas à un entrepôt SQL), vous pouvez également transmettre des valeurs aux widgets. Par exemple :

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

Cet exemple exécute le notebook spécifié et passe 10 au widget X et 1 au widget Y.

Limites

• Les limites suivantes s’appliquent aux widgets :

  • Un maximum de 512 widgets peut être créé dans un bloc-notes.
  • Le nom d’un widget est limité à 1024 caractères.
  • Le libellé d’un widget est limité à 2048 caractères.
  • Un maximum de 2048 caractères peut être entré dans un widget de texte.
  • Il peut y avoir un maximum de 1024 choix pour un widget de liste déroulante, de sélection multiple ou de zone de liste déroulante.

• Il existe un problème connu où l’état d’un widget peut ne pas être correctement effacé après avoir appuyé sur Exécuter tout, même après l’effacement ou la suppression du widget dans le code. Si cela se produit, vous verrez une différence entre l’état visuel du widget et l’état imprimé. La ré-exécution des cellules individuellement peut permettre de contourner ce problème. Pour éviter entièrement ce problème, Databricks vous recommande d’utiliser ipywidgets.

• Vous ne devez pas accéder directement à l’état d’un widget dans des contextes asynchrones comme des threads, des sous-processus ou Structured Streaming (foreachBatch), car l’état du widget peut changer pendant l’exécution du code asynchrone. Si vous devez accéder à l’état du widget dans un contexte asynchrone, transmettez-le en tant qu’argument. Par exemple, si vous avez le code suivant qui utilise des 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()
  

  Vous devez au lieu de cela l’écrire de cette façon :

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

• En règle générale, les widgets ne peuvent pas transmettre d’arguments entre différents langages au sein d’un notebook. Vous pouvez créer un widget arg1 dans une cellule Python, et l’utiliser dans une cellule SQL ou Scala si vous exécutez une cellule à la fois. Mais cela ne fonctionne pas si vous utilisez la fonction Exécuter tout ou exécutez le notebook en tant que travail. Voici certaines solutions de contournement :

  • Pour les notebooks qui ne mélangent pas de langues, vous pouvez créer un notebook pour chaque langue et transmettre les arguments lorsque vous exécutez le notebook.
  • Vous pouvez accéder au widget à l’aide d’un appel spark.sql(). Par exemple, dans Python : spark.sql("select getArgument('arg1')").take(1)[0][0].