# Multi-search API

# 1. Summary

The multi-search endpoint performs multiple search queries on one or more indexes by bundling them into a single request. Each search query has its own results set.

# 2. Motivation

  • Perform multiple queries in a single HTTP request

# 3. Functional Specification

Meilisearch exposes 1 route to perform multi-search requests:

  • POST /multi-search

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.

If any of the search queries fail to execute, the response returns the corresponding error instead of the array of results. If multiple queries fail, only the first encountered failure is returned.

POST HTTP verb errors:

# 3.1. Search Payload Parameters

Field Type Required
queries Array of Objects True

# 3.1.1. queries

  • Type: Object
  • Required: True

The queries object contains the list of search queries to perform.

Each element of this array is a JSON object with the required field indexUid, the uid of the index to be searched. Other fields of this object are optional, and identical to the ones in the existing search routes (qlimit, etc.).

# 3.2. Search Response Properties

Field Type Required
results Array[Object] True

# 3.2.1. results

  • Type: Array[Objets]
  • Required: True

Results of the search queries as an array of search results.

Each element in this array contains the results of the search queries in the same order they have been requested. Additionally to the usual fields returned by a search result, an indexUid field is present with the index UID on which the search has been performed.


Search queries:

   "queries": [ { "indexUid": "movie", "q": "wonder" }, { "indexUid": "books", "q": "king" } ]

Search results:

   "results": [ 
         "indexUid": "movie",
         "hits": [ { "title": "wonderwoman" } ],
         // other search results fields: processingTimeMs, limit, ...
         "indexUid": "books",
         "hits": [ { "title": "king kong theory" } ],
         // other search results fields: processingTimeMs, limit, ...

The other fields of an element from the results array are identical to the fields of the response from the other search routes.

# 2. Technical Details


# 3. Future Possibilities

  • Allow specifying an index uid pattern instead of an index uid to produce searches on all indexes matching the pattern.
  • Allow additional arguments to the request specifying a strategy to aggregate results from the multiple searches.