Travailler avec les paramètres de tableau de bord

Cette page explique comment utiliser des paramètres sur des tableaux de bord IA/BI. Si vous préférez en savoir plus sur les filtres de champ, veuillez consulter la section Filtrer sur des champs.

Les paramètres des tableaux de bord AI/BI vous permettent de substituer différentes valeurs dans les requêtes de jeu de données à l’exécution. Cela vous permet de filtrer les données selon 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 requête SQL, ce qui rend les requêtes plus efficaces et l’analyse plus 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 jeux de données.

Les auteurs ou éditeurs de tableaux de bord ajoutent des paramètres aux jeux de données et les relient à un ou plusieurs widgets sur le canevas 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 éditeurs. Pour les paramètres utilisés dans les widgets de filtre, les utilisateurs du tableau de bord peuvent interagir avec les données en sélectionnant des valeurs dans les widgets de filtre à l’exécution. Cette interaction relance les requêtes associées et affiche les visualisations en fonction des données filtrées.

Choisir entre les filtres de champs et les paramètres

Les paramètres modifient directement la requête, ce qui peut s’avérer être un puissant outil. Les filtres de champ de jeu de données peuvent également offrir une interactivité accrue, davantage de fonctionnalités et de meilleures performances avec de grands jeux de données que les paramètres. Pour plus d’informations, voir Dois-je filtrer sur un champ ou un paramètre ?.

Ajouter un paramètre à une requête

Vous devez disposer au minimum des autorisations CAN EDIT (PEUT MODIFIER) sur le tableau de bord en cours de création pour ajouter un paramètre à un jeu de données de tableau de bord. Vous pouvez ajouter des paramètres directement dans les requêtes de jeu de données dans l’onglet Données.

Pour ajouter un paramètre à une requête :

1. Placez votre curseur à l’endroit où vous souhaitez insérer le paramètre dans votre requête.

2. Cliquez sur Ajouter un paramètre pour insérer un nouveau paramètre.

   Cela crée un nouveau paramètre avec le nom par défaut parameter. Pour modifier le nom par défaut, remplacez-le dans l’éditeur de requête. Vous pouvez également ajouter des paramètres en saisissant cette syntaxe dans l’éditeur de requête.

Modifier un paramètre de requête

Pour modifier un paramètre :

1. Cliquez sur À côté du nom du paramètre. Une boîte de dialogue Parameter detail (Détails du paramètre) s’affiche et comprend les options de configuration suivantes :

   • Keyword (Mot clé) : mot clé qui représente le paramètre dans la requête. Ce champ ne peut être modifié qu’en mettant à jour directement le texte dans la requête.

   • Display name (Nom d’affichage) : nom dans l’éditeur de filtre. Par défaut, le titre est identique au mot-clé.

   • Type : les types pris en charge sont String, Date, Date and Time, Numeric

     • Le type par défaut est String.
     • Le type de données Numeric vous permet de choisir entre Decimal et Integer. Le type numérique par défaut est Decimal.

   • Allow multiple selections (Autoriser plusieurs sélections) : cochez la case pour permettre aux utilisateurs de sélectionner plusieurs paramètres à l’exécution.

     Note

     Cette sélection peut nécessiter une modification supplémentaire de votre requête. Veuillez consulter la section Autoriser plusieurs sélections.

2. Cliquez dans une autre zone de l’interface utilisateur pour fermer la boîte de dialogue.

Définir une valeur par défaut pour un paramètre

Pour tester votre requête, tapez une valeur par défaut dans le champ de texte sous le nom du paramètre et exécutez la requête. Cela applique la valeur du paramètre pour que vous puissiez afficher un aperçu des résultats et confirmer que la requête s’exécute comme prévu. L’exécution de la requête permet également d’enregistrer la valeur par défaut.

Lorsque vous utilisez le paramètre dans un widget de filtre, la valeur par défaut de l’onglet Données est utilisée, sauf si le widget spécifie une valeur par défaut différente. Veuillez consulter la section Utiliser des filtres.

Les auteurs de tableaux de bord doivent confirmer que les requêtes paramétrables s’exécutent correctement avec les valeurs par défaut sélectionnées sous l’onglet jeu de données. Azure Databricks interroge le schéma du jeu de données pour remplir l’éditeur de configuration du widget. Dans certains cas, en particulier avec les requêtes paramétrables qui utilisent la IDENTIFIER clause, la requête de jeu de données peut échouer à s’exécuter avec les valeurs de paramètre par défaut, même si elle réussit 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 requête SQL qui vous permet de sélectionner plusieurs valeurs à insérer dans la requête à l’exécution. La clause WHERE utilise la fonction ARRAY_CONTAINS. Cette fonction prend en arguments le mot-clé du paramètre et le nom de la colonne. Le paramètre doit être défini pour contenir plusieurs valeurs afin qu’il puisse être inséré dans la requête en tant que tableau. Lorsque la requête s’exécute, chaque ligne est évaluée et toutes les lignes où l_quantity correspondent au moins une valeur :parameter sont incluses dans le jeu de résultats.

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

