API clients / Methods / Search

Mar 27, 2025

Search multiple indices

This is documentation for v3 of the PHP API clients, which is not the latest version. To see the documentation for the latest version, see PHP v4.

Required API Key: any key with the search ACL

Method signature

$client->multipleQueries(array queries)

$client->multipleQueries(array queries, [
  // All the following parameters are optional
  'strategy' => string,
  // + any requestOptions
])

client.multiple_queries(Array queries)

client.multiple_queries(Array queries, Hash opts = {
  # any searchParameters
  # any requestOptions
})

client.multipleQueries(array queries)

client.multipleQueries(array queries, {
  // All the following parameters are optional
  strategy: string,
  // + any requestOptions
})

client.multiple_queries(dict queries)
client.multiple_queries(dict queries, {
    # All the following parameters are optional
    'strategy' => string,
    # + any requestOptions
})

client.multipleQueries(
  queries: [IndexedQuery] ,
  strategy: MultipleQueriesStrategy = .none,
  requestOptions: RequestOptions? = nil,
  completion: Result<FacetSearchResponse> -> Void
)

suspend fun ClientSearch.multipleQueries(
    queries: List<IndexQuery>,
    strategy: MultipleQueriesStrategy? = null,
    requestOptions: RequestOptions? = null
): ResponseSearches

client.MultipleQueries(new MultipleQueriesRequest
{
  Queries = IEnumerable<MultipleQueries>,
  Strategy = String
},

  // All the following parameters are optional
  RequestOptions: RequestOptions
)

client.multipleQueries(
 new MultipleQueriesRequest( List<MultipleQueries> queries),
  Contact.class
)

client.multipleQueries(
 new MultipleQueriesRequest( List<MultipleQueries> queries, MultiQueriesStrategy strategy),
  Contact.class
)

client.multipleQueries(
 new MultipleQueriesRequest( List<MultipleQueries> queries),
  Contact.class
  RequestOptions requestOptions
)

client.multipleQueries(
 new MultipleQueriesRequest( List<MultipleQueries> queries, MultiQueriesStrategy strategy),
  Contact.class
  RequestOptions requestOptions
)

client.MultipleQueries([]IndexedQuery queries, string strategy)

client.MultipleQueries(
  []IndexedQuery queries,
  string strategy,
  requestOptions,
)

multiQueries(queries)
multiQueries(queries) strategy strategy
multiQueries(queries) strategy strategy options RequestOptions

See code examples

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:

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

You can use this method for a search query or facet search by specifying the type parameter to be “default” or “facet”.

You can only use up to 50 queries in a multiple queries request.

When using the method multiQueries, the request will not be tied to any specific index. As a result, when retrieving logs for a specific index, multiQueries logs won’t be retrieved.

Examples #

Multiple queries#

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Perform three queries in a single API call:
//  First query targets index `categories`
//  Second and third 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']);

1
2
3
4
5
6
7
8
9
10
# Perform three queries in a single API call:
# First query targets index `categories`
# Second and third queries target index `products`
res = client.multiple_queries([
  { indexName: 'categories', query: my_query_string, hitsPerPage: 3 },
  { indexName: 'products', query: my_query_string, filters: '_tags:promotion' },
  { indexName: 'products', query: my_query_string, hitsPerPage: 10 }
])

puts res['results']

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
const 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 three queries in a single API call:
//  First query targets index `categories`
//  Second and third queries target index `products`
client.multipleQueries(queries).then(({ results }) => {
  console.log(results);
});

1
2
3
4
5
6
7
8
9
10
# Perform three queries in a single API call:
# First query targets index `categories`
# Second and third 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'])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Perform three queries in a single API call:
//    First query target index `categories`
//    Second and third queries target index `products`
let queries: [IndexedQuery] = [
  .init(indexName: "categories", query: Query("electronics").set(\.hitsPerPage, to: 3)),
  .init(indexName: "products", query: Query("iPhone").set(\.hitsPerPage, to: 3).set(\.filters, to: "_tags:promotions")),
  .init(indexName: "products", query: Query("Galaxy").set(\.hitsPerPage, to: 10)),
]

client.multipleQueries(queries: queries) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
val queries = listOf(
    IndexQuery(
        IndexName("categories"),
        Query(query = "query string", hitsPerPage = 3)
    ),
    IndexQuery(
        IndexName("products"),
        Query(query = "query string", hitsPerPage = 3, filters = "_tags:promotion")
    ),
    IndexQuery(
        IndexName("products"),
        Query(query = "query string", hitsPerPage = 10)
    )
)

