Travailler avec les parameters du tableau de bord

Cette page explique comment utiliser des paramètres sur les tableaux de bord AI/BI. Si vous souhaitez en savoir plus sur les filtres de champ, consultez plutôt Filtrer sur les champs.

Les AI/BI dashboard parameters vous permettent de substituer différentes valeurs dans les dataset queries au moment de l'exécution. Ceci vous permet de filtrer les données par des critères tels que les dates et les catégories de produits avant que les données ne soient agrégées dans une query SQL, ce qui conduit à une interrogation plus efficace et à une analyse précise. Les paramètres peuvent être utilisés avec des widgets de filtre pour rendre les tableaux de bord interactifs ou avec des widgets de visualisation pour faciliter la réutilisation des datasets.

Les auteurs ou éditeurs de tableaux de bord ajoutent des paramètres aux datasets et les connectent à un ou plusieurs widgets sur la zone de dessin du tableau de bord. Pour les paramètres statiques définis dans les widgets de visualisation, les valeurs sont définies par les auteurs ou les éditeurs. Pour les parameters utilisés dans les widgets de filtre, les spectateurs du tableau de bord peuvent interagir avec les données en sélectionnant des valeurs dans les widgets de filtre au moment de l'exécution. Cette interaction réexécute les requêtes associées et affiche les visualisations basées sur les données filtrées.

Choisissez entre les filtres de champ et les parameters

Les parameters modifient directement la query, ce qui peut être puissant. Les filtres de champ du dataset peuvent également offrir une interactivité de tableau de bord, davantage de fonctionnalités et de meilleures performances avec les grands datasets que les paramètres. Les filtres de champ prennent en charge le comportement en cascade par default : lorsqu'un filtre est appliqué, les options disponibles dans les autres filtres se mettent automatiquement à jour pour refléter les valeurs compatibles. Pour plus d'informations, consultez Dois-je filtrer sur un champ ou un parameter ?.

Ajouter un parameter à une query

Vous devez disposer d'au moins d'autorisations CAN EDIT sur le tableau de bord brouillon pour ajouter un paramètre à un dataset de tableau de bord. Vous pouvez ajouter des paramètres directement aux queries du dataset dans l'onglet tab .

Pour ajouter un parameter à une query :

1. Placez votre curseur là où vous souhaitez placer le parameter dans votre query.

2. Cliquez sur Add parameter pour insérer un nouveau parameter.

   Ceci crée un nouveau paramètre avec le nom default parameter. Pour changer le nom default, remplacez-le dans l'éditeur de query. Vous pouvez également ajouter des parameters en tapant cette syntaxe dans l'éditeur de query.

Modifier un paramètre de query

Pour modifier un parameter :

1. Cliquez sur à côté du nom du parameter. Une boîte de dialogue Détails du parameter apparaît et comprend les options de configuration suivantes :

   • Mot-clé : Le mot-clé qui représente le parameter dans la query. Cela ne peut être modifié qu’en mettant directement à jour le texte dans la query.

   • Nom d'affichage : Le nom dans l'éditeur de filtre. Par default, le titre est le même que le mot-clé.

   • **Type** : Les types pris en charge sont :**Chaîne**, **Date**, **Date et Heure**, **Numérique**.

     • Le type default est Chaîne .
     • Le type de données **Numérique** vous permet de spécifier entre les types **Décimal** et **Entier**. Le type numérique default est Décimal .

   • Autoriser plusieurs sélections : cochez la case pour permettre aux utilisateurs de choisir plusieurs paramètres au moment de l'exécution.

remarque

Cette sélection pourrait nécessiter une modification supplémentaire de votre query. Consultez Autoriser plusieurs sélections.

2. Cliquez sur une autre partie de l'interface utilisateur pour fermer la boîte de dialogue.

Définir une valeur de paramètre default

Pour tester votre requête, saisissez une valeur default dans le champ de texte sous le nom du paramètre et exécutez la requête. Ceci applique la valeur du paramètre afin que vous puissiez prévisualiser les résultats et confirmer que la requête s'exécute comme prévu. L'exécution de la query enregistre également la valeur par default.

Lorsque vous utilisez le parameter dans un widget de filtre, la valeur default de l' Data tab est utilisée, à moins que le widget ne spécifie une valeur default différente. Consultez Utiliser les filtres de tableau de bord.

Les auteurs de tableaux de bord devraient confirmer que les queries paramétrées s'exécutent correctement avec les valeurs default sélectionnées sur le tab dataset. Databricks interroge le schéma du dataset pour remplir l'éditeur de configuration du widget. Dans certains cas, particulièrement avec des queries paramétrées qui utilisent la clause IDENTIFIER, la query du dataset peut échouer à s'exécuter avec les valeurs de parameter default, même si elle réussirait lorsqu'un utilisateur sélectionne une valeur au moment de l'exécution.

Autoriser plusieurs sélections

Les requêtes qui autorisent plusieurs sélections doivent inclure une fonction ARRAY_CONTAINS dans la requête.

L'exemple suivant montre une query SQL qui vous permet de sélectionner plusieurs valeurs à insérer dans la query à l'exécution. La clause WHERE utilise la fonction ARRAY_CONTAINS avec une vérification supplémentaire NULL. Le paramètre doit être configuré pour contenir plusieurs valeurs afin qu'il puisse être inséré dans la requête sous forme de tableau.

Lorsque la query s'exécute :

• Si des valeurs spécifiques sont sélectionnées, chaque ligne est évaluée et toutes les lignes où l_quantity correspond à au moins une valeur dans :parameter sont incluses dans le jeu de résultats.
• Si « Tout » est sélectionné, le parameter est NULL et toutes les lignes sont renvoyées (aucun filtrage n’est appliqué).

SQL

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity) OR :parameter IS NULL

Pour définir des valeurs default :

1. Écrivez une query de dataset qui utilise la fonction ARRAY_CONTAINS pour filtrer les lignes en fonction d'une liste de valeurs.

2. Cliquez sur l'icône en forme d'engrenage à côté du nom du parameter. Sélectionnez **Autoriser les sélections multiples**.

remarque

Cette étape permet d'insérer le parameter dans la query sous forme de tableau. Si la fonction ARRAY_CONTAINS est utilisée sans activer les sélections multiples, une erreur se produit.

3. Saisissez une valeur dans le champ de texte sous le nom d'affichage. Vous pouvez saisir plusieurs valeurs. Sélectionnez la valeur actuelle avant de saisir la suivante.

Appliquer les paramètres de plage de dates

Vous pouvez utiliser des paramètres pour définir une plage et renvoyer uniquement les résultats qui s’y trouvent. Lorsque vous choisissez l’un des types de paramètres suivants, vous créez deux paramètres qui sont désignés par les suffixes .min et .max :

• Plage de dates
• Date et période

L’exemple suivant montre une requête SQL qui crée un parameter de plage de dates nommé date_param. La OR :date_param IS NULL condition gère le cas lorsqu'un utilisateur sélectionne **Tout**, ce qui définit le parameter à null et renvoie toutes les lignes.

SQL

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min AND :date_param.max
  OR :date_param IS NULL

Pour créer un paramètre de plage de dates :

1. Cliquez sur Ajouter un paramètre .

2. Cliquez sur à côté du nom du parameter. Saisissez le **mot-clé** et le **nom d'affichage**. N’incluez pas les suffixes .min ou .max.

3. Choisissez Plage de dates ou Plage de dates et d'heures comme Type .

4. Insérer une clause WHERE qui définit la plage dans votre requête. Pour définir la plage, utilisez une clause BETWEEN avec les valeurs .min et .max et incluez une condition OR :parameter IS NULL pour gérer les sélections Toutes . Par exemple :

   SQL

    WHERE date_col BETWEEN :date_param.min AND :date_param.max
      OR :date_param IS NULL

5. Saisissez les valeurs de date par default et exécutez la query pour la tester. Utilisez l'icône de calendrier pour choisir des options prédéfinies comme la semaine dernière ou le mois dernier.

