This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Sampler aggregations

If you’re aggregating over millions of documents, you can use a sampler aggregation to reduce its scope to a small sample of documents for a faster response. The sampler aggregation selects the samples by top-scoring documents.

The results are approximate but closely represent the distribution of the real data. The sampler aggregation significantly improves query performance, but the estimated responses are not entirely reliable.

The basic syntax is:

  1. “aggs”: {
  2.   "SAMPLE": {
  3.     "sampler": {
  4.       "shard_size": 100
  5.     },
  6.     "aggs": {...}
  7.   }
  8. }

The shard_size property tells OpenSearch how many documents (at most) to collect from each shard.

The following example limits the number of documents collected on each shard to 1,000 and then buckets the documents by a terms aggregation:

  1. GET opensearch_dashboards_sample_data_logs/_search
  2. {
  3.   "size": 0,
  4.   "aggs": {
  5.     "sample": {
  6.       "sampler": {
  7.         "shard_size": 1000
  8.       },
  9.       "aggs": {
  10.         "terms": {
  11.           "terms": {
  12.             "field": "agent.keyword"
  13.           }
  14.         }
  15.       }
  16.     }
  17.   }
  18. }

copy

Example response

  1. ...
  2. "aggregations" : {
  3.   "sample" : {
  4.     "doc_count" : 1000,
  5.     "terms" : {
  6.       "doc_count_error_upper_bound" : 0,
  7.       "sum_other_doc_count" : 0,
  8.       "buckets" : [
  9.         {
  10.           "key" : "Mozilla/5.0 (X11; Linux x86_64; rv:6.0a1) Gecko/20110421 Firefox/6.0a1",
  11.           "doc_count" : 368
  12.         },
  13.         {
  14.           "key" : "Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24",
  15.           "doc_count" : 329
  16.         },
  17.         {
  18.           "key" : "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)",
  19.           "doc_count" : 303
  20.         }
  21.       ]
  22.     }
  23.   }
  24.  }
  25. }