# 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.

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.

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

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

Last Updated: 2/15/2025, 10:06:12 PM