Spécifiez une plage de dates relative.

Pour définir une plage de dates relative comme valeur de paramètre par default, saisissez l'expression directement dans le champ de valeur par default au lieu de la sélectionner dans le calendrier. Utilisez la syntaxe suivante pour exprimer les n derniers jours :

now-{n}d/d

• {n}: Le nombre de jours à remonter à partir d'aujourd'hui.
• /d: Arrondit le résultat au start de la journée.

Par exemple, pour configurer une plage default des 30 derniers jours, définissez la valeur .min sur now-30d/d et la valeur .max sur now/d.

Utiliser les paramètres dans les calculs personnalisés

Vous pouvez référencer les paramètres directement dans les calculs personnalisés à l’aide de la syntaxe :keyword. Voir Utiliser les paramètres dans les calculs personnalisés.

Paramètres basés sur les query

Les parameters basés sur des query permettent aux auteurs de définir une liste dynamique ou statique de valeurs que les spectateurs peuvent choisir lors de la définition des parameters lorsqu'ils explorent des données dans un tableau de bord. Ils sont définis en combinant un filtre de champ et un filtre de paramètre dans un seul widget de filtre.

Pour créer un paramètre basé sur une query, l'auteur du tableau de bord effectue les étapes suivantes :

1. Créer un dataset dont le jeu de résultats est limité à une liste de valeurs de parameter possibles.
2. Créez une query de dataset qui utilise un parameter.
3. Configurez un widget de filtre sur le canevas qui filtre sur un champ et utilise un paramètre.
   • Les configurations de Champs doivent être définies pour utiliser le champ avec la liste souhaitée de valeurs de paramètres éligibles.
   • La configuration des parameters doit être définie pour sélectionner une valeur de parameter.

Consultez Utiliser les paramètres basés sur une query pour un tutoriel étape par étape qui explique comment ajouter un paramètre basé sur une query et une visualisation.

remarque

Si un dataset utilisé dans des paramètres basés sur une query est également utilisé dans d'autres visualisations sur un tableau de bord, la sélection de filtre d'un utilisateur modifie toutes les queries connectées. Pour éviter cela, les auteurs devraient créer un dataset dédié aux paramètres basés sur les queries, qui n'est pas utilisé dans d'autres visualisations sur le tableau de bord.

Créer une liste de paramètres dynamique

Pour créer un dataset dynamique qui alimente la liste déroulante que les spectateurs utilisent pour sélectionner les valeurs de parameter, écrivez une query SQL qui renvoie un seul champ et inclut toutes les valeurs de ce champ. Toute nouvelle valeur dans ce champ est automatiquement ajoutée comme sélection de paramètre. Voici un exemple de query SQL :

SQL

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Créer une liste de paramètres statiques

Vous pouvez créer un dataset statique qui inclut uniquement les valeurs que vous codez en dur dans votre dataset. Un exemple de query est le suivant :

SQL

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

Supprimer un paramètre de requête

Pour supprimer un paramètre, supprimez-le de votre requête.

paramètres de widget statiques

Les parameters de widget statiques sont configurés directement dans un widget de visualisation, permettant aux auteurs de paramétrer individuellement les widgets de visualisation qui partagent le même dataset. Cela permet au même dataset de présenter différentes vues sur le canevas.

L'exemple de cette section est basé sur un dataset qui query la table samples.nyctaxi.trips. La query fournie renvoie la distance de chaque trajet et catégorise le jour de prise en charge comme étant Weekday ou Weekend. Le parameter de query filtre les résultats en fonction du fait que la prise en charge a eu lieu un jour de semaine ou un week-end.

Le texte de la requête est fourni dans le bloc de code suivant, mais les instructions de cette section sont limitées à la configuration des visualisations associées avec des paramètres de widget statiques. Pour les instructions sur la configuration d'un jeu de données avec des paramètres, voir Ajouter un paramètre à une requête.

SQL

  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

Pour ajouter un paramètre de widget statique à une visualisation :

