# Facet Search API

# 1. Summary

The facet search endpoint retrieves facet values from a query.

# 2. Motivation

When many values exist for a facet, end-users need to be able to discover non-show values they can select in order to refine their faceted search. Being able to search for values for a facet solves this need.

# 3. Functional Specification

Meilisearch exposes 1 route to perform facet search requests:

  • POST indexes/:index_uid/facet-search

  • πŸ”΄ Sending an invalid index uid format for the :index_uid path parameter returns an invalid_index_uid error.

  • πŸ”΄ If the index does not exist, the API returns an index_not_found error.

If a master key is used to secure a Meilisearch instance, the auth layer returns the following errors:

  • πŸ”΄ Accessing these routes without the Authorization header returns a missing_authorization_header error.
  • πŸ”΄ Accessing these routes with a key that does not have permissions (i.e. other than the master key) returns an invalid_api_key error.

POST HTTP verb errors:

# 3.1. Facet Search Payload Parameters

Field Type Required
facetName String True
facetQuery String False

# 3.1.1. facetName

  • Type: String
  • Required: True
  • Default: null

facetName contains the facet name to search values on.

# 3.1.2. facetQuery

  • Type: String
  • Required: False
  • Default: null

facetQuery contains the terms to search within the facet values of the facetName.

When facetQuery isn't specified, Meilisearch performs a placeholder search. A placeholder search returns all facet values for the searched facet, limited by the maxValuesPerFacet index setting. It supports prefix search It supports typo tolerance. Modifying the typo tolerance index setting impacts the behavior of the facet search.

Meilisearch only considers one term for facetQuery. e.g if "harry potter" is typed the facet search consider "harry potter" as one single term.

# 3.2. Additional Search Parameters

Additional search parameters can be injected to the facet search query. If additional search parameters are set, the method will return facet values that both:

  • Match the facet query
  • Are contained in the records matching the additional search parameters (q, filter, matchingStrategy)
Field Type Required
q String False
filter String False
matchingStrategy String False
  • πŸ”΄ These properties are validated as stipulated in their original specification and return the associated errors.

Non-listed search parameters are ignored if specified for the API call; no error is raised.

# 3.3. Search Response Properties

Field Type Required
facetHits Array[FacetHit] True
facetQuery String True
processingTimeMs Integer True

# 3.3.1. facetHits

  • Type: Array[FacetHit]
  • Required: True

Results of the facet search query as an array of facet hit.

FacetHit object represents a matched facet value for a facet search.

# facetHit Object Properties

facetHit sorting is controlled by the sortFacetValuesBy index setting.

Field Type Required
value String True
count Integer True
# value
  • Type: String
  • Required: True

The facet value being matched.

# count
  • Type: Integer
  • Required: True

The number of document containing the matched facet value.

# 3.3.2. facetQuery

  • Type: Integer
  • Required: True

Facet query originating the response.

# 3.3.3. processingTimeMs

  • Type: Integer
  • Required: True

Processing time of the facet search query in milliseconds.

# 2. Technical Details

# 2.1 Facet Containing Numbers Limitation

  • Numbers on the Meilisearch side are represented as float64 (opens new window) internally. When a user sends a number in a JSON document, it can be written in different ways but end up being the same number i.e. 12e4, 120000, 120000.0. There is an issue as to how to let the user find it if it is not written in the same way.
  • Another issue is that float64 numbers sometimes lack precision. You can write a number in your document i.e. 12.6758493, search for this exact same number and don’t find it. The reason is that numbers are stored in a different way and an exact search will not find them.

# 3. Future Possibilities

  • Add a property to customize the sort of returned facet values
  • Highlight parts matching the facet value from the facet query
  • Support for number search