# Federated / Multi Search

Multi search allows you to make multiple search requests in a single HTTP request. It helps you avoid round-trip network latencies incurred otherwise if each of these requests are sent as separate HTTP requests.

You can use it in two different modes:

Federated search: each search request in the multi-search payload returns results as independently.
Union search: the response of each search request is merged into a single unified order.

# Federated search

With federated search, you can use amulti_search request to search across multiple collections in a single HTTP request, with the search results being independent of each other.

For eg: in an ecommerce products dataset, you can show results from both a "products" collection, and a "brands" collection to the user, by searching them in parallel with a multi_search request.

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.

# `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)

← Vector Search Voice Query →