Multi-search

Introduced 1.0

As the name suggests, the multi-search operation lets you bundle multiple search requests into a single request. OpenSearch then executes the searches in parallel, so you get back the response more quickly compared to sending one request per search. OpenSearch executes each search independently, so the failure of one doesn’t affect the others.

Path and HTTP methods

The Multi-search API uses the following paths:

  1. GET _msearch
  2. GET <index>/_msearch
  3. POST _msearch
  4. POST <index>/_msearch

Query parameters and metadata options

All parameters are optional. Some can also be applied per-search as part of each metadata line.

ParameterTypeDescriptionSupported in metadata line
allow_no_indicesBooleanWhether to ignore wildcards that don’t match any indexes. Default is true.Yes
cancel_after_time_intervalTimeThe time after which the search request will be canceled. Supported at both parent and child request levels. The order of precedence is:
1. Child-level parameter
2. Parent-level parameter
3. Cluster setting.
Default is -1.		Yes
css_minimize_roundtripsBooleanWhether OpenSearch should try to minimize the number of network round trips between the coordinating node and remote clusters (only applicable to cross-cluster search requests). Default is true.No
expand_wildcardsEnumExpands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are all, open, closed, hidden, and none. Default is open.Yes
ignore_unavailableBooleanIf an index or shard from the indexes list doesn’t exist, whether to ignore it rather than fail the query. Default is false.Yes
max_concurrent_searchesIntegerThe maximum number of concurrent searches. The default depends on your node count and search thread pool size. Higher values can improve performance, but risk overloading the cluster.No
max_concurrent_shard_requestsIntegerMaximum number of concurrent shard requests that each search executes per node. Default is 5. Higher values can improve performance, but risk overloading the cluster.No
pre_filter_shard_sizeIntegerDefault is 128.No
rest_total_hits_as_intStringWhether the hits.total property is returned as an integer (true) or an object (false). Default is false.No
search_typeStringAffects relevance score. Valid options are query_then_fetch and dfs_query_then_fetch. query_then_fetch scores documents using term and document frequencies for the shard (faster, less accurate), whereas dfs_query_then_fetch uses term and document frequencies across all shards (slower, more accurate). Default is query_then_fetch.Yes
typed_keysBooleanWhether to prefix aggregation names with their internal types in the response. Default is false.No

Metadata-only options

Some options can’t be applied as parameters to the entire request. Instead, you can apply them per-search as part of each metadata line. All are optional.

OptionTypeDescription
indexString, string arrayIf you don’t specify an index or multiple indexes as part of the URL (or want to override the URL value for an individual search), you can include it here. Examples include “logs-*” and [“my-store”, “sample_data_ecommerce”].
preferenceStringThe nodes or shards that you’d like to perform the search. This setting can be useful for testing, but in most situations, the default behavior provides the best search latencies. Options include _local, _only_local, _prefer_nodes, _only_nodes, and _shards. These last three options accept a list of nodes or shards. Examples include “_only_nodes:data-node1,data-node2” and “_shards:0,1.
request_cacheBooleanWhether to cache results, which can improve latency for repeat searches. Default is to use the index.requests.cache.enable setting for the index (which defaults to true for new indexes).
routingStringComma-separated custom routing values, for example, “routing”: “value1,value2,value3”.

Request body

The multi-search request body follows this pattern:

  1. Metadata\n
  2. Query\n
  3. Metadata\n
  4. Query\n
  • Metadata lines include options, such as which indexes to search and the type of search.
  • Query lines use the query DSL.

Just like the bulk operation, the JSON doesn’t need to be minified—spaces are fine—but it does need to be on a single line. OpenSearch uses newline characters to parse multi-search requests and requires that the request body end with a newline character.

Example request

The following example msearch API request runs queries against multiple indexes:

  1. GET _msearch
  2. { "index": "opensearch_dashboards_sample_data_logs"}
  3. { "query": { "match_all": {} }, "from": 0, "size": 10}
  4. { "index": "opensearch_dashboards_sample_data_ecommerce", "search_type": "dfs_query_then_fetch"}
  5. { "query": { "match_all": {} } }

copy

Example response

