Parameter sind ein leistungsfähiges Werkzeug, das in Data Explorer-Abfragen auf Discourse verwendet werden kann. Parameter ermöglichen dynamischere und anpassbarere Abfragen. Anstatt Werte hartkodiert in deinen Abfragen zu verwenden, kannst du Variablen deklarieren, die bei der Ausführung der Abfrage nach einer Eingabe fragen.
Deklaration eines Parameters
Um einen Parameter zu deklarieren, kannst du die folgende Syntax verwenden:
-- [params]
-- int :parameter_name = 10
Der Parameterabschnitt deiner Abfrage beginnt immer mit -- [params], gefolgt von jedem Parametertyp auf einer neuen Zeile, wobei parameter_name durch den Namen deines Parameters ersetzt wird.
Dadurch wird ein Feld erstellt, in das du bei jeder Ausführung der Abfrage unterschiedliche Werte eingeben kannst.
Typen von Parametern
Wenn du Parameter in deinen Data Explorer-Abfragen deklarierst, kannst du verschiedene Eingabetypen angeben. Hier sind die verfügbaren Parametertypen und deren Beschreibungen:
Numerische Parameter
int: Zeigt eine Zahleingabe an und wird zu einem numerischen Wert.intist auf 32-Bit-Zahlen beschränkt.bigint: Ähnlich wieint, aber kann größer sein.double: Erlaubt Dezimalwerte.
Die Korrektheit der numerischen Parameter wird auf der Frontend-Seite überprüft.
Zeichenketten-Parameter (String)
string: Freitextfeld, wird zu einem Textwert.
Listen-Parameter
int_list: Komma-getrennte Ganzzahlen eingeben, werden in der Abfrage zu kommagetrennten Ganzzahlen.string_list: Ähnlich wieint_list, aber für Zeichenketten.
Spezifische ID-Parameter
post_id: Numerische Eingabe; stellt sicher, dass der angegebene Beitrag auf dem 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 ermöglicht.
Zeit-Parameter
time: Zeigt eine Zeitwähler-Eingabe an.date: Zeigt eine Datumsauswahl-Eingabe an.datetime: Zeigt ein Eingabefeld an, das sowohl Datum als auch Zeit enthält.
Auswahlpunkte-Parameter (Selector)
user_id: Zeigt das Discourse-Benutzerauswahl-Feld an und wird zur numerischen Benutzer-ID.user_list: Ähnlich wieuser_id, aber erlaubt 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.
Interne Parameter
current_user_id: Keine Eingabe-Oberfläche; 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 Vorsicht 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
Du kannst auch eine leere Eingabe erlauben, indem du dem Parametertyp das Präfix null voranstellst. Das bedeutet, dass es nicht erforderlich ist, bei der Ausführung der Abfrage einen Wert für diesen Parameter anzugeben.
Hier sind einige Beispiele, wie du solche Parameter deklarieren würdest:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
-- null current_user_id :me
Im obigen SQL sind null_int, null_boolean und null_string Parameter, die bei der Ausführung der Abfrage leer gelassen werden können.
Schauen 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 wird, wenn post_id oder username nicht angegeben werden (d. h. als null verbleiben), dieser Teil der WHERE-Klausel ignoriert. Dies ermöglicht flexiblere Abfragen, bei denen einige Bedingungen optional sind.
Frontend-Validierung
Die meisten Parameterarten werden auf der Frontend-Seite validiert. Diese Validierungen umfassen erforderliche, aber nicht ausgefüllte Eingaben, ungültige numerische Eingaben, nicht existierende Kategorien oder Gruppen, fehlerhafte Zeiten usw. Bei ungültiger Eingabe wird der Grund für den Fehler im Formular angezeigt und die Ausführung der Abfrage wird abgelehnt.
Auswahl von Typen und Verwendung von Casts
Im Allgemeinen sollten Parameter in deinen Abfragen einfach funktionieren. Für fortgeschrittenere Fälle kann es notwendig sein, einen expliziten ::type-Cast hinzuzufügen.
z. B. für Intervalle musst du einen String-Parameter deklarieren und ihn auf interval casten. Werte können Einheiten enthalten, wie z. B. 2 day oder 3 hours:
-- [params]
-- string :lookback = 2 day
SELECT id AS topic_id, created_at
FROM topics
WHERE created_at >= NOW() - :lookback::interval
Einige Funktionen benötigen auch explizite Argumenttypen:
round(amount::numeric, :decimal_places::integer)
date_trunc('day', :start_date::timestamp)
Zusätzliche Beispiele
Hier sind einige zusätzliche Beispiele für die Deklaration verschiedener Parameterarten:
-- [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
