Partager via

Utiliser des widgets de paramètres

Lorsque vous ajoutez un marqueur de paramètre nommé à une requête, Azure Databricks affiche un widget de paramètre dans l’interface utilisateur. Les widgets permettent aux utilisateurs de définir des valeurs de paramètre sans modifier directement la requête. Vous pouvez configurer le type, le titre et la valeur par défaut de chaque widget.

Les widgets de paramètres sont pris en charge dans l’éditeur SQL, les notebooks, les tableaux de bord IA/BI et les espaces Genie, mais se comportent différemment sur ces surfaces. Cette page décrit les widgets de paramètres dans l’éditeur SQL. Pour d’autres surfaces, consultez :

Dans l’éditeur SQL, n’importe quel type de paramètre (String, Integer, Decimal, Date, Timestamp) peut utiliser n’importe quel type de widget.

Configurer un widget de paramètre

  1. Ajoutez un marqueur de paramètre nommé à votre requête. Un widget apparaît dans l’interface utilisateur.
  2. Cliquez sur l’icône d’engrenage en regard du widget pour ouvrir la boîte de dialogue du widget. Boîte de dialogue Créer un widget
  3. Définissez les champs suivants :
    • Nom du paramètre : nom du paramètre tel qu’il apparaît dans la requête. Si vous modifiez le nom du paramètre, dans la boîte de dialogue du widget, vous devez également le modifier dans la requête.
    • Étiquette du widget : chaîne qui a décrit le widget
    • Type de widget : contrôle la façon dont les utilisateurs entrent la valeur. Consultez les types de widgets ci-dessous.
    • Type de paramètre : type de données de paramètre. Consultez les types de paramètres.
  4. Cliquez en dehors de la boîte de dialogue du widget pour enregistrer vos modifications.

Modifier, supprimer et réorganiser des widgets

Modifier : cliquez sur l’icône d’engrenage en regard du widget pour rouvrir le volet paramètres.

Supprimer : supprimez le marqueur de paramètre de la requête. Le widget est supprimé automatiquement.

Réorganiser : utilisez la poignée de glisser à gauche d’un widget pour réorganiser.

Types de widgets

Azure Databricks prend en charge les types de widgets suivants pour les paramètres de requête :

Type de widget Description
Liste déroulante Les utilisateurs doivent choisir parmi une liste prédéfinie.
Combobox Les utilisateurs peuvent choisir parmi une liste prédéfinie ou taper une valeur personnalisée.
Entrée de texte Accepte n’importe quelle valeur de forme libre sans suggestions.
Multiselect Les utilisateurs peuvent sélectionner plusieurs valeurs dans une liste prédéfinie.
Liste déroulante dynamique Remplit les choix d’une requête enregistrée au lieu d’une liste statique.
Plage de date et d'horodatage Définit une plage de début et de fin à l’aide de paramètres .min et .max.

Entrée de texte

Accepte une valeur de formulaire libre directement de l’utilisateur. Utilisez ce widget quand aucune option prédéfinie n’est nécessaire.

SELECT * FROM samples.tpch.region WHERE r_name = :region_param

Présente une liste prédéfinie de valeurs. Les utilisateurs doivent sélectionner dans la liste : l’entrée libre n’est pas autorisée. Entrez les valeurs autorisées dans le volet paramètres, une par ligne.

SELECT * FROM samples.tpch.orders WHERE o_orderstatus = :status_param

Pour créer un type de widget déroulant :

  1. Cliquez sur l’icône d’engrenage à côté du :status_param widget.
  2. Définissez le type de widget sur Liste déroulante.
  3. Définissez le type de paramètre sur String.
  4. Entrez des valeurs dans le champ de saisie de texte Choix pour la valeur de paramètre. Cliquez sur Ajouter ou appuyer sur Entrée entre chaque valeur.

Zone de liste modifiable

Présente une liste prédéfinie de valeurs suggérées, mais permet également aux utilisateurs de taper une valeur personnalisée non dans la liste. Utilisez un combobox lorsque les options courantes sont utiles pour des raisons pratiques, mais que vous souhaitez permettre une saisie libre.

SELECT * FROM samples.tpch.part WHERE p_brand = :brand_param

Sélection multiple

Permet aux utilisateurs de sélectionner plusieurs valeurs dans une liste prédéfinie. Les valeurs sélectionnées sont passées à la requête en tant que collection.

SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    CAST(dropoff_zip AS STRING)
  )

Pour ajouter des options pour une liste déroulante à sélection multiple :

  1. Cliquez sur l’icône d’engrenage à côté du list_parameter widget.
  2. Définissez le type de widget sur Multiselect.
  3. Définissez le type de paramètre sur String.
  4. Entrez des valeurs dans le champ de saisie de texte Choix pour la valeur de paramètre. Cliquez sur Ajouter ou appuyer sur Entrée entre chaque valeur.

Liste déroulante dynamique

Note

Les widgets de liste déroulante dynamique sont disponibles uniquement dans l’éditeur SQL, et non dans les notebooks.

Remplit la liste des choix d’une requête enregistrée au lieu d’une liste statique. À mesure que les données sous-jacentes changent, les options disponibles sont mises à jour automatiquement.

Pour utiliser une liste déroulante dynamique :

  1. Créez et enregistrez une requête qui retourne les valeurs souhaitées dans la liste déroulante :

    SELECT DISTINCT c_mktsegment FROM samples.tpch.customer ORDER BY c_mktsegment

  2. Dans une requête nouvelle ou existante, ajoutez un marqueur de paramètre nommé :

    SELECT c_custkey, c_name, c_acctbal
FROM samples.tpch.customer
WHERE c_mktsegment = :segment_param

  3. Cliquez sur l’icône d’engrenage à côté du segment_param widget.

  4. Définissez le type de widget sur Dynamic dropdown.

  5. Cliquez sur le champ Requête pour ouvrir la boîte de dialogue Sélectionner une requête existante . Sélectionnez la requête enregistrée à l’étape 1, puis cliquez sur Sélectionner.

  6. Choisissez une valeur de paramètre par défaut.

  7. Cliquez sur Appliquer les modifications.

Plage de dates et d'horodatages

Les paramètres Date et Timestamp prennent en charge un type de widget Range . Lorsqu’il est sélectionné, Azure Databricks crée deux paramètres à l’aide des suffixes .min et .max pour définir le début et la fin de la plage.

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN CAST(:date_range_min AS TIMESTAMP) AND CAST(:date_range_max AS TIMESTAMP)

Cliquez sur l’icône éclair bleu pour sélectionner des valeurs dynamiques telles que today, , yesterdaythis week, last week, , last monthou last year. Ces valeurs sont mises à jour automatiquement.

Important

Les valeurs de date dynamique ne sont pas compatibles avec les requêtes planifiées.

  • Last updated on