Widgets Databricks

  • Article
  • 6 minutes de lecture

Les widgets d’entrée vous permettent d’ajouter des paramètres à vos notebooks et tableaux de bord. L’API Widget se compose d’appels permettant de créer différents types de widgets d’entrée, de les supprimer et d’accéder aux valeurs liées.

Dans Databricks Runtime 11.0 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.

Widget dans l’en-tête

API de widget Databricks

L’API Widget est conçue pour être cohérente dans Scala, Python et R. L’API 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 Databricks Utilites.

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

Les widgets acceptent uniquement les valeurs de chaîne.

Python

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

dbutils.widgets.text("database", "customers_dev")

SQL

CREATE WIDGET DROPDOWN state DEFAULT "CA" CHOICES SELECT * FROM (VALUES ("CA"), ("IL"), ("MI"), ("NY"), ("OR"), ("VA"))

CREATE WIDGET TEXT database DEFAULT "customers_dev"

Exemple de widget Databricks

Pour obtenir une documentation détaillée sur l’API pour chaque méthode, utilisez dbutils.widgets.help("<method-name>"). L’API d’aide est identique dans tous les langages. Par exemple :

dbutils.widgets.help("dropdown")

Créez un widget de liste déroulante simple.

Python

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.

Interagir avec un widget

Vous pouvez accéder à la valeur actuelle du widget avec l’appel :

Python

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

SQL

REMOVE WIDGET state

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

Utilisation de valeurs de widget dans Spark SQL

Spark SQL accède aux valeurs du widget en tant que littéraux de chaîne qui peuvent être utilisés dans les requêtes.

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

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

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

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

Notes

En général, vous ne pouvez pas utiliser de widgets pour passer des arguments entre différents langages dans 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.

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

Configurer les paramètres des 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 icône Engrenage à 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.

    Paramètres 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 icône Épingle. 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 de Gestion pour les notebooks, vous pouvez configurer la disposition du widget en cliquant sur icône Modifier. L’ordre et la taille de chaque widget peuvent être personnalisés. Pour enregistrer ou ignorer vos modifications, cliquez sur icônes Accepter et Annuler.

    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 icône Engrenage 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 notebook

Vous pouvez voir une démonstration du fonctionnement du paramètre Exécuter les commandes accessibles dans le notebook suivant. Le widget year est créé avec le paramètre 2014 et utilisé dans l’API DataFrame et les commandes SQL.

Widgets

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.

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 contenant des widgets d’entrée, tous les widgets s’affichent en haut du tableau de bord. 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.

Tableau de bord avec des widgets

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

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 son é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.