OpenSearch returns an array with the results of each search in the same order as the multi-search request.

  1. {
  2.   "took" : 2150,
  3.   "responses" : [
  4.     {
  5.       "took" : 2149,
  6.       "timed_out" : false,
  7.       "_shards" : {
  8.         "total" : 1,
  9.         "successful" : 1,
  10.         "skipped" : 0,
  11.         "failed" : 0
  12.       },
  13.       "hits" : {
  14.         "total" : {
  15.           "value" : 10000,
  16.           "relation" : "gte"
  17.         },
  18.         "max_score" : 1.0,
  19.         "hits" : [
  20.           {
  21.             "_index" : "opensearch_dashboards_sample_data_logs",
  22.             "_id" : "_fnhBXsBgv2Zxgu9dZ8Y",
  23.             "_score" : 1.0,
  24.             "_source" : {
  25.               "agent" : "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)",
  26.               "bytes" : 4657,
  27.               "clientip" : "213.116.129.196",
  28.               "extension" : "zip",
  29.               "geo" : {
  30.                 "srcdest" : "CN:US",
  31.                 "src" : "CN",
  32.                 "dest" : "US",
  33.                 "coordinates" : {
  34.                   "lat" : 42.35083333,
  35.                   "lon" : -86.25613889
  36.                 }
  37.               },
  38.               "host" : "artifacts.opensearch.org",
  39.               "index" : "opensearch_dashboards_sample_data_logs",
  40.               "ip" : "213.116.129.196",
  41.               "machine" : {
  42.                 "ram" : 16106127360,
  43.                 "os" : "ios"
  44.               },
  45.               "memory" : null,
  46.               "message" : "213.116.129.196 - - [2018-07-30T14:12:11.387Z] \"GET /opensearch_dashboards/opensearch_dashboards-1.0.0-windows-x86_64.zip HTTP/1.1\" 200 4657 \"-\" \"Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)\"",
  47.               "phpmemory" : null,
  48.               "referer" : "http://twitter.com/success/ellison-onizuka",
  49.               "request" : "/opensearch_dashboards/opensearch_dashboards-1.0.0-windows-x86_64.zip",
  50.               "response" : 200,
  51.               "tags" : [
  52.                 "success",
  53.                 "info"
  54.               ],
  55.               "timestamp" : "2021-08-02T14:12:11.387Z",
  56.               "url" : "https://artifacts.opensearch.org/downloads/opensearch_dashboards/opensearch_dashboards-1.0.0-windows-x86_64.zip",
  57.               "utc_time" : "2021-08-02T14:12:11.387Z",
  58.               "event" : {
  59.                 "dataset" : "sample_web_logs"
  60.               }
  61.             }
  62.           },
  63.           ...
  64.         ]
  65.       },
  66.       "status" : 200
  67.     },
  68.     {
  69.       "took" : 1473,
  70.       "timed_out" : false,
  71.       "_shards" : {
  72.         "total" : 1,
  73.         "successful" : 1,
  74.         "skipped" : 0,
  75.         "failed" : 0
  76.       },
  77.       "hits" : {
  78.         "total" : {
  79.           "value" : 4675,
  80.           "relation" : "eq"
  81.         },
  82.         "max_score" : 1.0,
  83.         "hits" : [
  84.           {
  85.             "_index" : "opensearch_dashboards_sample_data_ecommerce",
  86.             "_id" : "efnhBXsBgv2Zxgu9ap7e",
  87.             "_score" : 1.0,
  88.             "_source" : {
  89.               "category" : [
  90.                 "Women's Clothing"
  91.               ],
  92.               "currency" : "EUR",
  93.               "customer_first_name" : "Gwen",
  94.               "customer_full_name" : "Gwen Dennis",
  95.               "customer_gender" : "FEMALE",
  96.               "customer_id" : 26,
  97.               "customer_last_name" : "Dennis",
  98.               "customer_phone" : "",
  99.               "day_of_week" : "Tuesday",
  100.               "day_of_week_i" : 1,
  101.               "email" : "gwen@dennis-family.zzz",
  102.               "manufacturer" : [
  103.                 "Tigress Enterprises",
  104.                 "Gnomehouse mom"
  105.               ],
  106.               "order_date" : "2021-08-10T16:24:58+00:00",
  107.               "order_id" : 576942,
  108.               "products" : [
  109.                 {
  110.                   "base_price" : 32.99,
  111.                   "discount_percentage" : 0,
  112.                   "quantity" : 1,
  113.                   "manufacturer" : "Tigress Enterprises",
  114.                   "tax_amount" : 0,
  115.                   "product_id" : 22182,
  116.                   "category" : "Women's Clothing",
  117.                   "sku" : "ZO0036600366",
  118.                   "taxless_price" : 32.99,
  119.                   "unit_discount_amount" : 0,
  120.                   "min_price" : 14.85,
  121.                   "_id" : "sold_product_576942_22182",
  122.                   "discount_amount" : 0,
  123.                   "created_on" : "2016-12-20T16:24:58+00:00",
  124.                   "product_name" : "Jersey dress - black/red",
  125.                   "price" : 32.99,
  126.                   "taxful_price" : 32.99,
  127.                   "base_unit_price" : 32.99
  128.                 },
  129.                 {
  130.                   "base_price" : 28.99,
  131.                   "discount_percentage" : 0,
  132.                   "quantity" : 1,
  133.                   "manufacturer" : "Gnomehouse mom",
  134.                   "tax_amount" : 0,
  135.                   "product_id" : 14230,
  136.                   "category" : "Women's Clothing",
  137.                   "sku" : "ZO0234902349",
  138.                   "taxless_price" : 28.99,
  139.                   "unit_discount_amount" : 0,
  140.                   "min_price" : 13.05,
  141.                   "_id" : "sold_product_576942_14230",
  142.                   "discount_amount" : 0,
  143.                   "created_on" : "2016-12-20T16:24:58+00:00",
  144.                   "product_name" : "Blouse - june bug",
  145.                   "price" : 28.99,
  146.                   "taxful_price" : 28.99,
  147.                   "base_unit_price" : 28.99
  148.                 }
  149.               ],
  150.               "sku" : [
  151.                 "ZO0036600366",
  152.                 "ZO0234902349"
  153.               ],
  154.               "taxful_total_price" : 61.98,
  155.               "taxless_total_price" : 61.98,
  156.               "total_quantity" : 2,
  157.               "total_unique_products" : 2,
  158.               "type" : "order",
  159.               "user" : "gwen",
  160.               "geoip" : {
  161.                 "country_iso_code" : "US",
  162.                 "location" : {
  163.                   "lon" : -118.2,
  164.                   "lat" : 34.1
  165.                 },
  166.                 "region_name" : "California",
  167.                 "continent_name" : "North America",
  168.                 "city_name" : "Los Angeles"
  169.               },
  170.               "event" : {
  171.                 "dataset" : "sample_ecommerce"
  172.               }
  173.             }
  174.           },
  175.          ...
  176.         ]
  177.       },
  178.       "status" : 200
  179.     }
  180.   ]
  181. }