Parâmetros são uma ferramenta poderosa que pode ser usada em consultas do Data Explorer no Discourse. Os parâmetros permitem consultas mais dinâmicas e personalizáveis, e, em vez de codificar valores diretamente nas suas consultas, você pode declarar variáveis que solicitarão uma 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 será substituído pelo nome do seu parâmetro.
Isso criará um campo onde você pode inserir diferentes valores cada vez que executar a consulta.
Tipos de Parâmetros
Ao declarar parâmetros nas suas consultas do Data Explorer, você pode especificar diferentes tipos de entrada. Aqui estão os tipos de parâmetros disponíveis e suas descrições:
Parâmetros Numéricos
int: Exibe uma entrada numérica, tornando-se um valor numérico.inté restrito a números de 32 bits.bigint: Similar aint, mas pode ser maior.double: Permite valores decimais.
A correção dos parâmetros numéricos será verificada na interface do usuário.
Parâmetros de String
string: Caixa de texto livre, tornando-se um valor de texto.
Parâmetros de Lista
int_list: Insira inteiros separados por vírgulas, tornando-se inteiros separados por vírgulas na consulta.string_list: Similar aint_list, mas para strings.
Parâmetros de ID Específicos
post_id: Entrada numérica; garante que a postagem especificada exista no fórum antes de executar a consulta.topic_id: Similar apost_id, mas para tópicos.badge_id: Garante que o distintivo especificado exista.
Parâmetros Booleanos
boolean: Exibe uma caixa de seleção.null boolean: Exibe uma lista suspensa, 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 tanto data quanto hora.
Parâmetros de Seletor
user_id: Exibe a caixa de seletor de usuário do Discourse e torna-se o ID numérico do usuário.user_list: Similar auser_id, mas permite múltiplos usuários, tornando-se uma lista separada por vírgulas dos IDs numéricos dos usuários.group_id: Similar auser_id, mas para grupos.group_list: Similar auser_list, mas para grupos.category_id: Similar auser_id, mas para categorias.
Parâmetros Internos
current_user_id: Sem interface de entrada; define automaticamente a variável para o ID do usuário que está executando a consulta
Usando Parâmetros de Lista
Ao usar parâmetros de lista (int_list, string_list, user_list), deve-se ter cuidado especial 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 esses parâmetros:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
-- null current_user_id :me
No SQL acima, null_int, null_boolean e null_string são parâmetros que podem ser deixados vazios 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, for deixado como null), a consulta ignorará aquela parte da cláusula WHERE. Isso permite consultas mais flexíveis, onde algumas condições são opcionais.
Validação na Interface do Usuário
A maioria dos tipos de parâmetros será validada na interface do usuário. Essas validações incluem entradas obrigatórias não preenchidas, entrada numérica inválida, categorias ou grupos inexistentes, horários malformados, etc. Para entrada inválida, o motivo do erro será exibido no formulário e a operação de execução da consulta será rejeitada.
Escolhendo tipos e usando casts
Em geral, os parâmetros devem ‘funcionar sozinhos’ nas suas consultas. Para casos mais avançados, você pode precisar adicionar um cast explícito ::type.
Por exemplo, para intervalos, você precisa declarar um parâmetro de string e convertê-lo para interval. Os valores podem incluir unidades, como 2 day ou 3 hours:
-- [params]
-- string :lookback = 2 day
SELECT id AS topic_id, created_at
FROM topics
WHERE created_at >= NOW() - :lookback::interval
Algumas funções também precisam de tipos de argumento explícitos:
round(amount::numeric, :decimal_places::integer)
date_trunc('day', :start_date::timestamp)
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
-- current_user_id :me
