Les paramètres sont un outil puissant qui peut être utilisé dans les requêtes Data Explorer 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 lors de l’exécution de la requête.
Déclaration d’un paramètre
Pour déclarer un paramètre, vous pouvez utiliser la syntaxe suivante :
-- [params]
-- int :parameter_name = 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ù parameter_name sera remplacé par le nom de votre paramètre.
Cela créera un champ où vous pourrez saisir différentes valeurs chaque fois que vous exécuterez la requête.
Types de paramètres
Lors de la déclaration de paramètres dans vos requêtes Data Explorer, vous pouvez spécifier différents types de saisies. 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 de 32 bits.bigint: Similaire àint, mais peut être plus grand.double: Permet les valeurs décimales.
L’exactitude des paramètres numériques sera vérifiée côté client.
Paramètres de chaîne de caractères
string: Zone de texte libre, devient une valeur textuelle.
Paramètres de liste
int_list: Saisissez 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’identifiant spécifique
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 l’insigne spécifié existe.
Paramètres booléens
boolean: Affiche une case à cocher.null boolean: Affiche une liste déroulante, permettant une saisie vide.
Paramètres temporels
time: Affiche une saisie de sélecteur d’heure.date: Affiche une saisie de sélecteur de date.datetime: Affiche une zone de saisie incluant la date et l’heure.
Paramètres de sélection
user_id: Affiche la boîte de sélection d’utilisateur Discourse, et devient l’identifiant numérique de l’utilisateur.user_list: Similaire àuser_id, mais permet plusieurs utilisateurs, devenant une liste d’identifiants numériques d’utilisateurs séparés par des virgules.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.
Utilisation des paramètres de liste
Lors de l’utilisation de paramètres de liste (int_list, string_list, user_list), des précautions particulières doivent être prises 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 nuls
Vous pouvez également autoriser une saisie vide en préfixant le type de paramètre avec 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 manière dont vous déclareriez de tels paramètres :
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
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
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. En cas de 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