1. Ajoutez un widget de visualisation au canevas du tableau de bord provisoire.

2. Une fois le nouveau widget sélectionné, choisissez le dataset paramétré dans la liste déroulante Dataset du panneau de configuration.

3. Cliquez sur Afficher les filtres . Pour les datasets qui incluent des parameters, une section Parameters apparaît dans le panneau de configuration.

   

4. Cliquez sur le signe plus à droite de l'en-tête Parameters et choisissez un parameter dans la liste déroulante.

5. Par default, la valeur du paramètre reflète ce qui est défini dans la query sur l'onglet Data . Vous pouvez le conserver ou choisir une nouvelle valeur à substituer dans le dataset. Naviguez hors du champ de texte pour afficher la visualisation avec le nouveau parameter appliqué.

6. Passez en revue votre tableau de bord.

   L'image suivante montre deux widgets de visualisation. Chacun est configuré comme un histogramme avec un paramètre de widget statique. Le graphique de gauche montre la distribution des distances de trajet pour les trajets commençant en semaine, tandis que le graphique de droite montre les mêmes données pour les week-ends. Les deux visualisations sont basées sur le même dataset.

   

Comparer les données à l'aide d'une condition de filtre

Vous pouvez ajouter une condition de filtre qui vous permet de comparer les agrégations sur une partie des données aux agrégations appliquées à l'ensemble du dataset.

L'exemple suivant étend la query précédente pour inclure une condition de filtre où la valeur du parameter spécifié est All, qui n'apparaît pas dans les données. La première partie de la condition de filtre fonctionne de la même manière que dans l'exemple précédent, en filtrant les résultats où le day_type est Weekday ou Weekend. La deuxième partie de la condition de filtre vérifie si le paramètre lui-même est défini sur une certaine valeur, dans ce cas All, qui n’apparaît pas dans les données. Lorsque vous définissez la valeur par default de ce parameter dans l'éditeur de dataset, vous contournez efficacement le filtre lorsque ni Weekday ni Weekend ne sont transmis comme valeurs.

SQL

WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

remarque

Cet exemple utilise une valeur de chaîne personnalisée ('All') pour les paramètres à valeur unique où « Tout » est défini comme une option statique. Pour les paramètres à sélection multiple, utilisez OR :parameter IS NULL à la place pour gérer les sélections « Tout ». Voir Autoriser plusieurs sélections.

Vous pouvez utiliser ce dataset pour configurer trois widgets de visualisation, avec le day_type_param défini sur All, Weekday et Weekend respectivement. Ensuite, les personnes qui consultent le tableau de bord peuvent comparer chaque dataset filtré par type de jour à l'ensemble du dataset.

Le GIF suivant vous montre comment créer rapidement trois graphiques à partir du dataset créé avec cette query.

1. Le premier graphique est configuré pour afficher le jeu de données **Distances de trajet par type de jour** avec une valeur de parameter définie sur **Jour de semaine**.
2. Cloner le graphique pour conserver toutes les configurations appliquées.
3. Pour afficher les données des trajets effectués le week-end, ajustez le paramètre statique sur Week-end .
4. Clonez le nouveau graphique pour conserver toutes les configurations précédemment appliquées.
5. Définissez le parameter dans le nouveau graphique sur All pour afficher le nombre total de trajets par distance pour les trajets de week-end et de semaine.

Utilisez des paramètres dans les widgets de texte

Vous pouvez faire référence aux parameters du tableau de bord dans les widgets de texte en utilisant le signe @ suivi du mot-clé du paramètre. Cela fonctionne dans le contenu, le titre et la description du widget. Quand un utilisateur sélectionne une valeur de parameter, le widget de texte se met à jour pour refléter la sélection actuelle.

Par exemple, si votre tableau de bord contient un paramètre avec le mot-clé region, vous pouvez écrire Sales data for @region dans le titre ou le corps d'un widget de texte et il est rendu avec la valeur sélectionnée.

Afficher les paramètres sur le tableau de bord

