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:

• 🔴 Omitting the Content-Type header returns a missing_content_type error.
• 🔴 Sending an empty Content-Type returns an invalid_content_type error.
• 🔴 Sending a different Content-Type than application/json returns an invalid_content_type error.
• 🔴 Sending an empty payload returns a missing_payload error.
• 🔴 Sending an invalid JSON payload returns a malformed_payload error.

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.

• 🔴 Omitting facetName returns a missing_facet_search_facet_name error.
• 🔴 Sending a value with a different type than String for facetName returns a invalid_facet_search_facet_name error.
• 🔴 Sending a field not defined as a filterableAttributes for facetname returns an invalid_facet_search_facet_name error.

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.

• 🔴 Sending a value with a different type than String or null for facetQuery returns an invalid_facet_search_facet_query error.

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.

3.3.1.1. facetHit Object Properties

facetHit sorting is controlled by the sortFacetValuesBy index setting.

Field	Type	Required
value	String	True
count	Integer	True

3.3.1.1.1. value

• Type: String
• Required: True

The facet value being matched.

3.3.1.1.2. 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