Faceting

Faceting counts the unique values of a field across matching documents. Use facets to build filter navigation, category counts, and drill-down interfaces.

Basic Usage

Add facet_by to any search query:

GET /collections/products/documents/search?\
q=*&query_by=title&facet_by=category,brand
X-TYPESENSE-API-KEY: YOUR_API_KEY

The field must have "facet": true in the collection schema.

Response

Facet counts appear in the facet_counts array of the search response:

{
  "facet_counts": [
    {
      "field_name": "category",
      "counts": [
        {"value": "Footwear", "count": 42},
        {"value": "Electronics", "count": 31},
        {"value": "Sports", "count": 18}
      ],
      "stats": {
        "total_values": 5
      }
    },
    {
      "field_name": "brand",
      "counts": [
        {"value": "Nike", "count": 28},
        {"value": "Adidas", "count": 22}
      ],
      "stats": {
        "total_values": 15
      }
    }
  ]
}

Max Facet Values

Control how many facet values are returned per field:

max_facet_values=20

Default is 10. Facet values are returned in descending order by count.

Facet Query

Filter facet values by a prefix string. This is useful for type-ahead facet filtering:

facet_query=category:Foot

This returns only facet values for category that start with “Foot”.

Facets with Filters

Facet counts are computed after applying filter_by. This means facet values reflect the filtered result set:

q=*&query_by=title&filter_by=price:<100&facet_by=category

This returns category counts only for products under $100.

Facetable Field Types

The following field types support faceting when "facet": true is set:

  • string and string[]
  • int32, int64, and their array variants
  • float
  • bool

Facet Length Limits

The facet_by expression is limited to 2,048 characters.