Параметры — это мощный инструмент, который можно использовать в запросах Data Explorer в Discourse. Параметры позволяют создавать более динамичные и настраиваемые запросы. Вместо того чтобы жестко кодировать значения в запросах, вы можете объявить переменные, которые будут запрашивать ввод при выполнении запроса.
Объявление параметра
Для объявления параметра используйте следующий синтаксис:
-- [params]
-- int :parameter_name = 10
Раздел параметров запроса всегда начинается с -- [params], за которым следует каждый тип параметра на новой строке, где parameter_name заменяется именем вашего параметра.
Это создаст поле, в которое можно вводить разные значения каждый раз при запуске запроса.
Типы параметров
При объявлении параметров в запросах Data Explorer можно указывать различные типы ввода. Ниже приведены доступные типы параметров и их описания:
Числовые параметры
int: Поле ввода числа, преобразуется в числовое значение.intограничен 32-битными числами.bigint: Аналогичноint, но может быть больше.double: Позволяет вводить десятичные значения.
Корректность числовых параметров проверяется на стороне клиента.
Строковые параметры
string: Свободное текстовое поле, преобразуется в текстовое значение.
Список параметров
int_list: Ввод целых чисел через запятую, в запросе преобразуется в список целых чисел через запятую.string_list: Аналогичноint_list, но для строк.
Параметры конкретных идентификаторов
post_id: Числовой ввод; гарантирует, что указанный пост существует на форуме перед выполнением запроса.topic_id: Аналогичноpost_id, но для тем.badge_id: Гарантирует существование указанного значка.
Булевы параметры
boolean: Отображает флажок.null boolean: Отображает выпадающий список, позволяя оставить поле пустым.
Параметры времени
time: Отображает выбор времени.date: Отображает выбор даты.datetime: Отображает поле ввода, включающее дату и время.
Параметры селектора
user_id: Отображает селектор пользователей Discourse и преобразуется в числовой идентификатор пользователя.user_list: Аналогичноuser_id, но позволяет выбирать нескольких пользователей, преобразуясь в список числовых идентификаторов через запятую.group_id: Аналогичноuser_id, но для групп.group_list: Аналогичноuser_list, но для групп.category_id: Аналогичноuser_id, но для категорий.
Внутренние параметры
current_user_id: Нет интерфейса ввода; автоматически устанавливает переменную в идентификатор пользователя, запускающего запрос
Использование параметров списка
При использовании параметров списка (int_list, string_list, user_list) необходимо соблюдать особую осторожность, чтобы избежать синтаксических ошибок. Вот пример правильного использования параметра списка:
-- [params]
-- user_list :the_user_ids
SELECT SUM(length(bio_raw))
FROM user_profiles
WHERE user_id IN (:the_user_ids)
Пустые параметры (Null)
Вы также можете разрешить пустой ввод, добавив префикс null к типу параметра. Это означает, что при выполнении запроса не обязательно указывать значение для этого параметра.
Вот несколько примеров объявления таких параметров:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
-- null current_user_id :me
В приведенном выше SQL-коде null_int, null_boolean и null_string — это параметры, которые можно оставить пустыми при выполнении запроса.
Давайте посмотрим, как такие типы параметров можно использовать в запросе:
-- [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)
В этом запросе, если post_id или username не указаны (то есть оставлены как null), запрос проигнорирует эту часть условия WHERE. Это позволяет создавать более гибкие запросы, где некоторые условия являются необязательными.
Валидация на стороне клиента
Большинство типов параметров проверяются на стороне клиента. Эти проверки включают обязательные, но незаполненные поля ввода, некорректные числовые значения, несуществующие категории или группы, некорректные форматы времени и т. д. Для некорректного ввода причина ошибки будет отображена в форме, а операция запуска запроса будет отклонена.
Дополнительные примеры
Вот несколько дополнительных примеров объявления различных типов параметров:
-- [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
