Partager via

Utiliser les paramètres de tableau de bord

  • Article

Le présent article décrit comment utiliser les paramètres de tableaux de bord IA/BI. Si vous souhaitez en savoir plus sur les filtres de champ, consultez Filtrer sur les champs.

Les paramètres du tableau de bord AI/BI vous permettent de substituer différentes valeurs dans les requêtes d’ensembles de données au moment de l’exécution. Cela vous permet de filtrer les données en fonction de 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 permet d’effectuer des requêtes plus efficaces et des analyses plus précises. 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 l’espace 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 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 au moment de l’exécution. Cette interaction permet de réexécuter les requêtes associées et d’afficher des visualisations basées sur les données filtrées.

Les paramètres modifient directement la requête, ce qui peut être puissant. Les filtres du champ de jeu de données peuvent également proposer une interactivité de tableau de bord, davantage de fonctionnalités et de meilleures performances relatives aux jeux de données volumineux à la différence des paramètres. Consultez Utiliser des filtres.

Ajouter un paramètre à une requête

Vous devez disposer au moins de l’autorisation CAN EDIT sur le tableau de bord brouillon pour ajouter un paramètre à un jeu de données du tableau de bord. Vous pouvez ajouter des paramètres directement aux requêtes de jeu de données sous l’onglet Données.

Gif montrant un exemple des étapes suivantes.

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

  1. Placez votre curseur à l’endroit où vous souhaitez placer 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 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 tapant cette syntaxe dans l’éditeur de requête.

Modifier un paramètre de requête

Pour modifier un paramètre :

  1. Cliquez sur icône Engrenage à côté du nom du paramètre. Une boîte de dialogue Détails des paramètres s’affiche et inclut les options de configuration suivantes :

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

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

    • Type : les types pris en charge incluent Chaîne, Date, Date et heure, Numérique.

      • Le type par défaut est Chaîne.
      • Le type de données Numérique vous permet de spécifier entre Décimal et Entier. Le type numérique par défaut est Décimal.

    • Autoriser plusieurs sélections : cochez la case pour autoriser les utilisateurs à choisir plusieurs paramètres au moment de l’exécution.

      Remarque

      Cette sélection peut nécessiter une modification supplémentaire de votre requête. 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 par défaut

Pour que votre requête s’exécute, choisissez une valeur par défaut pour votre paramètre en la saisissant dans le champ de texte situé sous le nom du paramètre. Exécutez la requête pour prévisualiser les résultats de la requête avec la valeur du paramètre appliquée. L’exécution de la requête enregistre également la valeur par défaut. Lorsque vous définissez ce paramètre à l’aide d’un widget de filtre sur le canevas, la valeur par défaut est utilisée, sauf si une nouvelle valeur par défaut est spécifiée dans le widget de filtre. Consultez Utiliser des filtres.

Autoriser plusieurs sélections

Les requêtes qui autorisent plusieurs sélections doivent inclure une ARRAY_CONTAINS fonction 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 au moment de l’exécution. La WHERE clause utilise la ARRAY_CONTAINS fonction. Cette fonction prend le mot clé de paramètre et le nom de colonne comme arguments. Lorsque la requête s’exécute, elle retourne toutes les lignes contenant les valeurs de paramètre sélectionnées.

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

Pour définir les valeurs par défaut, tapez-les dans le champ de texte sous le nom d’affichage. Sélectionnez la valeur actuelle avant d’entrer la valeur suivante.

Les valeurs par défaut sont définies dans l’éditeur. Plusieurs valeurs sont sélectionnées et séparées par un espace.

Appliquer des paramètres de plage de dates

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

  • Plage de dates
  • Intervalle de date et d’heure

L’exemple suivant montre une requête SQL qui crée un paramètre de plage de dates 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 de plage de dates :

  1. Cliquez sur Ajouter un paramètre.

  2. Cliquez sur icône Engrenage à côté du nom du paramètre. Entrez le mot clé et le nom d’affichage. N’incluez .min pas de .max suffixes.

  3. Choisissez plage de dates ou plage de date et d’heure comme type.

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

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

  5. Entrez les valeurs de date par défaut et exécutez la requête pour la tester. Utilisez l’icône 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 créateurs de définir une liste de valeurs statiques ou dynamiques parmi lesquelles les viewers peuvent choisir lorsqu’ils définissent des paramètres lors de leur exploration de données dans un tableau de bord. Ils sont définis en associant un filtre de champ et un filtre de paramètre dans un seul widget de filtre.

Pour créer un paramètre basé sur des requêtes, le créateur 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 possibles de paramètre.
  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 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 des valeurs de paramètre éligibles.
    • La configuration de Paramètres doit être définie pour sélectionner une valeur de paramètre.

Remarque

Si un jeu de données utilisé dans des paramètres basés sur des requêtes est également utilisé dans d’autres visualisations sur un tableau de bord, la sélection de filtre d’un viewer modifie toutes les requêtes connectées. Pour éviter ceci, les créateurs doivent créer un jeu de données dédié pour des paramètres basés sur des requêtes qui n’est pas utilisé dans d’autres visualisations sur le tableau de bord.

Consultez Utiliser des paramètres basés sur des requêtes pour obtenir un tutoriel étape par étape qui montre comment ajouter une visualisation et un paramètre basé sur des requêtes.

Créer une liste de paramètres dynamiques

