Search multiple indices

Required API Key: any key with the search ACL
Method signature
$client->multipleQueries(queries)
$client->multipleQueries(queries, 'indexName', strategy)
$client->multipleQueries(queries, 'indexName', strategy, requestOptions)
Method signature
client.multiple_queries(queries)
client.multiple_queries(queries, strategy=strategy)
client.multiple_queries(queries, request_options=requestOptions)
Method signature
client.search(queries, callback)
client.search(queries, { strategy: strategy }, callback)
Method signature
client.multiple_queries(queries)
client.multiple_queries(queries, strategy=strategy)
client.multiple_queries(queries, request_options=requestOptions)
Method signature
client.multipleQueries(queries, completionHandler)
client.multipleQueries(queries, strategy: strategy, completionHandler)
client.multipleQueries(
  queries,
  requestOptions: requestOptions,
  completionHandler
)

Method signature
client.multipleQueriesAsync(queries, strategy, completionHandler)
client.multipleQueriesAsync(queries, strategy, requestOptions, completionHandler)
Method signature
client.MultipleQueries(queries)
client.MultipleQueries(queries, strategy)
client.MultipleQueries(queries, requestOptions, strategy)
Method signature
client.multipleQueries(queries)
client.multipleQueries(queries, strategy)
client.multipleQueries(queries, requestOptions)
client.multipleQueries(queries, strategy, requestOptions)

Method signature
client.MultipleQueries(queries, "")
client.MultipleQueries(queries, strategy)

client.MultipleQueriesWithRequestOptions(queries, strategy, requestOptions)
Method signature
multiQueries(queries)
multiQueries(queries) strategy strategy
multiQueries(queries) strategy strategy options RequestOptions

About this method

Perform a search on several indices at the same time, with one method call.

The returned results are broken down by query.

This method can be used in several different kinds of situations. Here are two typical usage scenarios:

  1. You have multiple indices that serve different purposes. This is typical when you want to search your main index as well as an index that contains a history of searches (to be used for autocomplete).
  2. You want to target one index and send it multiple queries, where, for example, each query contains different settings or filters, or the query itself is slightly adjusted.

Note that for 2., you will want to use the “stopIfEnoughMatches” value of the strategy parameter.

Examples

Multiple queries

<?php
// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

$queries = [
  [
    'indexName' => 'categories',
    'query' => $myQueryString,
    'hitsPerPage' => 3
  ],
  [
    'indexName' => 'products',
    'query' => $myQueryString,
    'hitsPerPage' => 3,
    'facetFilters' => 'promotion'
  ],
  [
    'indexName' => 'products',
    'query' => $myQueryString,
    'hitsPerPage' => 10
  ]
];

$results = $client->multipleQueries($queries);

var_dump($results['results']);
# perform 3 queries in a single API call:
# - 1st query targets index `categories`
# - 2nd and 3rd queries target index `products`
res = Algolia.multiple_queries([
  { index_name: 'categories', query: my_query_string, hitsPerPage: 3 },
  { index_name: 'products', query: my_query_string, filters: '_tags:promotion' },
  { index_name: 'products', query: my_query_string, hitsPerPage: 10 }
])

puts res['results']
var client = algoliasearch('ApplicationID', 'apiKey');

var queries = [{
  indexName: 'categories',
  query: 'search in categories index',
  params: {
    hitsPerPage: 3
  }
}, {
  indexName: 'products',
  query: 'first search in products',
  params: {
    hitsPerPage: 3,
    filters: '_tags:promotion'
  }
}, {
  indexName: 'products',
  query: 'another search in products',
  params: {
    hitsPerPage: 10
  }
}];

// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`
client.search(queries, function searchCallback(err, content) {
  if (err) throw err;

  console.log(content.results);
});
# perform 3 queries in a single API call:
# - 1st query targets index `categories`
# - 2nd and 3rd queries target index `products`
results = client.multiple_queries([
    {"indexName": "categories", "query": myQueryString, "hitsPerPage": 3},
    {"indexName": "products", "query": myQueryString, "filters": "_tags:promotion"}
    {"indexName": "products", "query": myQueryString, "hitsPerPage": 3},
])

print results["results"]
// Perform 3 queries in a single API call:
//    - 1st query target index `categories`
//    - 2nd and 3rd queries target index `products`
let queries = [
    IndexQuery(indexName: "categories", query: Query(query: "electronics")),
    IndexQuery(indexName: "products", query: Query(query: "iPhone")),
    IndexQuery(indexName: "products", query: Query(query: "Galaxy"))
]
client.multipleQueries(queries, completionHandler: { (content, error) -> Void in
    if error == nil {
        print("Result: \(content!)")
    }
})
// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

