This page lists the changes to the /multi-search route to allow for federated search.

A federated search is a multi-search in which the results of the various queries are combined in some way instead of returned serially.

Implementation status

• Finished design
• Finished implementation
• Released in v1.10

API/behavior changes

Add federation to /multi-search requests

POST /multi-search requests may now include an optional federation key.

• If the federation key is included and non null, then the multi-search returns a single search result object, whose list of hits is built by merging the hits coming from all the queries, in descending ranking score order.
• If the federation key is missing or null, then the multi-search behaves as in v1.9, returning a list of search result objects, with each search result item from the list corresponding to a search query in the request.

POST /multi-search
{
  // ✨NEW✨ 
  // null, or an object with the described fields
  // optional, defaults to `null`
  // if `null`, the behavior of the multi-search is the same as in v1.9
  "federation": {
    // number of results in the merged list
    // optional, defaults to 20
    "limit": 20,
    // number of results to skip in the merged list
    // optional, defaults to 0
	  "offset": 0,
  }
  // same as before
  "queries": [
    {
      "q": "Batman",
      "indexUid": "movies"
		  // the following attributes cause an error if present:
      // "offset", "limit", "page", "hitsPerPage"
      // "facets" is **ignored** if present
    },
    {
      "q": "Batman",
      "indexUid": "comics"
    }
  ]
}

A response to a federated search call looks like the following:

{
  hits: [
    {
      "id": 42,
      "title": "Batman returns",
      "overview": "..", 
      // ✨NEW✨
      // `_federation` field injected in the returned hit, indicating the
      // index of origin and query index of origin
      "_federation": {
        // index of origin of this document
        "indexUid": "movies",
        // index of the query in the `queries` array that caused this document
        // to appear in the hits at this rank
        "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,
}

Merge algorithm

The merged results are returned in decreasing ranking score. Results from different queries must be compatible for the comparison to be possible. Otherwise, an invalid_multi_search_ranking_rules_query_ranking_rules error is returned.

The ranking scores are compared in the following way: