Multi-search - Meilisearch Documentation

The /multi-search route allows you to perform multiple search queries on one or more indexes by bundling them into a single HTTP request. Multi-search is also known as federated search.

Perform a multi-search

Bundle multiple search queries in a single API request. Use this endpoint to search through multiple indexes at once.

POST

/multi-search

Body

Name	Type	Description
`federation`	Object	If present and not `null`, returns a single list merging all search results across all specified queries
`queries`	Array of objects	Contains the list of search queries to perform. The `indexUid` search parameter is required, all other parameters are optional

If Meilisearch encounters an error when handling any of the queries in a multi-search request, it immediately stops processing the request and returns an error message. The returned message will only address the first error encountered.

`federation`

Use federation to receive a single list with all search results from all specified queries, in descending ranking score order. This is called federated search.

federation may optionally contain the following parameters:

Parameter	Type	Default value	Description
`offset`	Integer	`0`	Number of documents to skip
`limit`	Integer	`20`	Maximum number of documents returned
`facetsByIndex`	Object of arrays	`null`	Display facet information for the specified indexes
`mergeFacets`	Object	`null`	Display facet information for the specified indexes

If federation is missing or null, Meilisearch returns a list of multiple search result objects, with each item from the list corresponding to a search query in the request.

`facetsByIndex`

facetsByIndex must be an object. Its keys must correspond to indexes in your Meilisearch project. Each key must be associated with an array of attributes in the filterable attributes list of that index:

"facetsByIndex": {
  "INDEX_A": ["ATTRIBUTE_X", "ATTRIBUTE_Y"],
  "INDEX_B": ["ATTRIBUTE_Z"]
}

When you specify facetsByIndex, multi-search responses include an extra facetsByIndex field. The response’s facetsByIndex is an object with one field for each queried index:

{
  "hits" [ … ],
  …
  "facetsByIndex": {
    "INDEX_A": {
      "distribution": {
        "ATTRIBUTE_X": {
          "KEY": <Integer>,
          "KEY": <Integer>,
          …
        },
        "ATTRIBUTE_Y": {
          "KEY": <Integer>,
          …
        }
      },
      "stats": {
        "KEY": {
          "min": <Integer>,
          "max": <Integer>
        }
      }
    },
    "INDEX_B": {
      …
    }
  }
}

`mergeFacets`

mergeFacets must be an object and may contain the following fields:

maxValuesPerFacet: must be an integer. When specified, indicates the maximum number of returned values for a single facet. Defaults to the value assigned to the maxValuesPerFacet index setting

When both facetsByIndex and mergeFacets are present and not null, facet information included in multi-search responses is merged across all queried indexes. Instead of facetsByIndex, the response includes two extra fields: facetDistribution and facetStats:

{
  "hits": [ … ],
  …
  "facetDistribution": {
    "ATTRIBUTE": {
      "VALUE": <Integer>,
      "VALUE": <Integer>
    }
  },
  "facetStats": {
    "ATTRIBUTE": {
      "min": <Integer>,
      "max": <Integer>
    }
  }
}

Merge algorithm for federated searches

Federated search’s merged results are returned in decreasing ranking score. To obtain the final list of results, Meilisearch compares with the following procedure:

Detailed ranking scores are normalized in the following way for both hits:
1. Consecutive relevancy scores (related to the rules words, typo, attribute, exactness or vector) are grouped in a single score for each hit
2. sort and geosort score details remain unchanged
Normalized detailed ranking scores are compared lexicographically for both hits:
1. If both hits have a relevancy score, then the bigger score wins. If it is a tie, move to next step
2. If one result has a relevancy score or a (geo)sort score, Meilisearch picks it
3. If both results have a sort or geosort score in the same sorting direction, then Meilisearch compares the values according to the common sort direction. The result with the value that must come first according to the common sort direction wins. If it is a tie, go to the next step
4. Compare the global ranking scores of both hits to determine which comes first, ignoring any sorting or geosorting
5. In the case of a perfect tie, documents from the query with the lowest rank in the queries array are preferred.

Meilisearch considers two documents the same if:

They come from the same index
And their primary key is the same

There is no way to specify that two documents should be treated as the same across multiple indexes.

`queries`

queries must be an array of objects. Each object may contain the following search parameters:

Search parameter	Type	Default value	Description
`federationOptions`	Object	`null`	Configure federation settings for a specific query
`indexUid`	String	N/A	`uid` of the requested index
`q`	String	`""`	Query string
`offset`	Integer	`0`	Number of documents to skip
`limit`	Integer	`20`	Maximum number of documents returned
`hitsPerPage`	Integer	`1`	Maximum number of documents returned for a page
`page`	Integer	`1`	Request a specific page of results
`filter`	String	`null`	Filter queries by an attribute’s value
`facets`	Array of strings	`null`	Display the count of matches per facet
`distinct`	String	`null`	Restrict search to documents with unique values of specified attribute
`attributesToRetrieve`	Array of strings	`["*"]`	Attributes to display in the returned documents
`attributesToCrop`	Array of strings	`null`	Attributes whose values have to be cropped
`cropLength`	Integer	`10`	Maximum length of cropped value in words
`cropMarker`	String	`"…"`	String marking crop boundaries
`attributesToHighlight`	Array of strings	`null`	Highlight matching terms contained in an attribute
`highlightPreTag`	String	`"<em>"`	String inserted at the start of a highlighted term
`highlightPostTag`	String	`"</em>"`	String inserted at the end of a highlighted term
`showMatchesPosition`	Boolean	`false`	Return matching terms location
`sort`	Array of strings	`null`	Sort search results by an attribute’s value
`matchingStrategy`	String	`last`	Strategy used to match query terms within documents
`showRankingScore`	Boolean	`false`	Display the global ranking score of a document
`showRankingScoreDetails`	Boolean	`false`	Adds a detailed global ranking score field
`rankingScoreThreshold`	Number	`null`	Excludes results with low ranking scores
`attributesToSearchOn`	Array of strings	`["*"]`	Restrict search to the specified attributes
`hybrid`	Object	`null`	Return results based on query keywords and meaning
`vector`	Array of numbers	`null`	Search using a custom query vector
`retrieveVectors`	Boolean	`false`	Return document vector data
`locales`	Array of strings	`null`	Explicitly specify languages used in a query

Unless otherwise noted, search parameters for multi-search queries function exactly like search parameters for the /search endpoint.

`limit`, `offset`, `hitsPerPage` and `page`

These options are not compatible with federated searches.

`federationOptions`

federationOptions must be an object. It accepts the following parameters:

weight: serves as a multiplicative factor to ranking scores of search results in this specific query. If < 1.0, the hits from this query are less likely to appear in the final results list. If > 1.0, the hits from this query are more likely to appear in the final results list. Must be a positive floating-point number. Defaults to 1.0
remote experimental: indicates the remote instance where Meilisearch will perform the query. Must be a string corresponding to a remote object. Defaults to null

Response

The response to /multi-search queries may take different shapes depending on the type of query you’re making.

Non-federated multi-search requests

Name	Type	Description
`results`	Array of objects	Results of the search queries in the same order they were requested in

Each search result object is composed of the following fields:

Name	Type	Description
`indexUid`	String	`uid` of the requested index
`hits`	Array of objects	Results of the query
`offset`	Number	Number of documents skipped
`limit`	Number	Number of documents to take
`estimatedTotalHits`	Number	Estimated total number of matches
`totalHits`	Number	Exhaustive total number of matches
`totalPages`	Number	Exhaustive total number of search result pages
`hitsPerPage`	Number	Number of results on each page
`page`	Number	Current search results page
`facetDistribution`	Object	Distribution of the given facets
`facetStats`	Object	The numeric `min` and `max` values per facet
`processingTimeMs`	Number	Processing time of the query
`query`	String	Query originating the response

Federated multi-search requests

Federated search requests return a single object and the following fields:

Name	Type	Description
`hits`	Array of objects	Results of the query
`offset`	Number	Number of documents skipped
`limit`	Number	Number of documents to take
`estimatedTotalHits`	Number	Estimated total number of matches
`processingTimeMs`	Number	Processing time of the query
`facetsByIndex`	Object	Data for facets present in the search results
`facetDistribution`	Object	Distribution of the given facets
`facetStats`	Object	The numeric `min` and `max` values per facet
`remoteErrors`	Object	Indicates which remote requests failed and why

Each result in the hits array contains an additional _federation field with the following fields:

Name	Type	Description
`indexUid`	String	Index of origin for this document
`queriesPosition`	Number	Array index number of the query in the request’s `queries` array
`remote`	String	Remote instance of origin for this document
`weightedRankingScore`	Number	The product of the _rankingScore of the hit and the weight of the query of origin.

Example

Non-federated multi-search

