Skip to main content
In Meilisearch, facets are a specialized type of filter. This guide shows you how to configure facets and use them when searching a database of books. It also gives you instruction on how to get facet value distributions and to search for specific facet values.

​
Configure facet index settings

First, create a new index using this books dataset. Documents in this dataset have the following fields: 
{
  "id": 5,
  "title": "Hard Times",
  "genres": ["Classics","Fiction", "Victorian", "Literature"],
  "publisher": "Penguin Classics",
  "language": "English",
  "author": "Charles Dickens",
  "description": "Hard Times is a novel of social […] ",
  "format": "Hardcover",
  "rating": 3
}
Next, add genres, language, and rating to the list of filterableAttributes: 
curl \
  -X PUT 'MEILISEARCH_URL/indexes/books/settings/filterable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "genres", "rating", "language"
  ]'
You have now configured your index to use these attributes as filters.

​
Use facets in a search query

Make a search query setting the facets search parameter: 
curl \
  -X POST 'MEILISEARCH_URL/indexes/books/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "classic",
    "facets": [
    "genres", "rating", "language"
  ]
}'
The response returns all books matching the query. It also returns two fields you can use to create a faceted search interface, facetDistribution and facetStats: 
{
  "hits": [
    …
  ],
  …
  "facetDistribution": {
    "genres": {
      "Classics": 6,
      …
    },
    "language": {
      "English": 6,
      "French": 1,
      "Spanish": 1
    },
    "rating": {
      "2.5": 1,
      …
    }
  },
  "facetStats": {
    "rating": {
      "min": 2.5,
      "max": 4.7
    }
  }
}
facetDistribution lists all facets present in your search results, along with the number of documents returned for each facet. facetStats contains the highest and lowest values for all facets containing numeric values.

​
Sorting facet values

By default, all facet values are sorted in ascending alphanumeric order. You can change this using the sortFacetValuesBy property of the faceting index settings: 
curl \
  -X PATCH 'MEILISEARCH_URL/indexes/books/settings/faceting' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "sortFacetValuesBy": {
      "genres": "count"
  }
}'
The above code sample sorts the genres facet by descending value count. Repeating the previous query using the new settings will result in a different order in facetsDistribution: 
{
  …
  "facetDistribution": {
    "genres": {
      "Fiction": 8,
      "Literature": 7,
      "Classics": 6,
      "Novel": 2,
      "Horror": 2,
      "Fantasy": 2,
      "Victorian": 2,
      "Vampires": 1,
      "Tragedy": 1,
      "Satire": 1,
      "Romance": 1,
      "Historical Fiction": 1,
      "Coming-of-Age": 1,
      "Comedy": 1
    },
   …
   }
}

​
Searching facet values

You can also search for facet values with the facet search endpoint: 
curl \
  -X POST 'MEILISEARCH_URL/indexes/books/facet-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "facetQuery": "c",
    "facetName": "genres"
}'
The following code sample searches the genres facet for values starting with c: The response contains a facetHits array listing all matching facets, together with the total number of documents that include that facet: 
{
  …
  "facetHits": [
    {
      "value": "Children's Literature",
      "count": 1
    },
    {
      "value": "Classics",
      "count": 6
    },
    {
      "value": "Comedy",
      "count": 2
    },
    {
      "value": "Coming-of-Age",
      "count": 1
    }
  ],
  "facetQuery": "c",
  …
}
You can further refine results using the q, filter, and matchingStrategy parameters. Learn more about them in the API reference.

​
Toggle facet search globally

By default, the facet search endpoint is enabled for all indexes. If you do not need facet search and want to speed up indexing, you can disable it with the facetSearch index setting: 
curl \
  -X PUT 'MEILISEARCH_URL/indexes/books/settings/facet-search' \
  -H 'Content-Type: application/json' \
  --data-binary 'false'
Setting facetSearch to false disables the /indexes/{index_uid}/facet-search endpoint for this index. Documents are still indexed for regular facet distribution, but Meilisearch skips the additional processing needed for facet search, resulting in faster indexing. To re-enable facet search, send the same request with true.

​
Get exact facet counts

By default, the facet counts returned by the facet search endpoint are estimates. This is faster but may not be perfectly accurate for large datasets. To get exact facet counts, set the exhaustiveFacetCount parameter to true in your facet search request: 
curl \
  -X POST 'MEILISEARCH_URL/indexes/books/facet-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "facetName": "genres",
    "facetQuery": "c",
    "exhaustiveFacetCount": true
  }'
Exact counts are slower to compute, especially on large indexes. Use this option when precision matters more than speed, for example when displaying category counts in a storefront.