# @groups

```sql
-- @groups: Month, Product
```

## Valid Types

`List`

A comma separated list of columns to use as categories

## Full Example

```sql
-- @chart: bar
-- @title: Groups - Multiple category groups
-- @subtitle: An example of multiple category groups
-- @groups: Channel, Owner
-- @series: TotalSales
-- @formats: currency
SELECT 
	Final.*
FROM (  
  SELECT 
  	Channel,    
  	Owner,
    (
      SELECT sum(Sub.Amount)
      FROM Sales Sub
      WHERE Sub.Channel = Sales.Channel
    ) as TotalChannelSales,
    sum(Amount) as TotalSales
  FROM Sales
  WHERE Owner IN (
    SELECT Owner
    FROM Sales
    GROUP BY Owner
    ORDER BY sum(Amount)
    LIMIT 10
  )
  GROUP BY Channel, Owner
) as Final
ORDER BY TotalChannelSales ASC, TotalSales ASC

```

<figure><img src="/files/dshQViJ2oCRwVQZwMsq3" alt=""><figcaption><p>An example bar chart grouped by a primary and secondary category</p></figcaption></figure>

| CHANNEL  | OWNER   | TOTALCHANNELSALES | TOTALSALES |
| -------- | ------- | ----------------- | ---------- |
| pr\_ad   | Kim     | 9181300.0         | 84603.0    |
| pr\_ad   | Roger   | 9181300.0         | 118985.0   |
| pr\_ad   | Lucy    | 9181300.0         | 138374.0   |
| pr\_ad   | Norbit  | 9181300.0         | 141711.0   |
| pr\_ad   | Justice | 9181300.0         | 160517.0   |
| pr\_ad   | Heather | 9181300.0         | 239870.0   |
| pr\_ad   | Peter   | 9181300.0         | 266655.0   |
| pr\_ad   | Tammy   | 9181300.0         | 501805.0   |
| coldcall | Justice | 1.7372264E7       | 87207.0    |
| coldcall | Heather | 1.7372264E7       | 162974.0   |
| coldcall | Norbit  | 1.7372264E7       | 333648.0   |
| coldcall | Tammy   | 1.7372264E7       | 335206.0   |
| coldcall | Roger   | 1.7372264E7       | 365129.0   |
| coldcall | Peter   | 1.7372264E7       | 725052.0   |
| search   | Lucy    | 3.3377707E7       | 139277.0   |
| search   | Kim     | 3.3377707E7       | 177605.0   |
| search   | Roger   | 3.3377707E7       | 223080.0   |
| search   | Grenda  | 3.3377707E7       | 333216.0   |

## Use Cases

Use groups to heirarchically group series columns together when you want to make visually distinct buckets. In the example above, without the @groups parameter, the chart would render without separating the parent category.

<figure><img src="/files/CkJ8IzlwLmRoTUmOC0JI" alt=""><figcaption><p>An example of a recordset with two groups but not rendering the groups</p></figcaption></figure>


---

# 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/groups.md?ask=<question>
```

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.