Facet search

The /facet-search route allows you to search for facet values.

The /facet-search route allows you to search for facet values. Facet search supports prefix search and typo tolerance. The returned hits are sorted lexicographically in ascending order.

Meilisearch does not support facet search on numbers. Convert numeric facets to strings to make them searchable.

Internally, Meilisearch represents numbers as float64. This means they lack precision and can be represented in different ways, making it difficult to search facet values effectively.

Perform a facet search

Search for a facet value within a given facet.

POST

/indexes/{index_uid}/facet-search

This endpoint will not work without first explicitly adding attributes to the filterableAttributes list. Learn more about facets in our dedicated guide.

Meilisearch’s facet search does not support multi-word facets and only considers the first term in thefacetQuery.

For example, searching for Jane will return Jane Austen, but searching for Austen will not return Jane Austen.

Body

Name	Type	Default value	Description
facetName *	String	null	Facet name to search values on
facetQuery	String	null	Search query for a given facet value. If facetQuery isn’t specified, Meilisearch returns all facet values for the searched facet, limited to 100
q	String	""	Query string
filter	String*	null	Filter queries by an attribute’s value
matchingStrategy	String	"last"	Strategy used to match query terms within documents
attributesToSearchOn	Array of strings	null	Restrict search to the specified attributes
exhaustiveFacetCount	Boolean	false	Return an exhaustive count of facets, up to the limit defined by maxTotalHits

Response

Name	Type	Description
facetHits.value	String	Facet value matching the facetQuery
facetHits.count	Integer	Number of documents with a facet value matching value
facetQuery	String	The original facetQuery
processingTimeMs	Number	Processing time of the query

Example

cURL

curl \
  -X POST 'MEILISEARCH_URL/indexes/books/facet-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "facetQuery": "fiction",
    "facetName": "genres",
    "filter": "rating > 3"
  }'

Response: 200 Ok

{
  "facetHits": [
    {
      "value": "fiction",
      "count": 7
    }
  ],
  "facetQuery": "fiction",
  "processingTimeMs": 0
}