Bucket Script Aggregation

A parent pipeline aggregation which executes a script which can perform per bucket computations on specified metrics in the parent multi-bucket aggregation. The specified metric must be numeric and the script must return a numeric value.

Syntax

A bucket_script aggregation looks like this in isolation:

  1. {
  2.   "bucket_script": {
  3.     "buckets_path": {
  4.       "my_var1": "the_sum",                     
  5.       "my_var2": "the_value_count"
  6.     },
  7.     "script": "params.my_var1 / params.my_var2"
  8.   }
  9. }

Here, my_var1 is the name of the variable for this buckets path to use in the script, the_sum is the path to the metrics to use for that variable.

Table 44. bucket_script Parameters

Parameter NameDescriptionRequiredDefault Value

script

The script to run for this aggregation. The script can be inline, file or indexed. (see Scripting for more details)

Required

buckets_path

A map of script variables and their associated path to the buckets we wish to use for the variable (see buckets_path Syntax for more details)

Required

gap_policy

The policy to apply when gaps are found in the data (see Dealing with gaps in the data for more details)

Optional

skip

format

format to apply to the output value of this aggregation

Optional

null

The following snippet calculates the ratio percentage of t-shirt sales compared to total sales each month:

  1. POST /sales/_search
  2. {
  3.   "size": 0,
  4.   "aggs": {
  5.     "sales_per_month": {
  6.       "date_histogram": {
  7.         "field": "date",
  8.         "calendar_interval": "month"
  9.       },
  10.       "aggs": {
  11.         "total_sales": {
  12.           "sum": {
  13.             "field": "price"
  14.           }
  15.         },
  16.         "t-shirts": {
  17.           "filter": {
  18.             "term": {
  19.               "type": "t-shirt"
  20.             }
  21.           },
  22.           "aggs": {
  23.             "sales": {
  24.               "sum": {
  25.                 "field": "price"
  26.               }
  27.             }
  28.           }
  29.         },
  30.         "t-shirt-percentage": {
  31.           "bucket_script": {
  32.             "buckets_path": {
  33.               "tShirtSales": "t-shirts>sales",
  34.               "totalSales": "total_sales"
  35.             },
  36.             "script": "params.tShirtSales / params.totalSales * 100"
  37.           }
  38.         }
  39.       }
  40.     }
  41.   }
  42. }

And the following may be the response:

  1. {
  2.    "took": 11,
  3.    "timed_out": false,
  4.    "_shards": ...,
  5.    "hits": ...,
  6.    "aggregations": {
  7.       "sales_per_month": {
  8.          "buckets": [
  9.             {
  10.                "key_as_string": "2015/01/01 00:00:00",
  11.                "key": 1420070400000,
  12.                "doc_count": 3,
  13.                "total_sales": {
  14.                    "value": 550.0
  15.                },
  16.                "t-shirts": {
  17.                    "doc_count": 1,
  18.                    "sales": {
  19.                        "value": 200.0
  20.                    }
  21.                },
  22.                "t-shirt-percentage": {
  23.                    "value": 36.36363636363637
  24.                }
  25.             },
  26.             {
  27.                "key_as_string": "2015/02/01 00:00:00",
  28.                "key": 1422748800000,
  29.                "doc_count": 2,
  30.                "total_sales": {
  31.                    "value": 60.0
  32.                },
  33.                "t-shirts": {
  34.                    "doc_count": 1,
  35.                    "sales": {
  36.                        "value": 10.0
  37.                    }
  38.                },
  39.                "t-shirt-percentage": {
  40.                    "value": 16.666666666666664
  41.                }
  42.             },
  43.             {
  44.                "key_as_string": "2015/03/01 00:00:00",
  45.                "key": 1425168000000,
  46.                "doc_count": 2,
  47.                "total_sales": {
  48.                    "value": 375.0
  49.                },
  50.                "t-shirts": {
  51.                    "doc_count": 1,
  52.                    "sales": {
  53.                        "value": 175.0
  54.                    }
  55.                },
  56.                "t-shirt-percentage": {
  57.                    "value": 46.666666666666664
  58.                }
  59.             }
  60.          ]
  61.       }
  62.    }
  63. }