Parámetros son una herramienta potente que se puede usar 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 tus consultas, puedes declarar variables que solicitarán 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], seguido de cada tipo de parámetro en una nueva línea, donde parameter_name se reemplazaría 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 Explorador de Datos, puedes 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 frontend.
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 fecha como 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.
Usando 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
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ías tales parámetros:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
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 post_id o username no se proporcionan (es decir, se dejan 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 Frontend
La mayoría de los tipos de parámetros se validarán en el frontend. 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 :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
:拥抱: