Widgets Databricks

Article
10/29/2024

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.

Pour afficher la documentation de l’API de widget en Scala, Python ou R, utilisez la commande suivante : dbutils.widgets.help(). Vous pouvez également faire référence à la documentation de l’utilitaire de widgets (dbutils.widgets).

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.

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 :

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

Créez un widget de texte pour spécifier manuellement un nom de table :
```
dbutils.widgets.text("table", "")
```
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.
Entrez manuellement un nom de table dans le widget table.
Créez un widget de texte pour spécifier une valeur de filtre :
```
dbutils.widgets.text("filter_value", "")
```
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
```

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

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"

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.

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.

Cliquez sur l’icône à l’extrémité droite du panneau de widget.
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é.
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.
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.
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.