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. You can configure how facets are sorted using the sortFacetValuesBy property of the faceting index settings.

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.

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

NameTypeDefault valueDescription
facetName *StringnullFacet name to search values on
facetQueryStringnullSearch query for a given facet value. If facetQuery isn’t specified, Meilisearch returns all facet values for the searched facet, limited to 100
qString""Query string
filterString*nullFilter queries by an attribute’s value
matchingStrategyString"last"Strategy used to match query terms within documents
attributesToSearchOnArray of stringsnullRestrict search to the specified attributes
exhaustiveFacetCountBooleanfalseReturn an exhaustive count of facets, up to the limit defined by maxTotalHits

​
Response

NameTypeDescription
facetHits.valueStringFacet value matching the facetQuery
facetHits.countIntegerNumber of documents with a facet value matching value
facetQueryStringThe original facetQuery
processingTimeMsNumberProcessing time of the query

​
Example

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
}

Was this page helpful?