Aller au contenu principal
Dernière mise à jour le

Databricks widgets

Les widgets d'entrée vous permettent d'ajouter des paramètres à vos Notebooks et tableaux de bord. Vous pouvez ajouter un widget depuis l'interface utilisateur de Databricks ou en utilisant l'API de widget. Pour ajouter ou modifier un widget, vous devez disposer des autorisations CAN EDIT sur le Notebook.

Si vous utilisez Databricks Runtime 11.3 LTS ou une version supérieure, vous pouvez également utiliser ipywidgets dans les Notebooks Databricks.

Les widgets Databricks sont optimaux pour :

  • Création d'un Notebook ou d'un tableau de bord qui est réexécuté avec différents parameters.
  • Explorer rapidement les résultats d'une seule query avec différents parameters.

Pour consulter la documentation de l'API de widget pour Scala, Python ou R, utilisez la commande suivante : dbutils.widgets.help(). Vous pouvez également consulter la documentation de l'utilitaire de widgets (dbutils.widgets).

Types de widgets Databricks​

Il existe 4 types de widgets :

  • text: Saisissez une valeur dans une zone de texte.
  • dropdown: Sélectionnez une valeur dans une liste de valeurs fournies.
  • combobox: Combinaison de texte et de menu déroulant. Sélectionnez une valeur dans une liste fournie ou saisissez-en une dans la zone de texte.
  • multiselect: Sélectionnez une ou plusieurs valeurs dans une liste de valeurs fournies.

Les listes déroulantes de widgets et les zones de texte apparaissent immédiatement après la barre d'outils du Notebook. Les widgets n'acceptent que les valeurs de chaîne.

Widget dans l'en-tête

Créer des widgets​

Cette section vous montre comment créer des widgets à l'aide de l'interface utilisateur ou par programmation en utilisant les magies SQL ou l'API de widget pour Python, Scala et R.

prompt

Demandez à Genie Code (mode Agent) de le faire pour vous :

Create a new notebook that queries @samples.nyctaxi.trips and displays a bar chart showing the average fare amount by trip distance, grouped by the pickup zip code.

Créer des widgets à l'aide de l'interface utilisateur​

Créez un widget à l'aide de l'interface du notebook. Si vous êtes connecté à un SQL Warehouse, c'est le seul moyen de créer des widgets. Sélectionnez **Modifier > Ajouter un paramètre**.

Pour modifier les paramètres du widget , cliquez sur l’icône en forme de roue dentée.

menu kebab de widget

Dans la boîte de dialogue **Paramètres du widget**, vous pouvez saisir le nom du widget, l'étiquette facultative, le type, le type de paramètre, les valeurs possibles et la default value facultative. Dans la boîte de dialogue, **Nom du paramètre** est le nom que vous utilisez pour référencer le widget dans votre code. **Libellé du widget** est un nom facultatif qui apparaît au-dessus du widget dans l'interface utilisateur.

boîte de dialogue de création de widget

Une fois que vous avez créé un widget, vous pouvez survoler le nom du widget pour afficher une infobulle décrivant comment référencer le widget.

Infobulle de widget

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

Créer des widgets par programme dans un Notebook associé à un cluster de compute.