List<IndexQuery> queries = new ArrayList<>();

queries.add(
  new IndexQuery(
    "categories",
    new Query(myQueryString)
      .setHitsPerPage(3)
    )
  );
queries.add(
  new IndexQuery(
    "products",
    new Query(myQueryString)
      .setHitsPerPage(3)
      .set("filters", "_tags:promotion")
  )
);
queries.add(
  new IndexQuery(
    "products",
    new Query(myQueryString)
      .setHitsPerPage(10)
  )
);

// Execute the sequence of queries until the end.
final MultipleQueriesStrategy strategy = MultipleQueriesStrategy.NONE;

client.multipleQueriesAsync(queries, strategy, new CompletionHandler() {
    @Override
    public void requestCompleted(JSONObject content, AlgoliaException error) {
        // [...]
    }
});
// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

var indexQueries = new List<IndexQuery>();

indexQueries.Add(
  new IndexQuery(
    "categories",
    new Query(myQueryString).SetNbHitsPerPage(3)
  )
);

indexQueries.Add(
  new IndexQuery(
    "products",
    new Query(myQueryString).SetNbHitsPerPage(3).SetFilters("_tags:promotion")
  );

indexQueries.Add(
  new IndexQuery(
    "products",
    new Query(MyQueryString).SetNbHitsPerPage(10)
  )
);

var res = client.MultipleQueries(indexQueries);
// Asynchronous
// var res = await client.MultipleQueriesAsync(indexQueries);

System.Diagnostics.Debug.WriteLine(res["results"]);
//Sync version

// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

List<IndexQuery> queries = Arrays.asList(
    new IndexQuery(
      "categories",
      new Query(myQueryString).setHitsPerPage(3)
    ),
    new IndexQuery(
      "products",
      new Query(myQueryString).setHitsPerPage(3).setFilters("_tags:promotion")
    ),
    new IndexQuery(
      "products",
      new Query(myQueryString).setHitsPerPage(10)
    )
);

MultiQueriesResult search = client.multipleQueries(queries);




//Async version

// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

List<IndexQuery> queries = Arrays.asList(
  new IndexQuery(
    "categories",
    new Query(myQueryString).setHitsPerPage(3)
  ),
  new IndexQuery(
    "products",
    new Query(myQueryString).setHitsPerPage(3).setFilters("_tags:promotion")
  ),
  new IndexQuery(
    "products",
    new Query(myQueryString).setHitsPerPage(10)
  )
);

CompletableFuture<MultiQueriesResult> search = client.multipleQueries(queries);
// Perform 3 queries in a single API call:
//  - 1st query targets the `categories` index
//  - 2nd and 3rd queries target the `products` index
queries := []algoliasearch.IndexedQuery{
  {
    IndexName: "categories",
    Params:    algoliasearch.Map{
      "query": "computer",
      "hitsPerPage": 3,
    },
  },
  {
    IndexName: "products",
    Params:    algoliasearch.Map{
      "query": "computer",
      "hitsPerPage": 3,
      "filters": "_tags:promotion",
    },
  },
  {
    IndexName: "products",
    Params:    algoliasearch.Map{
      "query": "computer",
      "hitsPerPage": 10,
    },
  },
}

res, err := client.MultipleQueries(queries, "")
// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

client.execute {
  multiQueries(
    search into "categories" query Query(
      query = myQueryString,
      hitsPerPage = Some(3)
    ),
    search into "products" query Query(
      query = myQueryString,
      hitsPerPage = Some(3),
      filters = Some("_tags:promotion")
    ),
    search into "products" query Query(
      query = myQueryString,
      hitsPerPage = Some(10)
    )
  ) strategy MultiQueries.Strategy.stopIfEnoughMatches
}

Multiple queries and send extra http headers

<?php
$queries = [/* queries */];

$extraHeaders = [
  'X-FORWARDED-FOR' => '94.228.178.246'
];

$results = $client->multipleQueries(
  $queries,
  'indexName',
  'none',
  $extraHeaders
);

var_dump($results['results']);
queries = []

extra_headers = {
  'X-FORWARDED-FOR': '94.228.178.246'
};

res = Algolia.multiple_queries(queries, { request_options: extra_headers })

puts res['results']
var client = algoliasearch('ApplicationID', 'apiKey');

// set the userId for this client
client.setExtraHeader('X-Algolia-User-ID', 'user123');

var queries = [/* queries */];

client.search(queries, function (err, content) {
  if (err) throw err;

  console.log(content.results);
});

# perform 3 queries in a single API call:
# - 1st query targets index `categories`
# - 2nd and 3rd queries target index `products`
request_options = RequestOptions({'forwardedFor': '94.228.178.246'})
results = client.multiple_queries(
  [
    {"indexName": "categories", "query": myQueryString, "hitsPerPage": 3},
    {"indexName": "products", "query": myQueryString, "filters": "_tags:promotion"},
    {"indexName": "products", "query": myQueryString, "hitsPerPage": 10}
  ],
  request_options=request_options
)

print results["results"]
// Perform 3 queries in a single API call:
//    - 1st query target index `categories`
//    - 2nd and 3rd queries target index `products`
let queries = [
    IndexQuery(indexName: "categories", query: Query(query: "electronics")),
    IndexQuery(indexName: "products", query: Query(query: "iPhone")),
    IndexQuery(indexName: "products", query: Query(query: "Galaxy"))
]

let requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"
client.multipleQueries(
  queries,
  requestOptions: requestOptions,
  completionHandler: { (content, error) -> Void in
    if error == nil {
        print("Result: \(content!)")
  }
})
// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

List<IndexQuery> queries = new ArrayList<>();

queries.add(
  new IndexQuery(
    "categories",
    new Query(myQueryString)
      .setHitsPerPage(3)
    )
  );
queries.add(
  new IndexQuery(
    "products",
    new Query(myQueryString)
      .setHitsPerPage(3)
      .set("filters", "_tags:promotion")
  )
);
queries.add(
  new IndexQuery(
    "products",
    new Query(myQueryString)
      .setHitsPerPage(10)
  )
);
// Execute the sequence of queries until the end.
final MultipleQueriesStrategy strategy = MultipleQueriesStrategy.NONE;

client.multipleQueriesAsync(queries, strategy, new RequestOptions()
  .setHeader("X-Algolia-User-ID", "94.228.178.246"), new CompletionHandler() {
    @Override
    public void requestCompleted(JSONObject content, AlgoliaException error) {
      // [...]
    }
});
// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

var indexQueries = new List<IndexQuery>();

indexQueries.Add(
  new IndexQuery(
    "categories",
    new Query(myQueryString).SetNbHitsPerPage(3)
  )
);

indexQueries.Add(
  new IndexQuery(
    "products",
    new Query(myQueryString).SetNbHitsPerPage(3).SetFilters("_tags:promotion")
  )
);

indexQueries.Add(
  new IndexQuery(
    "products",
    new Query(MyQueryString).SetNbHitsPerPage(10)
  )
);

RequestOptions requestOptions = new RequestOptions();
requestOptions.AddExtraHeader("X-Algolia-User-ID", "user123");

var res = _client.MultipleQueries(indexQueries, requestOptions);
// Asynchronous
// var res = await _client.MultipleQueriesAsync(indexQueries, requestOptions);

System.Diagnostics.Debug.WriteLine(res["results"]);
//Sync version

// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

List<IndexQuery> queries = Arrays.asList(
   new IndexQuery(
     "categories",
     new Query(myQueryString).setHitsPerPage(3)
   ),
   new IndexQuery(
     "products",
     new Query(myQueryString).setHitsPerPage(3).setFilters("_tags:promotion")
   ),
   new IndexQuery(
     "products",
     new Query(myQueryString).setHitsPerPage(10)
   )
);

MultiQueriesResult search = client.multipleQueries(
  queries,
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);



//Async version

// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

List<IndexQuery> queries = Arrays.asList(
  new IndexQuery(
   "categories",
   new Query(myQueryString).setHitsPerPage(3)
  ),
  new IndexQuery(
   "products",
   new Query(myQueryString).setHitsPerPage(3).setFilters("_tags:promotion")
  ),
  new IndexQuery(
   "products",
   new Query(myQueryString).setHitsPerPage(10)
  )
);

CompletableFuture<MultiQueriesResult> search = client.multipleQueries(
  queries,
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);
// Perform 3 queries in a single API call:
//  - 1st query targets the `categories` index
//  - 2nd and 3rd queries target the `products` index
queries := []algoliasearch.IndexedQuery{
  {
    IndexName: "categories",
    Params:    algoliasearch.Map{
      "query": "computer",
      "hitsPerPage": 3,
    },
  },
  {
    IndexName: "products",
    Params:    algoliasearch.Map{
      "query": "computer",
      "hitsPerPage": 3,
      "filters": "_tags:promotion",
    },
  },
  {
    IndexName: "products",
    Params:    algoliasearch.Map{
      "query": "computer",
      "hitsPerPage": 10,
    },
  },
}

opts := &algoliasearch.RequestOptions{
  ExtraHeaders: map[string]string{
    "X-Algolia-User-ID": "userID1",
  },
}

res, err := client.MultipleQueriesWithRequestOptions(queries, "", opts)
// perform 3 queries in a single API call:
//  - 1st query targets index `categories`
//  - 2nd and 3rd queries target index `products`

client.execute {
  multiQueries(
    search into "categories" query Query(
      query = myQueryString,
      hitsPerPage = Some(3)
    ),
    search into "products" query Query(
      query = myQueryString,
      hitsPerPage = Some(3),
      filters = Some("_tags:promotion")
    ),
    search into "products" query Query(
      query = myQueryString,
      hitsPerPage = Some(10)
    )
  ) strategy MultiQueries.Strategy.stopIfEnoughMatches options RequestOptions(
    extraHeaders = Some(Map("X-Algolia-User-ID" => "user123"))
  )
}

Parameters

queries
type: list of query object
Required
strategy
type: string|enum
Optional
default: none

The strategy of the query.

Can be one of the following values:

  • none: Execute the sequence of queries until the end.

    This is recommended when each query is of equal importance, meaning all records of all queries need to be returned.

  • stopIfEnoughMatches: Execute queries one by one, but stop as soon as the cumulated number of hits is at least hitsPerPage.

    This is recommended when each query is an alternative, and where, if the first returns enough records, there is no need to perform the remaining queries.

requestOptions
type: key value mapping
Optional
default: No request options

A mapping of request options to send along with the query.


queries ➔ query object
{
  indexName: indexName
  searchParameter1: value1, // one or several searchParameters
  searchParameter2: value2
}
indexName
type: string
Required

Name of the index to target.

searchParameters
type: key value mapping
Optional
default: No search parameters

A key/value mapping of any search parameters

Response

In this section we document the JSON response returned by the API. Each language will encapsulate this response inside objects specific to the language and/or the implementation. So the actual type in your language might differ from what is documented.

JSON format

{
  "results": [
    {
      "hits": [
        {
          "firstname": "Jimmie",
          "lastname": "Barninger",
          "objectID": "433",
          "_highlightResult": {
            "firstname": {
              "value": "&lt;em&gt;Jimmie&lt;/em&gt;",
              "matchLevel": "partial"
            },
            "lastname": {
              "value": "Barninger",
              "matchLevel": "none"
            },
            "company": {
              "value": "California &lt;em&gt;Paint&lt;/em&gt; & Wlpaper Str",
              "matchLevel": "partial"
            }
          }
        }
        ],
        "page": 0,
        "nbHits": 1,
        "nbPages": 1,
        "hitsPerPage": 20,
        "processingTimeMS": 1,
        "query": "jimmie paint",
        "params": "query=jimmie+paint&attributesToRetrieve=firstname,lastname&hitsPerPage=50"
        "index": "people"
    },
    {
      "hits": [
        {
          "firstname": "Jimmie",
          "lastname": "Barninger",
          "objectID": "433",
          "_highlightResult": {
            "firstname": {
              "value": "&lt;em&gt;Jimmie&lt;/em&gt;",
              "matchLevel": "partial"
            },
            "lastname": {
              "value": "Barninger",
              "matchLevel": "none"
            },
            "company": {
              "value": "California &lt;em&gt;Paint&lt;/em&gt; & Wlpaper Str",
              "matchLevel": "partial"
            }
          }
        }
        ],
        "page": 0,
        "nbHits": 1,
        "nbPages": 1,
        "hitsPerPage": 20,
        "processingTimeMS": 1,
        "query": "jimmie paint",
        "params": "query=jimmie+paint&attributesToRetrieve=firstname,lastname&hitsPerPage=50"
        "index": "famous_people"
    }
  ]
}
results
list of result

List of result in the order they were submitted, one element for each query.

{
  "results": [
    {
      [...],
      index: 'indexName'
      processed: true
    },
    [...]
  ]
}

results ➔ result

The results object contains the hits objet, and is therefore the same as the hits of the search method.

Each result also includes the following additional fields:

index
string

The name of the targeted index.

processed
boolean

Whether the query was processed. Only returned when strategy = stopIfEnoughmatches.

Php small white
PHP
Ruby small white
Ruby
Javascript small white
JavaScript
Python small white
Python
Swift small white
iOS
Android small white
Android
Csharp small white
C#
Java small white
Java
Go small white
Go
Scala small white
Scala
Php small white
PHP
Ruby small white
Ruby
Javascript small white
JavaScript
Python small white
Python
Swift small white
iOS
Android small white
Android
Csharp small white
C#
Java small white
Java
Go small white
Go
Scala small white
Scala