Skip to main content
  • Type: list<string>
  • Default: [](no facets retrieved)
  • Scope: search
The facets parameter lets you retrieve facet values and their match counts for each specified attribute. For each specified attribute, such as color, size, or category, the response includes:
  • A list of facet values (for example: blue, red, small)
  • The number of matching records for each value
  • An exhaustive object indicating whether the values or counts are complete
To learn more, see Retrieve facets.

​
Usage

  • To retrieve counts for all available facets, use the wildcard: ["*"].
  • Declare all attributes you want to facet on with attributesForFaceting.
  • Facets don’t filter results. Use the filters parameter to apply filtering.
  • Facet values are sorted by frequency by default. Use sortFacetValuesBy to change the sort order.
  • Each facet value is truncated to a maximum of 1,000 characters.
  • The number of facet values returned per facet is limited by maxValuesPerFacet (default: 100, max: 1,000).
  • The response includes two optional properties:
    • facetsCount: true if facet counts are complete, false if facet counts are approximate.
    • facetValues: true if all facet values were retrieved, false otherwise.
There’s no hard limit on the number of attributes you can include, but adding too many can slow down getSettings operations and degrade performance in the Algolia dashboard.

​
Example

Current API clients

var response = await client.SearchSingleIndexAsync<Hit>(
  "ALGOLIA_INDEX_NAME",
  new SearchParams(
    new SearchParamsObject
    {
      Query = "query",
      Facets = new List<string> { "category", "author" },
    }
  )
);

index.Search(new Query("query")
{
    Facets = new List{ "category", "author" }
});
The example response shows three matches for “Jhon” in the author facet and one in the category facet for “Classical”. The facet count is exact. 
{
  "facets": {
    "author": {
      "Jhon": 3,
    },
    "category": {
      "Classical": 1,
    }
  },
  "exhaustiveFacetsCount": true,
  "exhaustive": {
    "facetsCount": true
  },
  "hits": {
    //...
  }
}