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; en lugar de codificar valores de forma fija en tus consultas, puedes declarar variables que solicitarán una entrada cuando se ejecute la consulta.
Declarar un parámetro
Para declarar un parámetro, puedes usar la siguiente sintaxis:
-- [params]
-- int :parameter_name = 10
La sección de parámetros de la consulta siempre comenzará con -- [params], seguida de cada tipo de parámetro en una nueva línea, donde parameter_name se reemplazará por el nombre de tu parámetro.
Esto creará un campo donde puedes ingresar diferentes valores cada vez que ejecutes la consulta.
Tipos de parámetros
Al declarar parámetros en tus consultas de Data Explorer, puedes especificar diferentes tipos de entrada. A continuación se muestran los tipos de parámetros disponibles y sus descripciones:
Parámetros numéricos
int: Muestra una entrada numérica y se convierte en un valor numérico.intestá restringido a números de 32 bits.bigint: Similar aint, pero puede ser mayor.double: Permite valores decimales.
La corrección de los parámetros numéricos se verificará en el front end.
Parámetros de cadena
string: Cuadro de texto libre, se convierte en un valor de texto.
Parámetros de lista
int_list: Ingresa 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, permitiendo 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 un cuadro de entrada que incluye tanto la fecha como la hora.
Parámetros de selector
user_id: Muestra el cuadro de 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 entrada; establece automáticamente la variable con 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. A continuación se muestra un ejemplo de uso correcto de 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
También puedes permitir una entrada vacía prefijando el tipo de parámetro con 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 pueden dejarse 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 post_id o username no se proporciona (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 en el 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 completadas, entrada numérica inválida, categorías o grupos inexistentes, horas mal formateadas, etc. Para una entrada inválida, la razón del error se mostrará en el formulario y la operación de ejecución de la consulta será rechazada.
Elección de tipos y uso de casts
En general, los parámetros deberían “funcionar solos” en tus consultas. Para casos más avanzados, es posible que necesites agregar un cast explícito ::type.
Por ejemplo, para intervalos, necesitas declarar un parámetro de cadena y convertirlo a interval. Los valores pueden incluir unidades, como 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
Algunas funciones también necesitan tipos de argumento explícitos:
round(amount::numeric, :decimal_places::integer)
date_trunc('day', :start_date::timestamp)
Ejemplos adicionales
A continuación se muestran 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
