Parámetros son una herramienta potente que se puede utilizar en consultas de Explorador de datos 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 información al ejecutar la consulta.
Declarar un Parámetro
Para declarar un parámetro, puede usar la siguiente sintaxis:
-- [params]
-- int :nombre_parametro = 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 nombre_parametro se reemplazará por el nombre de su parámetro.
Esto creará un campo donde podrá ingresar diferentes valores cada vez que ejecute la consulta.
Tipos de Parámetros
Al declarar parámetros en sus consultas de Explorador de datos, 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: Cuadro de texto libre, se convierte en un valor de texto.
Parámetros de Lista
int_list: Ingrese 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, 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 un cuadro de entrada que incluye fecha y hora.
Parámetros Selectores
user_id: Muestra el cuadro selector de usuarios 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 los usuarios.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.
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 :los_ids_de_usuario
SELECT SUM(length(bio_raw))
FROM user_profiles
WHERE user_id IN (:los_ids_de_usuario)
Parámetros Nulos
También puede 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ía tales parámetros:
-- [params]
-- null int :int_nulo
-- null boolean :booleano_nulo
-- null string :cadena_nula
En el SQL anterior, int_nulo, booleano_nulo y cadena_nula 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 :id_publicacion
-- null string :nombre_usuario
SELECT *
FROM users
WHERE (id = :id_publicacion OR :id_publicacion IS NULL)
AND (username = :nombre_usuario OR :nombre_usuario IS NULL)
En esta consulta, si no se proporciona id_publicacion o nombre_usuario (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, tiempos mal formados, etc. Para entradas inválidas, se mostrará la razón del error en el formulario y se rechazará la operación de ejecución de la 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 :booleano_tres = #null
-- string :string = conejito pequeño 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