Pour définir les valeurs par défaut :

1. Écrivez une requête de jeu de données qui utilise la fonction ARRAY_CONTAINS pour filtrer les lignes en fonction d’une liste de valeurs.

2. Cliquez sur l'icône d'engrenage à côté du nom du paramètre. Sélectionnez Autoriser plusieurs sélections.

   Note

   Cette étape permet d’insérer le paramètre dans la requête en tant que tableau. Si la fonction ARRAY_CONTAINS est utilisée sans activer plusieurs sélections, une erreur se produit.

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

Appliquer des paramètres d’intervalle de dates

Vous pouvez utiliser des paramètres pour définir un intervalle et renvoyer uniquement les résultats compris dans cet intervalle. Lorsque vous choisissez l’un des types de paramètres suivants, vous créez deux paramètres désignés par les suffixes .min et .max :

• Plage de dates
• Intervalle de date et heure

L’exemple suivant montre une requête SQL qui crée un paramètre d’intervalle de date nommé date_param.

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

Pour créer un paramètre d’intervalle de date :

1. Cliquez sur Add parameter (Ajouter un paramètre).

2. Cliquez sur À côté du nom du paramètre. Saisissez le Mot-clé et le Nom d’affichage. N’incluez pas les suffixes .min ou .max.

3. Choisissez Date Range (Intervalle de date) ou Date and Time Range (Intervalle de date et heure) comme Type

4. Insérez une clause WHERE qui définit l’intervalle dans votre requête. Pour définir l’intervalle, utilisez une clause BETWEEN avec des valeurs .min et .max. Par exemple :

    WHERE date_col BETWEEN :date_param.min AND :date_param.max
   

5. Saisissez des valeurs de date par défaut et exécutez la requête 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.

Paramètres basés sur des requêtes

Les paramètres basés sur des requêtes permettent aux auteurs de définir une liste dynamique ou statique de valeurs parmi lesquelles les utilisateurs peuvent choisir lorsqu’ils définissent des paramètres pour explorer les 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 requête, l’auteur du tableau de bord effectue les étapes suivantes :

1. Créer un jeu de données dont le jeu de résultats est limité à une liste de valeurs de paramètre possibles.
2. Créer une requête de jeu de données qui utilise un paramètre.
3. Configurer un widget de filtre sur le canevas qui filtre un champ et utilise un paramètre.
   • La configuration des Champs doit être définie pour utiliser le champ contenant la liste souhaitée de valeurs éligibles du paramètre.
   • La configuration des Paramètres doit être définie pour sélectionner une valeur de paramètre.

Veuillez consulter la section Utiliser des paramètres basés sur des requêtes si vous souhaitez un tutoriel détaillé montrant comment ajouter un paramètre basé sur une requête et une visualisation.

Créer une liste de paramètres dynamiques

Pour créer un jeu de données dynamique qui alimente la liste déroulante que les utilisateurs utilisent pour sélectionner les valeurs de paramètre, rédigez une requête SQL qui renvoie un seul champ et inclut toutes les valeurs de ce champ. Toute nouvelle valeur de ce champ est automatiquement ajoutée comme sélection de paramètre. Un exemple de requête SQL est fourni ci-dessous :

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

Créer une liste de paramètres statiques

Vous pouvez créer un jeu de données statique qui n’inclut que les valeurs que vous avez codées en dur dans votre jeu de données. Un exemple de requête est fourni ci-dessous :

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 statique

Les paramètres de widget statique 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 jeu de données. Cela permet à un même jeu de données de présenter différentes vues sur le canevas.

L’exemple de cette section est basé sur un jeu de données qui interroge la table samples.nyctaxi.trips. La requête fournie renvoie la distance de chaque trajet et catégorise le jour de prise en charge comme étant Weekday ou Weekend. Le paramètre de requête filtre les résultats en fonction de si la prise en charge a eu lieu un jour de semaine ou en week-end.

Le texte de la requête est fourni dans le bloc de code ci-dessous, mais les instructions de cette section se limitent à la configuration des visualisations associées avec des paramètres de widget statique. Pour des instructions sur la configuration d’un jeu de données avec des paramètres, veuillez consulter la section Ajouter un paramètre à une requête.

  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 en cours de création.