curl \
  -X POST 'MEILISEARCH_URL/multi-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "queries": [
      {
        "indexUid": "movies",
        "q": "pooh",
        "limit": 5
      },
      {
        "indexUid": "movies",
        "q": "nemo",
        "limit": 5
      },
      {
        "indexUid": "movie_ratings",
        "q": "us"
      }
    ]
  }'

Response: `200 Ok`

{
  "results": [
    {
      "indexUid": "movies",
      "hits": [
        {
          "id": 13682,
          "title": "Pooh's Heffalump Movie",
          …
        },
        …
      ],
      "query": "pooh",
      "processingTimeMs": 26,
      "limit": 5,
      "offset": 0,
      "estimatedTotalHits": 22
    },
    {
      "indexUid": "movies",
      "hits": [
        {
          "id": 12,
          "title": "Finding Nemo",
          …
        },
        …
      ],
      "query": "nemo",
      "processingTimeMs": 5,
      "limit": 5,
      "offset": 0,
      "estimatedTotalHits": 11
    },
    {
      "indexUid": "movie_ratings",
      "hits": [
        {
          "id": "Us",
          "director": "Jordan Peele",
          …
        }
      ],
      "query": "Us",
      "processingTimeMs": 0,
      "limit": 20,
      "offset": 0,
      "estimatedTotalHits": 1
    }
  ]
}

Federated multi-search

curl \
  -X POST 'MEILISEARCH_URL/multi-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "federation": {},
    "queries": [
      {
        "indexUid": "movies",
        "q": "batman"
      },
      {
        "indexUid": "comics",
        "q": "batman"
      }
    ]
  }'

Response: `200 Ok`

{
  "hits": [
    {
      "id": 42,
      "title": "Batman returns",
      "overview": …, 
      "_federation": {
        "indexUid": "movies",
        "queriesPosition": 0
      }
    },
    {
      "comicsId": "batman-killing-joke",
      "description": …,
      "title": "Batman: the killing joke",
      "_federation": {
        "indexUid": "comics",
        "queriesPosition": 1
      }
    },
    …
  ],
  "processingTimeMs": 0,
  "limit": 20,
  "offset": 0,
  "estimatedTotalHits": 2,
  "semanticHitCount": 0
}

Remote federated multi-search experimental

curl \
  -X POST 'MEILISEARCH_URL/multi-search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "federation": {},
    "queries": [
      {
        "indexUid": "movies",
        "q": "batman",
        "federationOptions": {
          "remote": "ms-00"
        }
      },
      {
        "indexUid": "movies",
        "q": "batman",
        "federationOptions": {
          "remote": "ms-01"
        }
      }
    ]
  }'

Response: `200 Ok`

{
  "hits": [
    {
      "id": 42,
      "title": "Batman returns",
      "overview": …, 
      "_federation": {
        "indexUid": "movies",
        "queriesPosition": 0,
        "weightedRankingScore": 1.0,
        "remote": "ms-01"
    }
    },
    {
      "id": 87,
      "description": …,
      "title": "Batman: the killing joke",
      "_federation": {
        "indexUid": "movies",
        "queriesPosition": 1,
        "weightedRankingScore": 0.9848484848484849,
        "remote": "ms-00"
      }
    },
    …
  ],
  "processingTimeMs": 35,
  "limit": 5,
  "offset": 0,
  "estimatedTotalHits": 111,
  "remoteErrors": {
    "ms-02": {
      "message": "error sending request",
      "code": "proxy_could_not_send_request",
      "type": "system",
      "link": "https://docs.meilisearch.com/errors#proxy_could_not_make_request"
    }
  }
}

API reference

Errors

​Perform a multi-search

​Body

​federation

facetsByIndex

mergeFacets

Merge algorithm for federated searches

​queries

limit, offset, hitsPerPage and page

federationOptions

​Response

​Non-federated multi-search requests

​Federated multi-search requests

​Example

​Non-federated multi-search

Response: 200 Ok

​Federated multi-search

Response: 200 Ok

​Remote federated multi-search experimental

Response: 200 Ok

Perform a multi-search

Body

`federation`

`facetsByIndex`

`mergeFacets`

`queries`

`limit`, `offset`, `hitsPerPage` and `page`

`federationOptions`

Response

Non-federated multi-search requests

Federated multi-search requests

Example

Non-federated multi-search

Response: `200 Ok`

Federated multi-search

Response: `200 Ok`

Remote federated multi-search experimental

Response: `200 Ok`