client.multipleQueries(queries)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// Perform three queries in a single API call:
//  First query targets index `categories`
//  Second and third queries target index `products`
var indexQueries = new List<MultipleQueries>
{
    new MultipleQueries
    {
      IndexName = "categories",
      Params = new Query(myQueryString) { HitsPerPage = 3 }
    },
    new MultipleQueries
    {
      IndexName = "products",
      Params = new Query(myQueryString) { HitsPerPage = 3, Filters = "_tags:promotion" }
    },
    new MultipleQueries
    {
      IndexName = "products",
      Params = new Query(myQueryString) { HitsPerPage = 10 }
    },
};

MultipleQueriesRequest request = new MultipleQueriesRequest
{
    Requests = indexQueries
};

var res = client.MultipleQueries<object>(request);

// Asynchronous
var res = await client.MultipleQueriesAsync<object>(request);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
//Sync version

// Perform three queries in a single API call:
//  First query targets index `categories`
//  Second and third queries target index `products`

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

MultipleQueriesResponse<Object> search = 
    client.multipleQueries(new MultipleQueriesRequest(queries), Contact.class);

//Async version
CompletableFuture<MultipleQueriesResponse<Object>> search = 
    client.multipleQueriesAsync(queries, Contact.class);

1
2
3
4
5
6
7
8
9
// Perform three queries in a single API call:
//  First query targets the `categories` index
//  Second and third queries target the `products` index
queries := []search.IndexedQuery{
  search.NewIndexedQuery("categories", opt.Query("computer"), opt.HitsPerPage(3)),
  search.NewIndexedQuery("products", opt.Query("computer"), opt.HitsPerPage(3), opt.Filters("_tags:promotion")),
  search.NewIndexedQuery("products", opt.Query("computer"), opt.HitsPerPage(10)),
}
res, err := client.MultipleQueries(queries, "")

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Perform three queries in a single API call:
//  First query targets index `categories`
//  Second and third 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#

Copy

1
2
3
4
5
6
7
$queries = [/* queries */];

$results = $client->multipleQueries($queries, [
  'X-Forwarded-For' => '94.228.178.246'
]);

var_dump($results['results']);

1
2
3
4
5
6
7
8
9
10
11
12
queries = [
  { index_name: 'categories', query: my_query_string, hitsPerPage: 3 },
  { index_name: 'products', query: my_query_string, filters: '_tags:promotion' },
]

res = client.multiple_queries(queries, {
  headers: {
    'X-Forwarded-For': '94.228.178.246'
  }
})

puts res['results']

1
2
3
4
5
6
7
8
9
const queries = [/* queries */];

client.multipleQueries(queries, {
  headers: {
    "X-Forwarded-For": "94.228.178.246"
  }
}).then(({ results }) => {
  console.log(results);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Perform three queries in a single API call:
# First query targets index `categories`
# Second and third queries target index `products`
results = client.multiple_queries(
    [
        {'indexName': 'categories', 'query': my_query_string, 'hitsPerPage': 3},
        {'indexName': 'products', 'query': my_query_string, 'filters': '_tags:promotion'},
        {'indexName': 'products', 'query': my_query_string, 'hitsPerPage': 10}
    ],
    {
        'X-Forwarded-For': '94.228.178.246'
    }
)

print(results['results'])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Perform three queries in a single API call:
//    First query target index `categories`
//    Second and third queries target index `products`
let queries: [IndexedQuery] = [
  .init(indexName: "categories", query: Query("electronics").set(\.hitsPerPage, to: 3)),
  .init(indexName: "products", query: Query("iPhone").set(\.hitsPerPage, to: 3).set(\.filters, to: "_tags:promotions")),
  .init(indexName: "products", query: Query("Galaxy").set(\.hitsPerPage, to: 10)),
]

var requestOptions = RequestOptions()
requestOptions.headers["X-Forwarded-For"] = "94.228.178.246"
client.multipleQueries(queries: queries, requestOptions: requestOptions) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
val queries = listOf(
    IndexQuery(
        IndexName("categories"),
        Query(query = "query string", hitsPerPage = 3)
    ),
    IndexQuery(
        IndexName("products"),
        Query(query = "query string", hitsPerPage = 3, filters = "_tags:promotion")
    ),
    IndexQuery(
        IndexName("products"),
        Query(query = "query string", hitsPerPage = 10)
    )
)
val requestOptions = requestOptions {
    header("X-Forwarded-For", "94.228.178.246")
}

client.multipleQueries(queries, requestOptions = requestOptions)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Perform three queries in a single API call:
//  First query targets index `categories`
//  Second and third queries target index `products`
var indexQueries = new List<MultipleQueries>
{
    new MultipleQueries
    {
      IndexName = "categories",
      Params = new Query(myQueryString) { HitsPerPage = 3 }
    },
    new MultipleQueries
    {
      IndexName = "products",
      Params = new Query(myQueryString) { HitsPerPage = 3, Filters = "_tags:promotion" }
    },
    new MultipleQueries
    {
      IndexName = "products",
      Params = new Query(myQueryString) { HitsPerPage = 10 }
    },
};

var requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Forwarded-For", "94.228.178.246" } }
};

MultipleQueriesRequest request = new MultipleQueriesRequest
{
    Requests = indexQueries
};

var res = client.MultipleQueries<object>(request, requestOptions);

// Asynchronous
var res = await client.MultipleQueriesAsync<object>(request, requestOptions);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
//Sync version

// Perform three queries in a single API call:
//  First query targets index `categories`
//  Second and third 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,
  Contact.class,
  new RequestOptions().addExtraHeader("X-Forwarded-For", "94.228.178.246")
);