Pour créer un jeu de données dynamiques qui renseigne la liste déroulante utilisée par des viewers pour sélectionner des valeurs de paramètre, écrivez une requête SQL qui retourne un seul champ et inclut toutes les valeurs dans ce champ. Toute nouvelle valeur de ce champ est automatiquement ajoutée en tant que sélection de paramètre. Un exemple de requête SQL se présente comme suit :

 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 inclut uniquement les valeurs que vous codez en dur dans votre jeu de données. Un exemple de requête se présente comme suit :

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, ce qui permet aux auteurs de paramétrer individuellement les widgets de visualisation qui partagent le même jeu de données. Cela permet au 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 samples.nyctaxi.trips table. La requête fournie renvoie la distance de chaque trajet et catégorise le jour de prise en charge comme étant soit Weekday soit Weekend. Le paramètre de requête filtre les résultats en fonction de la date ou du week-end de la prise en charge.

Le texte de la requête est fourni dans le bloc de code suivant, mais les instructions de cette section se limitent à la mise en place des visualisations associées configurées avec les paramètres statiques du widget. Pour obtenir des instructions sur la configuration d’un jeu de données avec des paramètres, consultez 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 à l’espace de tableau de bord brouillon.

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

  3. Cliquez sur Afficher les filtres. Pour les jeux de données qui incluent des paramètres, une section Paramètres s’affiche dans le panneau de configuration.

    Panneau de configuration de visualisation montrant l’option permettant de choisir un analyseur.

  4. Cliquez sur le signe plus à droite du titre Paramètres 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 sous l’onglet Données. Vous pouvez le conserver ou choisir une nouvelle valeur à remplacer dans le jeu de données. Quittez le champ de texte pour afficher la visualisation avec le nouveau paramètre appliqué.

  6. Examinez votre tableau de bord.

    L’image suivante montre deux widgets de visualisation. Chacun est configuré en tant qu’histogramme avec un paramètre de widget statique. Le graphique à gauche montre la distribution des distances de trajet pour les voyages à partir des jours de la semaine, tandis que le graphique à droite affiche les mêmes données pour les week-ends. Les deux visualisations sont basées sur le même jeu de données.

    Deux histogrammes, configurés pour utiliser des paramètres statiques au niveau du widget, comme décrit.

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

Vous pouvez ajouter une condition de filtre qui vous permet de comparer les agrégations de la 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 pour inclure une condition de filtre où la valeur de paramètre spécifiée 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 façon que dans l’exemple précédent, le filtrage pour les résultats où l’est day_type 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 défaut de ce paramètre dans l’éditeur de jeu de données, vous ignorez efficacement le filtre lorsque ni Weekday ni 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 day_type_param défini sur All, Weekday et Weekend respectivement. Ensuite, les visionneuses de tableaux de bord peuvent comparer chaque jeu de données filtré par type de jour à l’ensemble du jeu de données.

L’image GIF suivante montre comment créer rapidement 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 par type de jour avec une valeur de paramètre définie sur semaine.
  2. Clonez le graphique pour conserver toutes les configurations appliquées.
  3. Pour afficher les données des voyages 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 paramètre du nouveau graphique sur Tous pour afficher le nombre total de trajets par distance pour les trajets du week-end et des jours de la semaine.

Gif comme décrit dans le texte précédent.

Afficher les paramètres sur le tableau de bord

L’ajout d’un filtre à votre canevas de tableau de bord permet aux visionneuses de sélectionner et de modifier des valeurs de 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 visionneuses voient uniquement les résultats de la requête qui utilisent la valeur de paramètre par défaut que vous définissez dans la requête.

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

  1. Cliquez sur Icône de filtre Ajouter un filtre (champ/paramètre).
  2. Cliquez sur icône d’ajout de champ à côté de Paramètres dans le panneau de configuration.
  3. Cliquez sur le nom du paramètre que vous souhaitez que la visionneuse utilise avec ce widget.

Utilisation des widgets de filtre et des paramètres statiques

Les paramètres sont des valeurs fixes remplacées dans une requête 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 est mis à jour, les widgets de visualisation renvoient une erreur indiquant quel paramètre a 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 est en conflit avec un widget de filtre qui autorise la sélection de la visionneuse.

Vous pouvez utiliser un modèle comme celui de l’exemple suivant pour définir des valeurs de secours 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 l’espace du tableau de bord. Cette instruction recherche une valeur fournie en tant que paramètre statique. Si aucune n’est défini, elle revient à une valeur de paramètre de tableau de bord sélectionnée par la visionneuse.

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 du tableau de bord et paramètres de requête en boîte à moustaches

Les paramètres du tableau de bord utilisent la même syntaxe que les marqueurs de paramètres nommés. Consultez Marqueurs de paramètres nommés. Les tableaux de bord ne prennent pas en charge les paramètres de style en boîte à moustaches.

Exemples de syntaxe

Les paramètres sont couramment utilisés pour insérer des dates, des nombres, du texte, des objets de base de données et des valeurs provenant de chaînes JSON. Pour plus d’exemples illustrant la manière d’utiliser les paramètres dans les cas susmentionnés, consultez Exemples de syntaxe des paramètres nommés

Important

Permettre aux utilisateurs d’accéder aux données via des sélections de paramètres comme les noms de tables ou de catalogues peut entraîner une exposition accidentelle d’informations sensibles. Si vous publiez un tableau de bord avec ces options, Azure Databricks recommande de ne pas incorporer d’informations d’identification dans le tableau de bord publié.