Multi-terms aggregations

Similar to the terms bucket aggregation, you can also search for multiple terms using the multi_terms aggregation. Multi-terms aggregations are useful when you need to sort by document count, or when you need to sort by a metric aggregation on a composite key and get the top n results. For example, you could search for a specific number of documents (e.g., 1000) and the number of servers per location that show CPU usage greater than 90%. The top number of results would be returned for this multi-term query.

The multi_terms aggregation does consume more memory than a terms aggregation, so its performance might be slower.

Multi-terms aggregation parameters

ParameterDescription
multi_termsIndicates a multi-terms aggregation that gathers buckets of documents together based on criteria specified by multiple terms.
sizeSpecifies the number of buckets to return. Default is 10.
orderIndicates the order to sort the buckets. By default, buckets are ordered according to document count per bucket. If the buckets contain the same document count, then order can be explicitly set to the term value instead of document count. (e.g., set order to “max-cpu”).
doc_countSpecifies the number of documents to be returned in each bucket. By default, the top 10 terms are returned.

Example request

  1. GET sample-index100/_search
  2. {
  3.   "size": 0, 
  4.   "aggs": {
  5.     "hot": {
  6.       "multi_terms": {
  7.         "terms": [{
  8.           "field": "region" 
  9.         },{
  10.           "field": "host" 
  11.         }],
  12.         "order": [{
  13.           "max-cpu": "desc"
  14.         },{
  15.           "max-memory": "desc"
  16.         }]
  17.       },
  18.       "aggs": {
  19.         "max-cpu": { "max": { "field": "cpu" } },
  20.         "max-memory": { "max": { "field": "memory" } }
  21.       }      
  22.     }
  23.   }
  24. }

copy

Example response

  1. {
  2.   "took": 118,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 8,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": null,
  16.     "hits": []
  17.   },
  18.   "aggregations": {
  19.     "multi-terms": {
  20.       "doc_count_error_upper_bound": 0,
  21.       "sum_other_doc_count": 0,
  22.       "buckets": [
  23.         {
  24.           "key": [
  25.             "dub",
  26.             "h1"
  27.           ],
  28.           "key_as_string": "dub|h1",
  29.           "doc_count": 2,
  30.           "max-cpu": {
  31.             "value": 90.0
  32.           },
  33.           "max-memory": {
  34.             "value": 50.0
  35.           }
  36.         },
  37.         {
  38.           "key": [
  39.             "dub1",
  40.             "h1"
  41.           ],
  42.           "key_as_string": "dub|h1",
  43.           "doc_count": 2,
  44.           "max-cpu": {
  45.             "value": 90.0
  46.           },
  47.           "max-memory": {
  48.             "value": 40.0
  49.           }
  50.         },
  51.         {
  52.           "key": [
  53.             "dub",
  54.             "h2"
  55.           ],
  56.           "key_as_string": "dub|h2",
  57.           "doc_count": 2,
  58.           "max-cpu": {
  59.             "value": 70.0
  60.           },
  61.           "max-memory": {
  62.             "value": 90.0
  63.           }
  64.         },
  65.         {
  66.           "key": [
  67.             "iad",
  68.             "h2"
  69.           ],
  70.           "key_as_string": "iad|h2",
  71.           "doc_count": 2,
  72.           "max-cpu": {
  73.             "value": 50.0
  74.           },
  75.           "max-memory": {
  76.             "value": 50.0
  77.           }
  78.         },
  79.         {
  80.           "key": [
  81.             "iad",
  82.             "h1"
  83.           ],
  84.           "key_as_string": "iad|h1",
  85.           "doc_count": 2,
  86.           "max-cpu": {
  87.             "value": 15.0
  88.           },
  89.           "max-memory": {
  90.             "value": 20.0
  91.           }
  92.         }
  93.       ]
  94.     }
  95.   }
  96. }