Parâmetros são uma ferramenta poderosa que pode ser usada em consultas do Explorador de Dados no Discourse. Parâmetros permitem consultas mais dinâmicas e personalizáveis, e em vez de codificar valores em suas consultas, você pode declarar variáveis que solicitarão entrada quando a consulta for executada.
Declarando um Parâmetro
Para declarar um parâmetro, você pode usar a seguinte sintaxe:
-- [params]
-- int :parameter_name = 10
A seção de parâmetros da consulta sempre começará com -- [params], seguida por cada tipo de parâmetro em uma nova linha, onde parameter_name seria substituído pelo nome do seu parâmetro.
Isso criará um campo onde você poderá inserir diferentes valores cada vez que executar a consulta.
Tipos de Parâmetros
Ao declarar parâmetros em suas consultas do Explorador de Dados, você pode especificar diferentes tipos de entradas. Aqui estão os tipos de parâmetros disponíveis e suas descrições:
Parâmetros Numéricos
int: Mostra uma entrada numérica, torna-se um valor numérico.inté restrito a números de 32 bits.bigint: Semelhante aint, mas pode ser maior.double: Permite valores decimais.
A correção dos parâmetros numéricos será verificada no front-end.
Parâmetros de String
string: Caixa de texto livre, torna-se um valor de texto.
Parâmetros de Lista
int_list: Insira inteiros separados por vírgula, torna-se inteiros separados por vírgula na consulta.string_list: Semelhante aint_list, mas para strings.
Parâmetros de ID Específico
post_id: Entrada numérica; garante que a postagem especificada exista no fórum antes de executar a consulta.topic_id: Semelhante apost_id, mas para tópicos.badge_id: Garante que o distintivo especificado exista.
Parâmetros Booleanos
boolean: Mostra uma caixa de seleção.null boolean: Mostra um menu suspenso, permitindo uma entrada vazia.
Parâmetros de Tempo
time: Exibe uma entrada de seletor de hora.date: Exibe uma entrada de seletor de data.datetime: Exibe uma caixa de entrada que inclui data e hora.
Parâmetros de Seletor
user_id: Mostra a caixa seletora de usuários do Discourse e se torna o ID numérico do usuário.user_list: Semelhante auser_id, mas permite vários usuários, tornando-se uma lista separada por vírgulas dos IDs numéricos dos usuários.group_id: Semelhante auser_id, mas para grupos.group_list: Semelhante auser_list, mas para grupos.category_id: Semelhante auser_id, mas para categorias.
Usando Parâmetros de Lista
Ao usar parâmetros de lista (int_list, string_list, user_list), cuidados especiais devem ser tomados para evitar erros de sintaxe. Aqui está um exemplo de como usar corretamente um 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
Você também pode permitir uma entrada vazia prefixando o tipo de parâmetro com null. Isso significa que não é necessário fornecer um valor para esse parâmetro ao executar a consulta.
Aqui estão alguns exemplos de como você declararia tais parâmetros:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
Na SQL acima, null_int, null_boolean e null_string são parâmetros que podem ser deixados em branco ao executar a consulta.
Vamos ver como esses tipos de parâmetros podem ser usados em uma 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)
Nesta consulta, se post_id ou username não for fornecido (ou seja, deixado como null), a consulta ignorará essa parte da cláusula WHERE. Isso permite consultas mais flexíveis onde algumas condições são opcionais.
Validação no Front-end
A maioria dos tipos de parâmetros será validada no front-end. Essas validações incluem entradas obrigatórias, mas não preenchidas, entrada numérica inválida, categorias ou grupos inexistentes, horários mal formatados, etc. Para entradas inválidas, o motivo do erro será exibido no formulário e a operação de execução da consulta será rejeitada.
Exemplos Adicionais
Aqui estão alguns exemplos adicionais de declaração 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
