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 pouvez saisir différentes valeurs à chaque fois que vous exécutez 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 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: Permet les valeurs décimales.
La validité 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 de texte.
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 ; s’assure que le post spécifié existe sur le forum avant d’exécuter la requête.topic_id: Similaire àpost_id, mais pour les sujets.badge_id: S’assure 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électeur
user_id: Affiche la boîte de sélecteur d’utilisateur Discourse et devient l’ID utilisateur numérique.user_list: Similaire àuser_id, mais permet plusieurs utilisateurs, devenant une liste d’ID utilisateurs numériques 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.
Paramètres internes
current_user_id: Pas d’interface de saisie ; définit automatiquement la variable à l’ID utilisateur 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 nuls
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 manière de 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é sur null), la requête ignorera cette partie de la clause WHERE. Cela permet des requêtes plus flexibles où certaines conditions sont optionnelles.
Validation côté client
La plupart des types de paramètres seront validés côté client. Ces validations incluent les saisies obligatoires mais non remplies, les saisies numériques invalides, les catégories ou groupes inexistants, les heures mal formé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.
Choix des types et utilisation des casts
En général, les paramètres devraient « fonctionner » dans vos requêtes. Pour les cas plus avancés, vous devrez peut-être ajouter un cast explicite ::type.
Par exemple, pour les intervalles, vous devez déclarer un paramètre de chaîne de caractères et le caster en intervalle. Les valeurs peuvent inclure des unités, telles que 2 day ou 3 hours :
-- [params]
-- string :lookback = 2 day
SELECT id AS topic_id, created_at
FROM topics
WHERE created_at >= NOW() - :lookback::interval
Certaines fonctions ont également besoin de types d’arguments explicites :
round(amount::numeric, :decimal_places::integer)
date_trunc('day', :start_date::timestamp)
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
