Utilizzo dei parametri nelle query di Data Explorer

[SaraDev (Sara Devlaeminck)]

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 valori 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 parametro.

Ciò creerà un campo in cui è possibile inserire 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 loro descrizioni:

Parametri Numerici

• int: Mostra un input numerico, diventa un valore numerico. int è limitato a numeri a 32 bit.
• bigint: Simile a int, 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, diventa interi separati da virgole nella query.
• string_list: Simile a int_list, ma per stringhe.

Parametri ID Specifici

• post_id: Input numerico; garantisce che il post specificato esista sul forum prima di eseguire la query.
• topic_id: Simile a post_id, ma per argomenti.
• badge_id: Garantisce 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 selettore di orario.
• date: Visualizza un selettore di 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 numerico dell’utente.
• user_list: Simile a user_id, ma consente più utenti, diventando un elenco separato da virgole degli ID numerici degli utenti.
• group_id: Simile a user_id, ma per gruppi.
• group_list: Simile a user_list, ma per gruppi.
• category_id: Simile a user_id, ma per categorie.

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

È inoltre possibile consentire un input vuoto anteponendo null al tipo di parametro. Ciò significa che non è necessario fornire un valore per tale 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

Nella SQL sopra, null_int, null_boolean e null_string sono parametri che possono essere lasciati vuoti durante l’esecuzione della 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 vengono forniti (cioè lasciati come null), la query ignorerà quella parte della clausola WHERE. Ciò consente query più flessibili in cui alcune condizioni sono facoltative.

Validazione Front-end

La maggior parte dei tipi di parametri verrà convalidata sul front-end. Queste convalide includono input richiesti ma non compilati, input numerici non validi, categorie o gruppi inesistenti, orari malformati, ecc. Per input non validi, il motivo dell’errore verrà visualizzato nel modulo e l’operazione di esecuzione della query verrà rifiutata.

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

Altri Argomenti in questa Serie

• Tutorial Data Explorer - Parte 1 - Scrivere la Prima Query
• Tutorial Data Explorer - Parte 2 - Basi di SQL di Discourse
• Questo Argomento
• Formattazione dei Risultati delle Tabelle di Data Explorer

[Lilly (Lillian Louis)]

Queste sono ottime guide, grazie per averle pubblicate @SaraDev :abbracci:

[fbpbdmin (deepblue)]

@AlexDev
un nome di campo nella clausola where può essere un parametro? grazie
o l’intera istruzione sql può essere un parametro da passare dall’endpoint REST /admin/plugin/explorer/queries/id/run

[n1bff]

PSA: Non è possibile utilizzare numeri nei nomi dei parametri, ad esempio “foo123” non funzionerà.

-- [params]
-- string       :foo123 = a

SELECT :foo123

risulta in

PG::SyntaxError: ERROR:  syntax error at or near ":"
LINE 10: SELECT :foo123
                ^

[C_X]

Ho provato a chiamare l’endpoint run tramite POST con i parametri nel payload JSON come

payload = {
    "params": {
        "request_post_id": "45"
    },
    "explain": False
}

Ho fatto reverse engineering del payload dalla scheda payload di Chrome DevTools.
In qualche modo continuo a ricevere un errore del server 500.

Qualcuno può aiutarmi per favore?