Multi-Search API (Federated and Union Search)

The multi-search API batches multiple search requests into one HTTP request, avoiding the round-trip latency of sending each request separately. It supports two response modes:

• Federated search returns a separate result set for each search request.
• Union search combines the matches from all search requests into a single ranked result set.

Federated search

Federated search works well when a UI needs distinct results from several sources. For example, an ecommerce UI can query products and brands collections in parallel and display each result set separately:

Sample Response

Definition

POST ${TYPESENSE_HOST}/multi_search

TIP

For federated search, the results array in a multi_search response is guaranteed to be in the same order as the queries you send in the searches array in your request.

Union search

The search results returned by each of the search queries in a multi_search request can be merged into a single ordered set of hits via the union option.

In the following example, we are making two different search requests to the same collection (although different collections can also be mentioned). Each search query is filtering the posts collection by two different usernames.

Since the union property is set to true, the response from each of these two search queries will be merged into a single ordered set of hits.

curl 'http://localhost:8108/multi_search?page=1&per_page=2' -X POST \
     -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '
{
  "union": true,
  "searches": [
    {
      "collection": "posts",
      "q": "*",
      "filter_by": "user_name:stark_industry"
    },
    {
      "collection": "posts",
      "q": "*",
      "filter_by": "user_name:rogers_steve"
    }
  ]
}'

Sample Response

Unlike SQL, results of any search requests can be merged regardless of the type or count of fields mentioned in query_by, include_fields, exclude_fields, etc. Since the results of each search are merged into one final result, union differs from multi_search in the following ways:

• The pagination parameters (page, per_page, offset, limit, and limit_hits) of individual searches are ignored. Only global pagination parameters passed as query parameters are considered.
• Sorting requires the type, count, and order of the sorting fields of every search request to be the same. For example:

{
  "union": true,
  "searches": [
    {
      ...
      "sort_by": "user_name:asc"
      ...
    },
    {
      ...
      "sort_by": "rating:asc"
      ...
    }
  ]
}

will return an error since the types (user_name: string, rating: float) are different.

Removing Duplicates in Union Search

Union search removes duplicates by default. Which can be turned off using the remove_duplicates: false flag.

Grouping with Union

Union supports group_by operations with flag group_by params in searches like below,

curl 'http://localhost:8108/multi_search?page=1&per_page=2' -X POST \
     -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" -d '
{
  "union": true,
  "searches": [
    {
      "collection": "posts",
      "q": "*",
      "filter_by": "user_name:stark_industry",
      "group_by": "content",
      "group_limit": 2
    },
    {
      "collection": "comments",
      "q": "*",
      "filter_by": "user_name:rogers_steve",
      "group_by": "content"
    }
  ]
}'

NOTE: Union searches with grouping should be uniform in shape. i.e either all searches should contain grouping params or none of them.

multi_search Parameters

You can use any of the Search Parameters here for each individual search operation within a multi_search request.

In addition, you can use the following parameters with multi_search requests:

Parameter	Required	Description
limit_multi_searches	no	Max number of search requests that can be sent in a multi-search request. Eg: 20 Default: 50 You want to generate a scoped API key with this parameter embedded and use that API key to perform the search, so it's automatically applied and can't be changed at search time.
x-typesense-api-key	no	You can embed a separate search API key for each search within a multi_search request. This is useful when you want to apply different embedded filters for each collection in individual scoped API keys.

Example UI Implementation

Here's a demo Frontend app that shows you how to implement a Federated Search UI: federated-search.typesense.org (opens new window).

Here's the source code for it: https://github.com/typesense/showcase-federated-search/blob/master/src/app.js (opens new window)