I parametri sono uno strumento potente che può essere utilizzato nelle query di Data Explorer su Discourse. I parametri consentono query più dinamiche e personalizzabili e, anziché codificare a valore fisso i dati nelle query, è possibile dichiarare variabili che richiederanno un input quando la query viene eseguita.
Dichiarazione di un parametro
Per dichiarare un parametro, è possibile utilizzare la seguente sintassi:
-- [params]
-- int :parameter_name = 10
La sezione dei parametri della query inizierà sempre con -- [params], seguita da ciascun tipo di parametro su una nuova riga, dove parameter_name verrà sostituito dal nome del proprio parametro.
Questo creerà un campo in cui è possibile immettere valori diversi ogni volta che si esegue la query.
Tipi di parametri
Quando si dichiarano parametri nelle query di Data Explorer, è possibile specificare diversi tipi di input. Ecco i tipi di parametri disponibili e le relative descrizioni:
Parametri numerici
int: Mostra un input numerico, diventa un valore numerico.intè limitato a numeri a 32 bit.bigint: Simile aint, ma può essere più grande.double: Consente valori decimali.
La correttezza dei parametri numerici verrà verificata sul front end.
Parametri stringa
string: Casella di testo libera, diventa un valore di testo.
Parametri elenco
int_list: Inserisci interi separati da virgole, diventano interi separati da virgole nella query.string_list: Simile aint_list, ma per le stringhe.
Parametri ID specifici
post_id: Input numerico; assicura che il post specificato esista sul forum prima di eseguire la query.topic_id: Simile apost_id, ma per gli argomenti.badge_id: Assicura che il badge specificato esista.
Parametri booleani
boolean: Mostra una casella di controllo.null boolean: Mostra un menu a discesa, consentendo un input vuoto.
Parametri temporali
time: Visualizza un input selettore dell’ora.date: Visualizza un input selettore della data.datetime: Visualizza una casella di input che include sia data che ora.
Parametri selettore
user_id: Mostra la casella selettore utente di Discourse e diventa l’ID utente numerico.user_list: Simile auser_id, ma consente più utenti, diventando un elenco separato da virgole di ID utente numerici.group_id: Simile auser_id, ma per i gruppi.group_list: Simile auser_list, ma per i gruppi.category_id: Simile auser_id, ma per le categorie.
Parametri interni
current_user_id: Nessuna interfaccia di input; imposta automaticamente la variabile sull’ID utente dell’utente che esegue la query
Utilizzo dei parametri elenco
Quando si utilizzano parametri elenco (int_list, string_list, user_list), è necessario prestare particolare attenzione per evitare errori di sintassi. Ecco un esempio di utilizzo corretto di un parametro elenco:
-- [params]
-- user_list :the_user_ids
SELECT SUM(length(bio_raw))
FROM user_profiles
WHERE user_id IN (:the_user_ids)
Parametri null
È anche possibile consentire un input vuoto anteponendo null al tipo di parametro. Questo significa che non è necessario fornire un valore per quel parametro quando si esegue la query.
Ecco alcuni esempi di come dichiarare tali parametri:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
-- null current_user_id :me
Nello SQL sopra, null_int, null_boolean e null_string sono parametri che possono essere lasciati vuoti quando si esegue la query.
Vediamo come questi tipi di parametri possono essere utilizzati in una query:
-- [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 questa query, se post_id o username non viene fornito (ovvero lasciato come null), la query ignorerà quella parte della clausola WHERE. Questo consente query più flessibili in cui alcune condizioni sono facoltative.
Validazione front-end
La maggior parte dei tipi di parametri verrà validata sul front end. Queste validazioni includono input obbligatori ma non compilati, input numerici non validi, categorie o gruppi inesistenti, orari malformati, ecc. Per un input non valido, il motivo dell’errore verrà visualizzato nel modulo e l’operazione di esecuzione della query verrà rifiutata.
Scelta dei tipi e utilizzo dei cast
In generale, i parametri dovrebbero ‘funzionare’ nelle proprie query. Per casi più avanzati, potrebbe essere necessario aggiungere un cast esplicito ::type.
Ad esempio, per gli intervalli, è necessario dichiarare un parametro stringa e convertirlo in intervallo. I valori possono includere unità, come 2 day o 3 hours:
-- [params]
-- string :lookback = 2 day
SELECT id AS topic_id, created_at
FROM topics
WHERE created_at >= NOW() - :lookback::interval
Alcune funzioni richiedono anche tipi di argomenti espliciti:
round(amount::numeric, :decimal_places::integer)
date_trunc('day', :start_date::timestamp)
Esempi aggiuntivi
Ecco alcuni esempi aggiuntivi di dichiarazione di diversi tipi di parametri:
-- [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
:abbracci: