Grouping

Group search results by one or more field values. Each group contains the top matching documents, with configurable group limits and sort options.

Basic Usage

GET /collections/products/documents/search?\
q=shoes&query_by=title&group_by=brand&group_limit=3
X-TYPESENSE-API-KEY: YOUR_API_KEY

Parameters

Response Format

When group_by is used, the response uses grouped_hits instead of hits:

{
  "found": 150,
  "found_docs": 150,
  "out_of": 1000,
  "grouped_hits": [
    {
      "group_key": ["Nike"],
      "found": 42,
      "hits": [
        {"document": {"id": "1", "title": "Air Max", "brand": "Nike", "price": 129.99}},
        {"document": {"id": "5", "title": "Free Run", "brand": "Nike", "price": 99.99}},
        {"document": {"id": "8", "title": "Pegasus", "brand": "Nike", "price": 119.99}}
      ]
    },
    {
      "group_key": ["Adidas"],
      "found": 38,
      "hits": [
        {"document": {"id": "2", "title": "Ultraboost", "brand": "Adidas", "price": 179.99}},
        {"document": {"id": "6", "title": "Superstar", "brand": "Adidas", "price": 89.99}}
      ]
    }
  ]
}

Sorting Groups

Use _group_found in sort_by to sort groups by the number of matching documents:

sort_by=_group_found:desc

Within each group, documents follow the normal sort_by order.

Multi-Field Grouping

Group by multiple fields for composite groups:

group_by=brand,category

The group_key in the response will contain values for each grouped field.

Missing Values

By default, documents where the group_by field is missing or null are included in a separate group. Set group_missing_values=false to exclude them.