## Quick Reference
```sql
-- @select-list-{NAME}: option1, option2
```
## Valid Values
`List`
A list of values to use in the select list options that will transform the SQL query based on the selected option.
## Full Example
{% tabs %}
{% tab title="SQL" %}
```sql
-- @title: Select List - Dynamic SQL query from user selection
-- @subtitle: An example SQL query which uses a dynaic SQL query from user selection
-- @formats: currency
-- @select-list-Channel: referral, coldcall, search, event
-- @chart: line
SELECT
TRUNC(date_closed, 'MONTH') as Month,
sum(amount) as Sales
FROM sales
WHERE Channel = '{{select-list-channel.selected}}'
GROUP BY Month
ORDER BY Month ASC;
```
{% endtab %}
{% tab title="Chart" %}
{% endtab %}
{% endtabs %}
## Use Cases
@select-list allows you to define a custom drop down selection that can be used as a variable within the query. This is useful when you have chart data that you want to change at the query level, including complex dynamic SQL.
@select-list allows you to create customizable reports using a single base query that the user can then select within the UI. @select-list allows you to consolidate certain queries which are very similar.
### Default First Value
The value of the select list is never null, therefore your SQL query does not need to handle the empty case. The first element in the @select-list is the default value.
If you want to simulate any/null/none, have your first select value be a value like 'none' or 'any' and handle this yourself in code.
### Templating Language
The templating language that processes the dynamic SQL is [Handlebars.js](https://handlebarsjs.com/). This allows for basic control flow (if/then/else), loops and equality checks.
```plsql
-- @chart: column
-- @series: TotalSold
-- @select-list-channel: All, Referral, Organic, Paid
SELECT
TRUNC(date_closed, 'MONTH') as Month,
sum(amount) as Sales
FROM sales
{{#if (eq select-list-channel.selected 'All')}}
-- Do nothing we are going to return all channels
{{else}}
WHERE Channel = '{{select-list-channel.selected}}'
{{/if}}
GROUP BY TRUNC(date_closed, 'MONTH')
ORDER BY TRUNC(date_closed, 'MONTH') ASC;
```
#### Handlebars Object Reference
The following variables are provided to the SQL script Handlebars processor that you can use in your handlebars logic.
```json5
{
//The value selected, defaults to the first value in the list
'select-list-channel': {
'selected': 'All'
'values': ['All', 'Referral', 'Organic', 'Paid']
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.chartsql.com/reference/directives/select-list.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.