> ## Documentation Index
> Fetch the complete documentation index at: https://nikita-shkoda.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Grouping

> Group results by a key and cap hits per group. Compiler mapping and result access patterns.

Backlinks: <a href="/projects/search-engine-for-typesense/v30/field-selection">Field Selection</a>, <a href="/projects/search-engine-for-typesense/v30/relation">Relation</a>

See example: <code>examples/demo\_shop/app/controllers/groups\_controller.rb</code>.

* <strong>State source</strong>: <code>Relation#group\_by(field, limit: nil, missing\_values: false)</code> stores normalized state in <code>@state\[:grouping]</code>
* <strong>Compiler</strong>: <code>Relation#to\_typesense\_params</code> emits Typesense params: <code>group\_by</code>, <code>group\_limit</code>, <code>group\_missing\_values</code>

```ruby theme={null}
rel = SearchEngine::Book.group_by(:author_id, limit: 1, missing_values: true)
# => { q: "*", query_by: "name, description", group_by: "author_id", group_limit: 1, group_missing_values: true }
```

| Call                                                                  | Params                                                                                                        |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| <code>.group\_by(:author\_id)</code>                                  | <code>group\_by: "author\_id"</code>                                                                          |
| <code>.group\_by(:author\_id, limit: 2)</code>                        | <code>group\_by: "author\_id"</code>, <code>group\_limit: 2</code>                                            |
| <code>.group\_by(:author\_id, missing\_values: true)</code>           | <code>group\_by: "author\_id"</code>, <code>group\_missing\_values: true</code>                               |
| <code>.group\_by(:author\_id, limit: 1, missing\_values: true)</code> | <code>group\_by: "author\_id"</code>, <code>group\_limit: 1</code>, <code>group\_missing\_values: true</code> |

```mermaid theme={null}
flowchart LR
  A[Relation#group_by] --> B[@state[:grouping]
  C[Compiler] --> D{ group_by, group_limit, group_missing_values }]
```

```ruby theme={null}
result = SearchEngine::Book.group_by(:author_id, limit: 2).to_a
res = SearchEngine::Book.group_by(:author_id, limit: 2).execute
```

Backlinks: <a href="https://github.com/lstpsche/search-engine-for-typesense#readme" target="_blank">README</a>, <a href="/projects/search-engine-for-typesense/v30/field-selection">Field Selection</a>

```json theme={null}
{"event":"search","collection":"books","status":200,"duration.ms":12.3,"cache":true,"ttl":60,"group_by":"author_id","group_limit":1,"group_missing_values":true}
```