//Async version

// Perform three queries in a single API call:
//  First query targets index `categories`
//  Second and third 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,
  Contact.class,
  new RequestOptions().addExtraHeader("X-Forwarded-For", "94.228.178.246")
);

1
2
3
4
5
6
7
8
9
10
11
12
13
// Perform three queries in a single API call:
//  First query targets the `categories` index
//  Second and third queries target the `products` index
queries := []search.IndexedQuery{
	search.NewIndexedQuery("categories", opt.Query("computer"), opt.HitsPerPage(3)),
	search.NewIndexedQuery("products", opt.Query("computer"), opt.HitsPerPage(3), opt.Filters("_tags:promotion")),
	search.NewIndexedQuery("products", opt.Query("computer"), opt.HitsPerPage(10)),
}

extraHeaders := opt.ExtraHeaders(map[string]string{
  "X-Forwarded-For": "94.228.178.246",
})
res, err := client.MultipleQueries(queries, "", extraHeaders)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Perform three queries in a single API call:
//  First query targets index `categories`
//  Second and third 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-Forwarded-For" => "94.228.178.246"))
  )
}

Parameters #


            queries

type: list of query object

Required

A list of queries to execute.


            strategy

type: string|enum

default: none

Optional

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

default: No request options

Optional

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

queries ➔ query object #

{
  indexName: "indexName",
  type: "default", // optional
  query: "search query",
  params: {
    searchParameter1: value1, // one or several search parameters
    searchParameter2: value2
  }
}

`indexName` #	type: string Required Name of the index to target.
`query` #	type: string Required The query to search in the index.
`type` #	type: string default: default Optional The type of query to perform. Can be either `default` for a regular search, or `facet` for a facet value search.
`params` #	type: key/value mapping default: No search parameters Optional A key/value mapping of any search parameters

Response #

This section shows the JSON response returned by the API. Each API client encapsulates this response inside objects specific to the programming language, so that the actual response might be different. You can view the response by using the getLogs method. Don’t rely on the order of attributes in the response, as JSON doesn’t guarantee the ordering of keys in objects.

JSON format#

Copy

          {
  "results": [
    {
      "hits": [
        {
          "firstname": "Jimmie",
          "lastname": "Barninger",
          "objectID": "433",
          "_highlightResult": {
            "firstname": {
              "value": "<em>Jimmie</em>",
              "matchLevel": "partial"
            },
            "lastname": {
              "value": "Barninger",
              "matchLevel": "none"
            },
            "company": {
              "value": "California <em>Paint</em> & 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": "<em>Jimmie</em>",
              "matchLevel": "partial"
            },
            "lastname": {
              "value": "Barninger",
              "matchLevel": "none"
            },
            "company": {
              "value": "California <em>Paint</em> & 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"
    }
  ]
}

        

Field Description


          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 object, and is therefore the same as the hits of the search method.

Each result also includes the following additional fields:

Field	Description
`index` #	string The name of the targeted index.
`processed` #	boolean Whether the query was processed. Only returned when `strategy` = `stopIfEnoughmatches`.

Did you find this page helpful?

Search multiple indices

About this method # Found an issue?

Examples # Found an issue?