# Using Parameters in Data Explorer Queries
**URL:** https://meta.discourse.org/t/using-parameters-in-data-explorer-queries/277934
**Category:** Data & reporting
**Tags:** data-explorer, sql-tutorial
**Created:** [September 5, 2023, 10:55pm UTC](https://meta.discourse.org/t/using-parameters-in-data-explorer-queries/277934 "2023-09-05T22:55:31Z")
**Posts on this page:** 7
**Page:** 1
### Author:  [@SaraDev](https://meta.discourse.org/u/SaraDev)
#### Post date: [September 5, 2023, 10:55pm UTC](https://meta.discourse.org/t/using-parameters-in-data-explorer-queries/277934/1 "2023-09-05T22:55:31Z")
Parameters are a powerful tool that can be used in [Data Explorer](https://meta.discourse.org/t/32566) queries on Discourse. Parameters allow for more dynamic and customizable queries, and instead of hard-coding values in your queries, you can declare variables that will prompt for input when the query is run.
## Declaring a Parameter
To declare a parameter, you can use the following syntax:
```plaintext
-- [params]
-- int :parameter_name = 10
```
The parameter’s section of the query will always start with `-- [params]`, followed by each type of parameter on a new line, where `parameter_name` would be replaced by the name for your parameter.
This will create a field where you can input different values each time you run the query.
## Types of Parameters
When declaring parameters in your [Data Explorer](https://meta.discourse.org/t/32566) queries, you can specify different types of inputs. Here are the available parameter types and their descriptions:
### Numeric Parameters
- `int`: Shows a number input, becomes a numeric value. `int` is restricted to 32-bit numbers.
- `bigint`: Similar to `int`, but can be larger.
- `double`: Allows decimal values.
The correctness of the numeric parameters will be verified on the front end.
### String Parameters
- `string`: Freeform textbox, becomes a text value.
### List Parameters
- `int_list`: Enter comma-separated integers, becomes comma-separated integers in the query.
- `string_list`: Similar to `int_list`, but for strings.
### Specific ID Parameters
- `post_id`: Numeric input; ensures the specified post exists on the forum before running the query.
- `topic_id`: Similar to `post_id`, but for topics.
- `badge_id`: Ensures the specified badge exists.
### Boolean Parameters
- `boolean`: Shows a checkbox.
- `null boolean`: Shows a dropdown, allowing for an empty input.
### Time Parameters
- `time`: Displays a time picker input.
- `date`: Displays a date picker input.
- `datetime`: Displays a input box includes both date and time.
### Selector Parameters
- `user_id`: Shows the Discourse user selector box, and becomes the numeric user ID.
- `user_list`: Similar to `user_id`, but allows for multiple users, becoming a comma-separated list of the numeric user IDs.
- `group_id`: Similar to `user_id`, but for groups.
- `group_list`: Similar to `user_list`, but for groups.
- `category_id`: Similar to `user_id`, but for categories.
### Internal Parameters
- `current_user_id`: No input UI; automatically sets the variable to the user ID of the user running the query
## Using List Parameters
When using list parameters (`int_list`, `string_list`, `user_list`), special care must be taken to avoid syntax errors. Here is an example of correctly using a list parameter:
```plaintext
-- [params]
-- user_list :the_user_ids
SELECT SUM(length(bio_raw))
FROM user_profiles
WHERE user_id IN (:the_user_ids)
```
## Null Parameters
You can also allow for an empty input by prefixing the parameter type with `null`. This means that it’s not necessary to provide a value for that parameter when running the query.
Here’s some examples of how you would declare such parameters:
```plaintext
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
-- null current_user_id :me
```
In the above SQL, `null_int`, `null_boolean`, and `null_string` are parameters that can be left empty when running the query.
Let’s see how these types of parameters can be used in a query:
```plaintext
-- [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)
```
In this query, if `post_id` or `username` is not provided (i.e., left as `null`), the query will ignore that part of the WHERE clause. This allows for more flexible queries where some conditions are optional.
## Front-end Validation
Most types of parameters will be validated on the front end. These validations include required but unfilled inputs, invalid numeric input, non-existent categories or groups, malformed times, etc. For invalid input, the reason for the error will be displayed in the form, and the run query operation will be rejected.
## Choosing types and using casts
In general, parameters should ‘just work’ in your queries. For more advanced cases, you may need to add an explicit `::type` cast.
e.g. for intervals, you need to declare a string parameter and cast it to interval. Values can include units, such as 2 day or 3 hours:
```sql
-- [params]
-- string :lookback = 2 day
SELECT id AS topic_id, created_at
FROM topics
WHERE created_at >= NOW() - :lookback::interval
```
Some functions also need explicit argument types:
```sql
round(amount::numeric, :decimal_places::integer)
date_trunc('day', :start_date::timestamp)
```
## Additional Examples
Here are some additional examples of declaring different types of parameters:
```sql
-- [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
```
## More Topics in this Series
- [Data Explorer Tutorial - Part 1 - Writing Your First Query](https://meta.discourse.org/t/data-explorer-tutorial-part-1-writing-your-first-query/277925)
- [Data Explorer Tutorial - Part 2 - Discourse SQL Basics](https://meta.discourse.org/t/data-explorer-tutorial-part-2-discourse-sql-basics/277927)
- **This Topic**
- [Formatting Data Explorer Table Results](https://meta.discourse.org/t/formatting-data-explorer-table-results/277939)
---
### Author:  [@Lilly](https://meta.discourse.org/u/Lilly)
#### Post date: [September 5, 2023, 10:58pm UTC](https://meta.discourse.org/t/using-parameters-in-data-explorer-queries/277934/2 "2023-09-05T22:58:30Z")
These are great guides, thank you for posting them @SaraDev 🙂 🤗
---
### Author:  [@fbpbdmin](https://meta.discourse.org/u/fbpbdmin)
#### Post date: [October 21, 2023, 3:56pm UTC](https://meta.discourse.org/t/using-parameters-in-data-explorer-queries/277934/3 "2023-10-21T15:56:32Z")
@AlexDev
can a field name in where clause be a parameter ? thanks
or the whole sql statement be a parameter to pass in from the rest endpoint /admin/plugin/explorer/queries/id/run
---
### Author:  [@n1bff](https://meta.discourse.org/u/n1bff)
#### Post date: [October 23, 2023, 5:22pm UTC](https://meta.discourse.org/t/using-parameters-in-data-explorer-queries/277934/4 "2023-10-23T17:22:14Z")
PSA: You can not use numbers in your parameter names, e.g. “foo123” will fail.
```plaintext
-- [params]
-- string :foo123 = a
SELECT :foo123
```
results in
```plaintext
PG::SyntaxError: ERROR: syntax error at or near ":"
LINE 10: SELECT :foo123
^
```
---
### Author:  [@C\_X](https://meta.discourse.org/u/C_X)
#### Post date: [January 2, 2025, 12:38am UTC](https://meta.discourse.org/t/using-parameters-in-data-explorer-queries/277934/5 "2025-01-02T00:38:27Z")
I tried to POST call the run endpoint with parameters in the json payload as
```plaintext
payload = {
"params": {
"request_post_id": "45"
},
"explain": False
}
```
I reverse angineered the payload from chrome dev tab payload
Somehow I keep getting 500 server error
Can someone please help me?
---
### Author:  [@zogstrip](https://meta.discourse.org/u/zogstrip)
#### Post date: [December 13, 2025, 10:33am UTC](https://meta.discourse.org/t/using-parameters-in-data-explorer-queries/277934/6 "2025-12-13T10:33:39Z")
> [@SaraDev](#):
>
> ### Internal Parameters
>
> - `current_user_id`: No input UI; automatically sets the variable to the user ID of the user running the query
PSA: this was added recently by
[https://github.com/discourse/discourse/pull/36655](https://github.com/discourse/discourse/pull/36655)
---
### Author:  [@gormus](https://meta.discourse.org/u/gormus)
#### Post date: [February 10, 2026, 2:20pm UTC](https://meta.discourse.org/t/using-parameters-in-data-explorer-queries/277934/7 "2026-02-10T14:20:25Z")
_Feature request:_ Would it be possible to add `tag_group` as a parameter type which would inject the integer ID of the selected tag group?