Les paramètres sont un outil puissant qui peut être utilisé dans les requêtes de l’Explorateur de données sur Discourse. Les paramètres permettent des requêtes plus dynamiques et personnalisables, et au lieu de coder en dur des valeurs dans vos requêtes, vous pouvez déclarer des variables qui demanderont une saisie lorsque la requête sera exécutée.
Déclaration d’un paramètre
Pour déclarer un paramètre, vous pouvez utiliser la syntaxe suivante :
-- [params]
-- int :nom_du_paramètre = 10
La section des paramètres de la requête commencera toujours par -- [params], suivie de chaque type de paramètre sur une nouvelle ligne, où nom_du_paramètre sera remplacé par le nom de votre paramètre.
Ceci créera un champ où vous pourrez saisir différentes valeurs à chaque exécution de la requête.
Types de paramètres
Lors de la déclaration de paramètres dans vos requêtes d’Explorateur de données, vous pouvez spécifier différents types de saisie. Voici les types de paramètres disponibles et leurs descriptions :
Paramètres numériques
int: Affiche une saisie numérique, devient une valeur numérique.intest limité aux nombres sur 32 bits.bigint: Similaire àint, mais peut être plus grand.double: Autorise les valeurs décimales.
L’exactitude des paramètres numériques sera vérifiée côté client (front end).
Paramètres de chaîne (String)
string: Zone de texte libre, devient une valeur textuelle.
Paramètres de liste
int_list: Saisir des entiers séparés par des virgules, devient des entiers séparés par des virgules dans la requête.string_list: Similaire àint_list, mais pour les chaînes de caractères.
Paramètres d’ID spécifiques
post_id: Saisie numérique ; garantit que le message spécifié existe sur le forum avant d’exécuter la requête.topic_id: Similaire àpost_id, mais pour les sujets.badge_id: Garantit que le badge spécifié existe.
Paramètres booléens
boolean: Affiche une case à cocher.null boolean: Affiche un menu déroulant, permettant une saisie vide.
Paramètres de temps
time: Affiche un sélecteur d’heure.date: Affiche un sélecteur de date.datetime: Affiche une boîte de saisie incluant à la fois la date et l’heure.
Paramètres de sélection (Selector)
user_id: Affiche la boîte de sélection d’utilisateur de Discourse, et devient l’ID utilisateur numérique.user_list: Similaire àuser_id, mais permet plusieurs utilisateurs, devenant une liste séparée par des virgules des ID utilisateurs numériques.group_id: Similaire àuser_id, mais pour les groupes.group_list: Similaire àuser_list, mais pour les groupes.category_id: Similaire àuser_id, mais pour les catégories.
Paramètres internes
current_user_id: Aucune interface utilisateur de saisie ; définit automatiquement la variable sur l’ID de l’utilisateur exécutant la requête
Utilisation des paramètres de liste
Lors de l’utilisation de paramètres de liste (int_list, string_list, user_list), une attention particulière doit être portée pour éviter les erreurs de syntaxe. Voici un exemple d’utilisation correcte d’un paramètre de liste :
-- [params]
-- user_list :the_user_ids
SELECT SUM(length(bio_raw))
FROM user_profiles
WHERE user_id IN (:the_user_ids)
Paramètres Null
Vous pouvez également autoriser une saisie vide en préfixant le type de paramètre par null. Cela signifie qu’il n’est pas nécessaire de fournir une valeur pour ce paramètre lors de l’exécution de la requête.
Voici quelques exemples de la façon dont vous pourriez déclarer de tels paramètres :
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
-- null current_user_id :me
Dans le SQL ci-dessus, null_int, null_boolean et null_string sont des paramètres qui peuvent être laissés vides lors de l’exécution de la requête.
Voyons comment ces types de paramètres peuvent être utilisés dans une requête :
-- [params]
-- null int :post_id
-- null string :username
SELECT *
FROM users
WHERE (id = :post_id OR :post_id IS NULL)
AND (username = :username OR :username IS NULL)
Dans cette requête, si post_id ou username n’est pas fourni (c’est-à-dire laissé comme null), la requête ignorera cette partie de la clause WHERE. Cela permet des requêtes plus flexibles où certaines conditions sont facultatives.
Validation côté client (Front-end Validation)
La plupart des types de paramètres seront validés côté client. Ces validations incluent les saisies requises mais non remplies, les saisies numériques invalides, les catégories ou groupes inexistants, les heures mal formatées, etc. Pour une saisie invalide, la raison de l’erreur sera affichée dans le formulaire, et l’opération d’exécution de la requête sera rejetée.
Exemples supplémentaires
Voici quelques exemples supplémentaires de déclaration de différents types de paramètres :
-- [params]
-- int :int = 3
-- bigint :bigint = 12345678912345
-- boolean :boolean
-- null boolean :boolean_three = #null
-- string :string = little bunny foo foo
-- date :date = 14 jul 2015
-- time :time = 5:02 pm
-- datetime :datetime = 14 jul 2015 5:02 pm
-- double :double = 3.1415
-- string :inet = 127.0.0.1/8
-- user_id :user_id = system
-- post_id :post_id = http://localhost:3000/t/adsfdsfajadsdafdsds-sf-awerjkldfdwe/21/1?u=system
-- topic_id :topic_id = /t/-/21
-- int_list :int_list = 1,2,3
-- string_list :string_list = a,b,c
-- category_id :category_id = meta
-- group_id :group_id = admins
-- user_list :mul_users = system,discobot
-- current_user_id :me
