Parameter sind ein mächtiges Werkzeug, das in Data Explorer Abfragen in Discourse verwendet werden kann. Parameter ermöglichen dynamischere und anpassbarere Abfragen, und anstatt Werte fest in Ihre Abfragen zu kodieren, können Sie Variablen deklarieren, die bei Ausführung der Abfrage zur Eingabe auffordern.
Einen Parameter deklarieren
Um einen Parameter zu deklarieren, können Sie die folgende Syntax verwenden:
-- [params]
-- int :parameter_name = 10
Der Parameterabschnitt der Abfrage beginnt immer mit -- [params], gefolgt von jedem Parametertyp in einer neuen Zeile, wobei parameter_name durch den Namen für Ihren Parameter ersetzt wird.
Dadurch wird ein Feld erstellt, in das Sie bei jeder Ausführung der Abfrage unterschiedliche Werte eingeben können.
Parametertypen
Beim Deklarieren von Parametern in Ihren Data Explorer Abfragen können Sie verschiedene Eingabetypen angeben. Hier sind die verfügbaren Parametertypen und ihre Beschreibungen:
Numerische Parameter
int: Zeigt eine Zahleneingabe an, wird zu einem numerischen Wert.intist auf 32-Bit-Zahlen beschränkt.bigint: Ähnlich wieint, kann aber größer sein.double: Erlaubt Dezimalwerte.
Die Korrektheit der numerischen Parameter wird im Frontend überprüft.
String-Parameter
string: Freitextfeld, wird zu einem Textwert.
Listen-Parameter
int_list: Geben Sie durch Kommas getrennte Ganzzahlen ein, wird zu durch Kommas getrennten Ganzzahlen in der Abfrage.string_list: Ähnlich wieint_list, aber für Strings.
Spezifische ID-Parameter
post_id: Numerische Eingabe; stellt sicher, dass der angegebene Beitrag im Forum existiert, bevor die Abfrage ausgeführt wird.topic_id: Ähnlich wiepost_id, aber für Themen.badge_id: Stellt sicher, dass das angegebene Abzeichen existiert.
Boolesche Parameter
boolean: Zeigt ein Kontrollkästchen an.null boolean: Zeigt ein Dropdown-Menü an, das eine leere Eingabe zulässt.
Zeit-Parameter
time: Zeigt eine Zeitauswahl an.date: Zeigt eine Datumsauswahl an.datetime: Zeigt ein Eingabefeld an, das sowohl Datum als auch Uhrzeit enthält.
Auswahl-Parameter
user_id: Zeigt das Discourse-Benutzerauswahlfeld an und wird zur numerischen Benutzer-ID.user_list: Ähnlich wieuser_id, erlaubt aber mehrere Benutzer und wird zu einer durch Kommas getrennten Liste numerischer Benutzer-IDs.group_id: Ähnlich wieuser_id, aber für Gruppen.group_list: Ähnlich wieuser_list, aber für Gruppen.category_id: Ähnlich wieuser_id, aber für Kategorien.
Interne Parameter
current_user_id: Keine Eingabe-UI; setzt die Variable automatisch auf die Benutzer-ID des Benutzers, der die Abfrage ausführt
Verwendung von Listen-Parametern
Bei der Verwendung von Listen-Parametern (int_list, string_list, user_list) ist besondere Sorgfalt geboten, um Syntaxfehler zu vermeiden. Hier ist ein Beispiel für die korrekte Verwendung eines Listen-Parameters:
-- [params]
-- user_list :the_user_ids
SELECT SUM(length(bio_raw))
FROM user_profiles
WHERE user_id IN (:the_user_ids)
Null-Parameter
Sie können auch eine leere Eingabe zulassen, indem Sie dem Parametertyp ein null voranstellen. Das bedeutet, dass bei Ausführung der Abfrage kein Wert für diesen Parameter angegeben werden muss.
Hier sind einige Beispiele, wie Sie solche Parameter deklarieren könnten:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
-- null current_user_id :me
In der obigen SQL-Anweisung sind null_int, null_boolean und null_string Parameter, die bei Ausführung der Abfrage leer gelassen werden können.
Sehen wir uns an, wie diese Arten von Parametern in einer Abfrage verwendet werden können:
-- [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)
In dieser Abfrage ignoriert die Abfrage diesen Teil der WHERE-Klausel, wenn post_id oder username nicht angegeben wird (d. h. als null belassen wird). Dies ermöglicht flexiblere Abfragen, bei denen einige Bedingungen optional sind.
Frontend-Validierung
Die meisten Parametertypen werden im Frontend validiert. Diese Validierungen umfassen erforderliche, aber nicht ausgefüllte Eingaben, ungültige numerische Eingaben, nicht existierende Kategorien oder Gruppen, fehlerhafte Zeitangaben usw. Bei ungültiger Eingabe wird der Grund für den Fehler im Formular angezeigt, und die Abfrageausführung wird abgelehnt.
Zusätzliche Beispiele
Hier sind einige zusätzliche Beispiele für die Deklaration verschiedener Parametertypen:
-- [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