L'API de widget est conçue pour être cohérente en Scala, Python et R. L'API de widget en SQL est légèrement différente mais équivalente aux autres langages. Vous gérez les widgets via l'interface de référence des infrastructures publiques Databricks (dbutils).

  • Le premier argument pour tous les types de widgets est name. C'est le nom que vous utilisez pour accéder au widget.
  • Le deuxième argument est defaultValue, le paramètre default du widget.
  • Le troisième argument pour tous les types de widgets (sauf 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 au-dessus de la zone de texte ou de la liste déroulante du widget.
Python
dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

Interagissez avec le widget depuis le panneau de widget.

Interagir avec le widget

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

Enfin, vous pouvez supprimer un widget ou tous les widgets dans un Notebook :

Python
dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

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 les valeurs de widget dans Spark SQL et SQL Warehouse​

Spark SQL et SQL Warehouse accèdent aux valeurs de widget à l'aide de marqueurs de parameter. Les marqueurs de parameter protègent votre code des attaques par injection 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 devraient utiliser l'ancienne syntaxe pour Databricks Runtime 15.1 et versions antérieures.

Vous pouvez accéder aux widgets définis dans n’importe quelle langue à partir de Spark SQL lors de l’exécution interactive de Notebooks. Considérez le workflow suivant :

  1. Créez un widget déroulant de toutes les bases de données du catalogue actuel :

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

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

  3. Exécutez une SQL query pour voir toutes les tables d'une base de données (sélectionnée dans la liste déroulante) :

    SQL
    SHOW TABLES IN IDENTIFIER(:database)
remarque

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

  1. Saisissez manuellement un nom de table dans le widget table.

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

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

  3. Prévisualisez le contenu d’une table sans avoir besoin de modifier le contenu de la query :

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

Utiliser les valeurs de widget dans les clauses de chaîne DDL​

Certaines clauses DDL, telles que la clause LOCATION dans CREATE TABLE, acceptent des littéraux de chaîne plutôt que des identifiants. Vous ne pouvez pas utiliser la clause IDENTIFIER() pour ces clauses.

S'applique à : Databricks Runtime coché oui 18.0 et versions ultérieures

Dans Databricks Runtime 18.0 et versions ultérieures, vous pouvez utiliser des widgets directement dans ces clauses :

SQL
CREATE EXTERNAL TABLE my_table USING DELTA LOCATION :path

S'applique à : Databricks Runtime coché oui 14,3 – 17,3 LTS

Dans les versions précédentes, utilisez EXECUTE IMMEDIATE pour construire l'instruction dynamiquement. Par exemple, si vous avez un widget nommé path:

SQL
DECLARE table_location STRING;
SET VARIABLE table_location = CONCAT('abfss://container@account.dfs.core.windows.net/', :path);
EXECUTE IMMEDIATE 'CREATE EXTERNAL TABLE my_table USING DELTA LOCATION \'' || table_location || '\'';
remarque

Vous ne pouvez pas intégrer un marqueur de paramètre dans un littéral de chaîne (par exemple, 'abfss://:widget...'). Au lieu de cela, passez la chaîne entière comme un seul paramètre, ou construisez la chaîne complète dans une variable en utilisant CONCAT() puis passez-la à EXECUTE IMMEDIATE.

Pour plus d’informations sur l’utilisation des marqueurs de paramètres dans les instructions DDL, consultez Marqueurs de paramètres dans les clauses de chaînes DDL.

Configurer les paramètres du widget​

Vous pouvez configurer le comportement des widgets lorsqu'une nouvelle valeur est sélectionnée, si le panneau des widgets est toujours pin en haut du Notebook, et modifier la Layout des widgets dans le Notebook.

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

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

    Paramètres de widget

    • Exécuter le Notebook : réexécute l'intégralité du Notebook chaque fois que vous sélectionnez une nouvelle valeur.
    • Exécuter les commandes accessibles : Réexécute uniquement les cellules qui récupèrent les valeurs de ce widget particulier chaque fois que vous sélectionnez une nouvelle valeur. Il s'agit du paramètre default lorsque vous créez un widget. Les cellules SQL ne sont pas réexécutées dans cette configuration.
    • **Ne rien faire** : Ne réexécute rien lorsque vous sélectionnez une nouvelle valeur.

  3. To pin the widgets to the top of the Notebook or to place the widgets above the first cell, click icône pin. Le paramètre est enregistré par utilisateur. Cliquez à nouveau sur l'icône de la punaise pour Reset le comportement par défaut.

  4. Si vous disposez de l'autorisation CAN MANAGE pour les notebooks, vous pouvez configurer la Layout des widgets en cliquant sur icône de modification. L'ordre et la taille de chaque widget peuvent être personnalisés. Pour enregistrer ou annuler vos modifications, cliquez sur icônes d'acceptation et d'annulation.

    Le Layout du widget est enregistré avec le Notebook. Si vous modifiez le Layout du widget par rapport à la configuration default, les nouveaux widgets ne sont pas ajoutés par ordre alphabétique.

  5. Pour réinitialiser le Layout du widget à un ordre et une taille par default, cliquez sur icône d'engrenage pour ouvrir la boîte de dialogue Paramètres du panneau de widget , puis cliquez sur Reset Layout . La commande removeAll() ne Reset pas la Layout du widget.

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 actualiser votre tableau de bord avec les nouvelles valeurs.

Tableau de bord avec des widgets

Utilisez les widgets Databricks avec %run​

Si vous exécutez un Notebook qui contient des widgets, le Notebook spécifié est exécuté avec les valeurs « default » du widget.

Si le notebook est attaché à un cluster (et non à un SQL Warehouse), vous pouvez également transmettre des valeurs aux widgets. Par exemple :

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

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

Limitations​

Consultez les limites connues des Notebooks Databricks pour plus d'informations.

Sur cette page