Aller au contenu principal
Dernière mise à jour le

Travailler avec les widgets de parameter

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

Les widgets de parameter sont pris en charge dans l’éditeur SQL, les notebooks, les tableaux de bord AI/BI et les Agents Genie, mais leur comportement varie selon ces interfaces. Cette page décrit les widgets de parameter dans l’éditeur SQL. Pour les autres domaines, consultez :

Dans l'éditeur SQL, tout type de parameter (String, Integer, Decimal, Date, Timestamp) peut utiliser n'importe quel type de widget.

Syntaxe des paramètres dans le nouvel éditeur SQL​

Le nouvel éditeur SQL utilise la syntaxe des paramètres nommés, la même syntaxe utilisée par d'autres outils Databricks comme les tableaux de bord AI/BI, les agents Genie et les notebooks. Les paramètres nommés sont précédés d'un signe deux-points, par exemple :parameter_name. Consultez les marqueurs de paramètres nommés pour la documentation de référence SQL.

Vous devez modifier les requêtes écrites dans l'éditeur SQL hérité qui utilisent des doubles accolades ( {{}} ) pour marquer les paramètres avant de pouvoir les exécuter dans le nouvel éditeur SQL. Consultez Exemples de syntaxe des paramètres nommés pour des exemples de conversion de la syntaxe des paramètres de l'éditeur SQL hérité vers les marqueurs de paramètres nommés.

Configurez un widget de parameter​

  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 en forme d'engrenage à côté du widget pour ouvrir la boîte de dialogue du widget.

    Paramètres du widget avec des champs pour le nom du paramètre, l'étiquette du widget, le type de widget, le type de paramètre et la valeur de paramètre default.

  3. Définissez les champs suivants :

    • Nom du parameter : Le nom du parameter tel qu'il apparaît dans la query. Si vous modifiez le nom du parameter, dans la boîte de dialogue du widget, vous devez également le modifier dans la query.
    • **Libellé du widget** : une chaîne qui décrit le widget
    • Type de widget : Contrôle la manière dont les utilisateurs saisissent la valeur. Voir les types de widget ci-dessous.
    • **Type de paramètre** : Le type de données du paramètre. Voir 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 les widgets​

Modifier : cliquez sur l'icône en forme d'engrenage à côté du widget pour rouvrir le volet des 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 glissement à gauche d’un widget pour le réorganiser.

Types de widgets​

Databricks prend en charge les types de widgets suivants pour les query parameters :

Type de widget

Description

Menu déroulant

Les utilisateurs doivent choisir à partir d’une liste prédéfinie.

Boîte combinée

Les utilisateurs peuvent choisir parmi une liste prédéfinie ou saisir une valeur personnalisée.

Saisie de texte

Accepte toute valeur de forme libre sans suggestion.

Sélection multiple

Les utilisateurs peuvent sélectionner plus d'une valeur dans une liste prédéfinie.

Menu déroulant dynamique

Renseigne les choix à partir d'une query enregistrée au lieu d'une liste statique.

Plage de date et de Timestamp

Définit une plage de start et de fin à l’aide des paramètres .min et .max.

Type de widget

Description

Menu déroulant

Les utilisateurs doivent choisir à partir d’une liste prédéfinie.

Boîte combinée

Les utilisateurs peuvent choisir parmi une liste prédéfinie ou saisir une valeur personnalisée.

Saisie de texte

Accepte toute valeur de forme libre sans suggestion.

Sélection multiple

Les utilisateurs peuvent sélectionner plus d'une valeur dans une liste prédéfinie.

Menu déroulant dynamique

Renseigne les choix à partir d'une query enregistrée au lieu d'une liste statique.

Plage de date et de Timestamp

Définit une plage de start et de fin à l’aide des paramètres .min et .max.

Saisie de texte​

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

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

Présente une liste de valeurs prédéfinie. Les utilisateurs doivent sélectionner dans la liste — la saisie libre n'est pas autorisée. Saisissez les valeurs autorisées dans le volet des paramètres, une par ligne.

SQL
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 widget :status_param.
  2. Définissez le **type de widget** sur **liste déroulante**.
  3. Définissez le **type de paramètre** sur **Chaîne**.
  4. Saisissez les valeurs dans le champ de saisie de texte Choix pour la valeur du paramètre . Cliquez sur Ajouter ou appuyez sur Entrée entre chaque valeur.

Boîte combinée​

Présente une liste prédéfinie de valeurs suggérées, mais permet également aux utilisateurs de saisir une valeur personnalisée ne figurant pas dans la liste. Utilisez une boîte combinée lorsque des options courantes sont utiles par commodité, mais que vous souhaitez autoriser la saisie de texte libre.

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

Sélection multiple​

Permet aux utilisateurs de sélectionner plusieurs valeurs à partir d'une liste prédéfinie. Les valeurs sélectionnées sont transmises à la requête sous forme de collection.

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

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

  1. Cliquez sur l'icône d'engrenage à côté du widget list_parameter.
  2. Définissez **Type de widget** sur **Sélection multiple**.
  3. Définissez le **type de paramètre** sur **Chaîne**.
  4. Saisissez les valeurs dans le champ de saisie de texte Choix pour la valeur du paramètre . Cliquez sur Ajouter ou appuyez sur Entrée entre chaque valeur.
remarque

Les widgets déroulants dynamiques sont disponibles uniquement dans l'éditeur SQL, pas dans les notebooks.

Remplit la liste de choix à partir d'une query enregistrée au lieu d'une liste statique. À mesure que les données sous-jacentes changent, les options disponibles se mettent à jour automatiquement.

Pour utiliser un menu déroulant dynamique :

  1. Créez et enregistrez une requête qui renvoie les valeurs que vous souhaitez dans la liste déroulante :

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

  2. Dans une query nouvelle ou existante, ajoutez un marqueur de parameter nommé :

    SQL
    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 widget segment_param.

  4. Définissez Type de widget sur Liste déroulante dynamique .

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

  6. Choisissez une default parameter value .

  7. Cliquez sur **Appliquer les modifications**.

remarque

Une liste déroulante dynamique affiche un maximum de 1 024 valeurs. Si la **query** enregistrée renvoie plus de 1 024 valeurs, le widget n’affiche que les 1 024 premières et n’affiche pas le reste.

Plage de dates et de Timestamp​

Les parameters Date et Timestamp prennent en charge un type de widget Range . Une fois sélectionné, Databricks crée deux parameters à l'aide des suffixes .min et .max pour définir le start et la fin de la plage.

SQL
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 de l'éclair bleu pour sélectionner des valeurs dynamiques telles que today, yesterday, this week, last week, last month ou last year. Ces valeurs sont mises à jour automatiquement.

important

Les valeurs de date dynamiques ne sont pas compatibles avec les query planifiées.

Sur cette page