2. Une fois le nouveau widget sélectionné, choisissez le jeu de données paramétré dans la liste déroulante Dataset (Jeu de données) du panneau de configuration.

3. Cliquez sur Show filters (Afficher les filtres). Pour les jeux de données incluant des paramètres, une section Parameters apparaît dans le panneau de configuration.

   

4. Cliquez sur le signe plus à droite de l’intitulé Parameters et choisissez un paramètre dans la liste déroulante.

5. Par défaut, la valeur du paramètre reflète ce qui est défini dans la requête de l’onglet Data (Données). Vous pouvez la conserver ou choisir une nouvelle valeur à insérer dans le jeu de données. Quittez le champ de texte pour afficher la visualisation avec le nouveau paramètre 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 trajets pour les trajets commencés en semaine, tandis que celui de droite montre les mêmes données pour le week-end. Les deux visualisations sont basées sur le même jeu de données.

   

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

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

L’exemple suivant étend la requête précédente en ajoutant une condition de filtre où la valeur spécifiée du paramètre est All, ce qui n’apparaît pas dans les données. La première partie de la condition de filtre fonctionne comme dans l’exemple précédent, filtrant les résultats lorsque day_type est soit Weekday soit Weekend. La seconde partie de la condition de filtre vérifie si le paramètre lui-même est défini sur une certaine valeur, ici All, qui n’apparaît pas dans les données. Lorsque vous définissez la valeur par défaut de ce paramètre dans l’éditeur de jeu de données, vous ignorez efficacement le filtre lorsque ni Weekday ne Weekend sont passés en tant que valeurs.

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'

Vous pouvez utiliser ce jeu de données pour configurer trois widgets de visualisation, avec la valeur de day_type_param définie respectivement sur All, Weekday et Weekend. Les utilisateurs du tableau de bord peuvent ensuite comparer chaque jeu de données filtré par type de jour à l’ensemble du jeu de données.

Le GIF suivant montre comment vous pouvez rapidement créer trois graphiques à partir du jeu de données créé avec cette requête.

1. Le premier graphique est configuré pour afficher le jeu de données Distances de trajets par type de jour avec une valeur de paramètre définie sur Weekday (Semaine).
2. Clonez 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 Weekend.
4. Clonez le nouveau graphique pour conserver toutes les configurations appliquées précédemment.
5. Définissez le paramètre dans le nouveau graphique sur All pour afficher le nombre total de trajets par distance pour les trajets du week-end et de la semaine.

Afficher les paramètres sur le tableau de bord

Ajouter un filtre à votre canevas de tableau de bord permet aux utilisateurs de sélectionner et de modifier les valeurs des paramètres pour explorer et analyser les données de manière interactive. Si vous n’exposez pas le paramètre sur le tableau de bord, les utilisateurs ne verront que les résultats de la requête utilisant la valeur par défaut définie dans la requête.

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

1. Cliquez sur Add a filter (field/parameter).
2. Cliquez sur à côté de Parameters dans le panneau de configuration.
3. Cliquez sur le nom du paramètre que vous souhaitez que l’utilisateur utilise avec ce widget.

Travailler avec des widgets de filtre et des paramètres statiques

Les paramètres sont des valeurs fixes insérées dans une requête à l’exécution. Si deux références ou plus à un même paramètre sont définies avec des valeurs différentes lors de la mise à jour de votre tableau de bord, les widgets de visualisation affichent une erreur indiquant quel paramètre présente des valeurs en conflit. 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 permettant la sélection par l’utilisateur.

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

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

Dans cet exemple, :static_param fait référence à un paramètre statique, qui doit être défini sur « All » dans le widget de visualisation et l’éditeur de jeu de données. 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 s’il existe une valeur définie en tant que paramètre statique. Si aucune valeur n’est définie, elle utilise à la place la valeur du paramètre sélectionné par l’utilisateur sur le tableau de bord.

Inclure des paramètres dans l’URL

Les paramètres de paramètres sont stockés dans l’URL, ce qui permet aux utilisateurs de les marquer pour maintenir l’état de leur tableau de bord, y compris les filtres et les paramètres prédéfinits, ou de les partager avec d’autres utilisateurs pour appliquer les mêmes filtres et paramètres de manière cohérente.

Paramètres de tableau de bord vs. paramètres de requête Mustache

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

Exemples de syntaxe

Les paramètres sont couramment utilisés pour 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 montrant comment utiliser les paramètres dans ces cas, veuillez consulter la section Exemples de syntaxe de paramètre nommé.