パラメータは、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と似ていますが、カテゴリ用です。
リストパラメータの使用
リストパラメータ (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
上記の 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
