Los parámetros son una herramienta poderosa que se puede utilizar en las consultas de Data Explorer en Discourse. Los parámetros permiten consultas más dinámicas y personalizables, y en lugar de codificar valores en sus consultas, puede declarar variables que solicitarán una entrada cuando se ejecute la consulta.
Declarar un Parámetro
Para declarar un parámetro, puede usar la siguiente sintaxis:
-- [params]
-- int :parameter_name = 10
La sección de parámetros de la consulta siempre comenzará con -- [params], seguido de cada tipo de parámetro en una nueva línea, donde parameter_name se reemplazará por el nombre de su parámetro.
Esto creará un campo donde puede introducir diferentes valores cada vez que ejecute la consulta.
Tipos de Parámetros
Al declarar parámetros en sus consultas de Data Explorer, puede especificar diferentes tipos de entradas. Aquí están los tipos de parámetros disponibles y sus descripciones:
Parámetros Numéricos
int: Muestra una entrada numérica, se convierte en un valor numérico.intestá restringido a números de 32 bits.bigint: Similar aint, pero puede ser más grande.double: Permite valores decimales.
La corrección de los parámetros numéricos se verificará en el front-end.
Parámetros de Cadena (String)
string: Cuadro de texto de formato libre, se convierte en un valor de texto.
Parámetros de Lista
int_list: Introduzca enteros separados por comas, se convierte en enteros separados por comas en la consulta.string_list: Similar aint_list, pero para cadenas.
Parámetros de ID Específicos
post_id: Entrada numérica; asegura que la publicación especificada exista en el foro antes de ejecutar la consulta.topic_id: Similar apost_id, pero para temas.badge_id: Asegura que la insignia especificada exista.
Parámetros Booleanos
boolean: Muestra una casilla de verificación.null boolean: Muestra un menú desplegable, lo que permite una entrada vacía.
Parámetros de Tiempo
time: Muestra una entrada de selector de hora.date: Muestra una entrada de selector de fecha.datetime: Muestra una entrada que incluye tanto la fecha como la hora.
Parámetros de Selector
user_id: Muestra el cuadro selector de usuario de Discourse y se convierte en el ID numérico del usuario.user_list: Similar auser_id, pero permite múltiples usuarios, convirtiéndose en una lista separada por comas de los IDs numéricos de usuario.group_id: Similar auser_id, pero para grupos.group_list: Similar auser_list, pero para grupos.category_id: Similar auser_id, pero para categorías.
Parámetros Internos
current_user_id: Sin interfaz de usuario de entrada; establece automáticamente la variable en el ID de usuario del usuario que ejecuta la consulta
Uso de Parámetros de Lista
Al usar parámetros de lista (int_list, string_list, user_list), se debe tener especial cuidado para evitar errores de sintaxis. Aquí hay un ejemplo de cómo usar correctamente un parámetro de lista:
-- [params]
-- user_list :the_user_ids
SELECT SUM(length(bio_raw))
FROM user_profiles
WHERE user_id IN (:the_user_ids)
Parámetros Nulos (Null)
También puede permitir una entrada vacía anteponiendo al tipo de parámetro null. Esto significa que no es necesario proporcionar un valor para ese parámetro al ejecutar la consulta.
Aquí hay algunos ejemplos de cómo declarar dichos parámetros:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
-- null current_user_id :me
En el SQL anterior, null_int, null_boolean y null_string son parámetros que se pueden dejar vacíos al ejecutar la consulta.
Veamos cómo se pueden usar estos tipos de parámetros en una consulta:
-- [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)
En esta consulta, si no se proporciona post_id o username (es decir, se deja como null), la consulta ignorará esa parte de la cláusula WHERE. Esto permite consultas más flexibles donde algunas condiciones son opcionales.
Validación de Front-end
La mayoría de los tipos de parámetros se validarán en el front-end. Estas validaciones incluyen entradas requeridas pero no rellenadas, entrada numérica no válida, categorías o grupos inexistentes, horas mal formadas, etc. Para entradas no válidas, se mostrará el motivo del error en el formulario y se rechazará la operación de ejecución de consulta.
Ejemplos Adicionales
Aquí hay algunos ejemplos adicionales de declaración de diferentes tipos de parámetros:
-- [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
