Parameter sind ein mächtiges Werkzeug, das in Data Explorer Abfragen auf Discourse verwendet werden kann. Parameter ermöglichen dynamischere und anpassbarere Abfragen. Anstatt Werte fest in Ihre Abfragen zu kodieren, können Sie Variablen deklarieren, die bei der Ausführung der Abfrage zur Eingabe auffordern.
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 Ihres Parameters ersetzt wird.
Dies erstellt ein Feld, in das Sie jedes Mal, wenn Sie die Abfrage ausführen, unterschiedliche Werte eingeben können.
Parametertypen
Bei der Deklaration 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, aber kann größer sein.double: Ermöglicht Dezimalwerte.
Die Korrektheit der numerischen Parameter wird im Frontend überprüft.
String-Parameter
string: Freitextfeld, wird zu einem Textwert.
Listenparameter
int_list: Komma-separierte ganze Zahlen eingeben, wird zu kommagetrennten ganzen Zahlen 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 die angegebene Auszeichnung existiert.
Boolesche Parameter
boolean: Zeigt eine Checkbox an.null boolean: Zeigt ein Dropdown an, das eine leere Eingabe ermöglicht.
Zeitparameter
time: Zeigt eine Zeitauswahl an.date: Zeigt eine Datumsauswahl an.datetime: Zeigt ein Eingabefeld an, das sowohl Datum als auch Uhrzeit enthält.
Selektor-Parameter
user_id: Zeigt das Discourse-Benutzerauswahlfeld an und wird zur numerischen Benutzer-ID.user_list: Ähnlich wieuser_id, aber ermöglicht mehrere Benutzer und wird zu einer kommagetrennten Liste der numerischen 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.
Listenparameter verwenden
Bei der Verwendung von Listenparametern (int_list, string_list, user_list) muss besonders darauf geachtet werden, Syntaxfehler zu vermeiden. Hier ist ein Beispiel für die korrekte Verwendung eines Listenparameters:
-- [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 null voranstellen. Das bedeutet, dass Sie bei der Ausführung der Abfrage keinen Wert für diesen Parameter angeben müssen.
Hier sind einige Beispiele, wie Sie solche Parameter deklarieren würden:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
In der obigen SQL-Abfrage sind null_int, null_boolean und null_string Parameter, die bei der 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, wenn post_id oder username nicht angegeben wird (d.h. als null belassen wird), ignoriert die Abfrage diesen Teil der WHERE-Klausel. 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 unausgefüllte Eingaben, ungültige numerische Eingaben, nicht existierende Kategorien oder Gruppen, fehlerhafte Zeiten usw. Bei ungültigen Eingaben wird der Grund für den Fehler im Formular angezeigt und der Abfrageausführungsbetrieb 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
