Facet search

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.

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

client.index('books').searchForFacetValues({
  facetQuery: 'fiction',
  facetName: 'genres'
  filter: 'rating > 3'
})

client.index('books').facet_search('genres', 'fiction', {
  'filter': 'rating > 3'
})

$client->index('books')->facetSearch(
  (new FacetSearchQuery())
      ->setFacetQuery('fiction')
      ->setFacetName('genres')
      ->setFilter(['rating > 3'])
);

FacetSearchRequest fsr = FacetSearchRequest.builder().facetName("genres").facetQuery("fiction").filter(new String[]{"rating > 3"}).build();
client.index("books").facetSearch(fsr);

client.index('books').facet_search('genres', 'fiction', filter: 'rating > 3')

client.Index("books").FacetSearch(&meilisearch.FacetSearchRequest{
  FacetQuery: "fiction",
  FacetName: "genres",
  Filter: "rating > 3",
})

var query = new SearchFacetsQuery()
{
  FacetQuery = "fiction",
  Filter = "rating > 3"
};
await client.Index("books").FacetSearchAsync("genres", query);

let res = client.index("books")
  .facet_search("genres")
  .with_facet_query("fiction")
  .with_filter("rating > 3")
  .execute()
  .await
  .unwrap();

await client.index('books').facetSearch(
      FacetSearchQuery(
        facetQuery: 'fiction',
        facetName: 'genres',
        filter: 'rating > 3',
      ),
    );

Response: `200 Ok`

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

API reference

Errors

Perform a facet search

Body

Response

Example

Response: `200 Ok`

​Perform a facet search

​Body

​Response

​Example

​Response: 200 Ok

Perform a facet search

Body

Response

Example

Response: `200 Ok`