Multi-search

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.

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

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:

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 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 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": [ … ],
  …
  "facetFederation": {
    "ATTRIBUTE": {
      "VALUE": <Integer>,
      "VALUE": <Integer>
    }
  },
  "facetStats": {
    "ATTRIBUTE": {
      "min": <Integer>,
      "max": <Integer>
    }
  }
}

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

1. 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
2. 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.

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

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

These options are not compatible with federated searches.

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

The response to /multi-search queries may take two shapes: federated and non-federated.

Each search result object is composed of the following fields:

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

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

curl \
  -X POST 'http://localhost:7700/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"
      }
    ]
  }'

{
  "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
    }
  ]
}

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

{
  "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
}