パラメータは、Discourse の Data Explorer クエリで使用できる強力なツールです。パラメータを使用することで、より動的でカスタマイズ可能なクエリを作成でき、クエリ内に値をハードコードする代わりに、クエリ実行時に入力を促す変数を宣言できます。
パラメータの宣言
パラメータを宣言するには、次の構文を使用できます：
-- [params]
-- int :parameter_name = 10
クエリのパラメータセクションは常に -- [params] で始まり、その後に新しい行で各パラメータの型が続きます。ここで parameter_name は、あなたのパラメータの名前に置き換えられます。
これにより、クエリを実行するたびに異なる値を入力できるフィールドが作成されます。
パラメータの型
Data Explorer クエリでパラメータを宣言する際、異なる入力型を指定できます。利用可能なパラメータの型とその説明は以下の通りです：
数値パラメータ
int: 数値入力を表示し、数値になります。intは 32 ビットの数値に制限されます。bigint:intに似ていますが、より大きな値を扱えます。double: 小数値を許可します。
数値パラメータの正確性はフロントエンドで検証されます。
文字列パラメータ
string: フリーフォームのテキストボックスで、テキスト値になります。
リストパラメータ
int_list: カンマ区切りで整数を入力し、クエリ内ではカンマ区切りの整数になります。string_list:int_listに似ていますが、文字列向けです。
特定の ID パラメータ
post_id: 数値入力。クエリ実行前に、指定された投稿がフォーラムに存在することを確認します。topic_id:post_idに似ていますが、トピック向けです。badge_id: 指定されたバッジが存在することを確認します。
ブール値パラメータ
boolean: チェックボックスを表示します。null boolean: ドロップダウンを表示し、空の入力を許可します。
時間パラメータ
time: 時間ピッカーの入力を表示します。date: 日付ピッカーの入力を表示します。datetime: 日付と時間を含む入力ボックスを表示します。
セレクターパラメータ
user_id: Discourse ユーザーセレクターボックスを表示し、数値のユーザー ID になります。user_list:user_idに似ていますが、複数のユーザーを許可し、数値のユーザー ID のカンマ区切りリストになります。group_id:user_idに似ていますが、グループ向けです。group_list:user_listに似ていますが、グループ向けです。category_id:user_idに似ていますが、カテゴリ向けです。
内部パラメータ
current_user_id: 入力 UI なし。クエリを実行しているユーザーのユーザー 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 句のその部分を無視します。これにより、一部の条件が任意である、より柔軟なクエリが可能になります。
フロントエンドの検証
ほとんどのパラメータの型はフロントエンドで検証されます。これらの検証には、必須だが未入力の場合、無効な数値入力、存在しないカテゴリやグループ、形式不正な時間などが含まれます。無効な入力の 경우、エラーの原因がフォームに表示され、クエリ実行操作は拒否されます。
型の選択とキャストの使用
一般的に、パラメータはクエリ内で「そのまま動作する」はずです。より高度なケースでは、明示的な ::type キャストを追加する必要がある場合があります。
例えば、間隔（interval）の場合、文字列パラメータを宣言し、interval にキャストする必要があります。値には単位を含めることができ、例えば 2 day や 3 hours などです：
-- [params]
-- string :lookback = 2 day
SELECT id AS topic_id, created_at
FROM topics
WHERE created_at >= NOW() - :lookback::interval
一部の関数も明示的な引数の型を必要とします：
round(amount::numeric, :decimal_places::integer)
date_trunc('day', :start_date::timestamp)
追加の例
異なる型のパラメータを宣言する追加の例を以下に示します：
-- [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
