파라미터는 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와 유사하지만 주제(Topic)를 위한 것입니다.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