L'ajout d'un filtre à la zone de travail de votre tableau de bord vous permet de sélectionner et de modifier les valeurs des paramètres afin d'explorer et d'analyser les données de manière interactive. Si vous n'exposez pas le parameter sur le tableau de bord, les visionneurs ne voient que les résultats de query qui utilisent la valeur du parameter par default que vous avez définie dans la query.

Pour ajouter un paramètre à votre tableau de bord :

1. Cliquez sur Ajouter un filtre (champ/paramètre) .
2. Cliquez sur à côté de Paramètres dans le panneau de configuration.
3. Cliquez sur le nom du paramètre que vous souhaitez que l'utilisateur utilise avec ce widget.

Utilisation de widgets de filtre et de parameters statiques

Les paramètres sont des valeurs fixes substituées dans une query au moment de l'exécution. Si deux références ou plus au même paramètre sont définies avec des valeurs différentes lorsque votre tableau de bord se met à jour, les widgets de visualisation affichent une erreur indiquant quel paramètre a des valeurs conflictuelles. Cela peut se produire lorsque plusieurs widgets de filtre utilisent le même paramètre ou lorsqu'un paramètre statique entre en conflit avec un widget de filtre qui autorise la sélection par l'utilisateur.

Vous pouvez utiliser un modèle comme celui de l'exemple suivant pour définir des valeurs de fallback pour différents paramètres dans la même query.

SQL

CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

Dans cet exemple, :static_param fait référence à un static parameter, qui doit être défini sur « Tout » dans le widget de visualisation et l'éditeur de dataset. Le paramètre :dash_param est une valeur dynamique contrôlée par un widget de filtre sur le canevas du tableau de bord. Cette instruction vérifie une valeur fournie comme paramètre statique. Si aucune valeur n'est définie, elle utilise la valeur du paramètre de tableau de bord sélectionnée par l'observateur.

Inclure les paramètres dans l'URL

Les paramètres sont stockés dans l'URL, permettant aux utilisateurs de la mettre en favori pour maintenir l'état de leur tableau de bord, y compris les filtres et parameters prédéfinis, ou de la partager avec d'autres pour appliquer les mêmes filtres et parameters de manière cohérente.

Paramètres de tableau de bord vs. paramètres de query Mustache

Les paramètres du tableau de bord utilisent la même syntaxe que les marqueurs de paramètres nommés. Voir Marqueurs de paramètres nommés. Les tableaux de bord ne prennent pas en charge les parameters de style Mustache.

Paramètres du tableau de bord et paramètres du widget de Notebook

Les paramètres de AI/BI dashboard et les paramètres de widget de Notebook ont des objectifs différents et ne sont pas interchangeables :

• Paramètres du tableau de bord (cette page) : utilisés pour filtrer les données des jeux de données du tableau de bord au moment de l'exécution. Ils sont définis dans le tab Données d'un tableau de bord et exposés aux utilisateurs via des widgets de filtre sur le canevas.
• Paramètres de widget Notebook : Utilisés pour transmettre des valeurs aux cellules de notebook de manière interactive, configurés dbutils.widgets avec. Celles-ci sont propres aux notebooks et ne peuvent pas être référencées dans les tableaux de bord AI/BI.

Si vous créez des tableaux de bord qui interrogent des données basées sur des notebooks, notez que les paramètres des tableaux de bord contrôlent le filtrage au niveau de la query du dataset, et non au niveau de l’exécution du notebook.

Exemples de syntaxe

Les utilisations courantes des paramètres incluent l'insertion de dates, de nombres, de texte, d'objets de base de données et de valeurs à partir de chaînes JSON. Pour des exemples qui démontrent comment utiliser les paramètres dans ces cas, consultez Exemples de syntaxe de paramètres nommés.

important

Permettre aux visualiseurs d'accéder aux données via les sélections de paramètres comme les noms de table ou de catalogue pourrait entraîner une exposition accidentelle d'informations sensibles. Si vous publiez un tableau de bord avec ces options, Databricks recommande de ne pas intégrer les identifiants dans le tableau de bord publié.