Aggregation

aggregations map string to Aggregation

Sub-aggregations for this aggregation. Only applies to bucket aggregations.

meta object

adjacency_matrix object

A bucket aggregation returning a form of adjacency matrix. The request provides a collection of named filter expressions, similar to the filters aggregation. Each bucket in the response represents a non-empty cell in the matrix of intersecting filters.

auto_date_histogram object

A multi-bucket aggregation similar to the date histogram, except instead of providing an interval to use as the width of each bucket, a target number of buckets is provided.

avg object

A single-value metrics aggregation that computes the average of numeric values that are extracted from the aggregated documents.

avg_bucket object

A sibling pipeline aggregation which calculates the mean value of a specified metric in a sibling aggregation. The specified metric must be numeric and the sibling aggregation must be a multi-bucket aggregation.

boxplot object

A metrics aggregation that computes a box plot of numeric values extracted from the aggregated documents.

bucket_script object

A parent pipeline aggregation which runs a script which can perform per bucket computations on metrics in the parent multi-bucket aggregation.

bucket_selector object

A parent pipeline aggregation which runs a script to determine whether the current bucket will be retained in the parent multi-bucket aggregation.

bucket_sort object

A parent pipeline aggregation which sorts the buckets of its parent multi-bucket aggregation.

from number

Buckets in positions prior to from will be truncated.

gap_policy enum · default: skip

The policy to apply when gaps are found in the data.

Supported values include:

skip: Treats missing data as if the bucket does not exist. It will skip the bucket and continue calculating using the next available value.
insert_zeros: Replace missing values with a zero (0) and pipeline aggregation computation will proceed as normal.
keep_values: Similar to skip, except if the metric provides a non-null, non-NaN value this value is used, otherwise the empty bucket is skipped.

Values: skip insert_zeros keep_values

size number

The number of buckets to return. Defaults to all buckets of the parent aggregation.

sort union oneOf

The list of fields to sort on.

A value or an array; each item is one of:

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

bucket_count_ks_test object

A sibling pipeline aggregation which runs a two sample Kolmogorov–Smirnov test ("K-S test") against a provided distribution and the distribution implied by the documents counts in the configured sibling aggregation.

bucket_correlation object

A sibling pipeline aggregation which runs a correlation function on the configured sibling multi-bucket aggregation.

cardinality object

A single-value metrics aggregation that calculates an approximate count of distinct values.

cartesian_bounds object

A metric aggregation that computes the spatial bounding box containing all values for a Point or Shape field.

cartesian_centroid object

A metric aggregation that computes the weighted centroid from all coordinate values for point and shape fields.

categorize_text object

A multi-bucket aggregation that groups semi-structured text into buckets.

field string required: The semi-structured text field to categorize.
max_unique_tokens number · default: 50: The maximum number of unique tokens at any position up to max_matched_tokens. Must be larger than 1. Smaller values use less memory and create fewer categories. Larger values will use more memory and create narrower categories. Max allowed value is 100.
max_matched_tokens number · default: 5: The maximum number of token positions to match on before attempting to merge categories. Larger values will use more memory and create narrower categories. Max allowed value is 100.
similarity_threshold number · default: 50: The minimum percentage of tokens that must match for text to be added to the category bucket. Must be between 1 and 100. The larger the value the narrower the categories. Larger values will increase memory usage and create narrower categories.
categorization_filters string[]: This property expects an array of regular expressions. The expressions are used to filter out matching sequences from the categorization field values. You can use this functionality to fine tune the categorization by excluding sequences from consideration when categories are defined. For example, you can exclude SQL statements that appear in your log files. This property cannot be used at the same time as categorization_analyzer. If you only want to define simple regular expression filters that are applied prior to tokenization, setting this property is the easiest method. If you also want to customize the tokenizer or post-tokenization filtering, use the categorization_analyzer property instead and include the filters as pattern_replace character filters.
categorization_analyzer union oneOf: The categorization analyzer specifies how the text is analyzed and tokenized before being categorized. The syntax is very similar to that used to define the analyzer in the _analyze endpoint. This property cannot be used at the same time as categorization_filters.; One of:
shard_size number: The number of categorization buckets to return from each shard before merging all the results.
size number · default: 10: The number of buckets to return.
min_doc_count number: The minimum number of documents in a bucket to be returned to the results.
shard_min_doc_count number: The minimum number of documents in a bucket to be returned from the shard before merging.

change_point object

A sibling pipeline that detects, spikes, dips, and change points in a metric. Given a distribution of values provided by the sibling multi-bucket aggregation, this aggregation indicates the bucket of any spike or dip and/or the bucket at which the largest change in the distribution of values, if they are statistically significant. There must be at least 22 bucketed values. Fewer than 1,000 is preferred.

children object

A single bucket aggregation that selects child documents that have the specified type, as defined in a join field.

composite object

A multi-bucket aggregation that creates composite buckets from different sources. Unlike the other multi-bucket aggregations, you can use the composite aggregation to paginate all buckets from a multi-level aggregation efficiently.

cumulative_cardinality object

A parent pipeline aggregation which calculates the cumulative cardinality in a parent histogram or date_histogram aggregation.

cumulative_sum object

A parent pipeline aggregation which calculates the cumulative sum of a specified metric in a parent histogram or date_histogram aggregation.

date_histogram object

A multi-bucket values source based aggregation that can be applied on date values or date range values extracted from the documents. It dynamically builds fixed size (interval) buckets over the values.

calendar_interval enum: Calendar-aware interval. Can be specified using the unit name, such as month, or as a single unit quantity, such as 1M.; Values: second 1s minute 1m hour 1h day 1d week 1w month 1M quarter 1q year 1y
extended_bounds object: Enables extending the bounds of the histogram beyond the data itself.
hard_bounds object: Limits the histogram to specified bounds.
field string: The date field whose values are use to build a histogram.
fixed_interval union oneOf: Fixed intervals: a fixed number of SI units and never deviate, regardless of where they fall on the calendar.; Values: -1 0
format string: The date format used to format key_as_string in the response. If no format is specified, the first date format specified in the field mapping is used.
interval union oneOf: Values: -1 0
min_doc_count number: Only returns buckets that have min_doc_count number of documents. By default, all buckets between the first bucket that matches documents and the last one are returned.
missing union oneOf: The value to apply to documents that do not have a value. By default, documents without a value are ignored.; One of: string or number
offset union oneOf: Changes the start value of each bucket by the specified positive (+) or negative offset (-) duration.; Values: -1 0
order union oneOf: The sort order of the returned buckets.; One of: string to enum[] or string to enum
params map string to object
script string
time_zone string: Time zone used for bucketing and rounding. Defaults to Coordinated Universal Time (UTC).
keyed boolean: Set to true to associate a unique string key with each bucket and return the ranges as a hash rather than an array.

date_range object

A multi-bucket value source based aggregation that enables the user to define a set of date ranges - each representing a bucket.

derivative object

A parent pipeline aggregation which calculates the derivative of a specified metric in a parent histogram or date_histogram aggregation.

diversified_sampler object

A filtering aggregation used to limit any sub aggregations' processing to a sample of the top-scoring documents. Similar to the sampler aggregation, but adds the ability to limit the number of matches that share a common value.

extended_stats object

A multi-value metrics aggregation that computes stats over numeric values extracted from the aggregated documents.

extended_stats_bucket object

A sibling pipeline aggregation which calculates a variety of stats across all bucket of a specified metric in a sibling aggregation.

frequent_item_sets object

A bucket aggregation which finds frequent item sets, a form of association rules mining that identifies items that often occur together.

filter {} Query

A single bucket aggregation that narrows the set of documents to those that match a query.

filters object

A multi-bucket aggregation where each bucket contains the documents that match a query.

geo_bounds object

A metric aggregation that computes the geographic bounding box containing all values for a Geopoint or Geoshape field.

geo_centroid object

A metric aggregation that computes the weighted centroid from all coordinate values for geo fields.

geo_distance object

A multi-bucket aggregation that works on geo_point fields. Evaluates the distance of each document value from an origin point and determines the buckets it belongs to, based on ranges defined in the request.

geohash_grid object

A multi-bucket aggregation that groups geo_point and geo_shape values into buckets that represent a grid. Each cell is labeled using a geohash which is of user-definable precision.

bounds union oneOf: The bounding box to filter the points in each bucket.; One of:
field string: Field containing indexed geo_point or geo_shape values. If the field contains an array, geohash_grid aggregates all array values.
precision number | string · default: 5: The string length of the geohashes used to define cells/buckets in the results.
shard_size number: Allows for more accurate counting of the top cells returned in the final result the aggregation. Defaults to returning max(10,(size x number-of-shards)) buckets from each shard.
size number · default: 10000: The maximum number of geohash buckets to return.

geo_line object

Aggregates all geo_point values within a bucket into a LineString ordered by the chosen sort field.

geotile_grid object

A multi-bucket aggregation that groups geo_point and geo_shape values into buckets that represent a grid. Each cell corresponds to a map tile as used by many online map sites.

geohex_grid object

A multi-bucket aggregation that groups geo_point and geo_shape values into buckets that represent a grid. Each cell corresponds to a H3 cell index and is labeled using the H3Index representation.

global object

Defines a single bucket of all the documents within the search execution context. This context is defined by the indices and the document types you’re searching on, but is not influenced by the search query itself.

histogram object

A multi-bucket values source based aggregation that can be applied on numeric values or numeric range values extracted from the documents. It dynamically builds fixed size (interval) buckets over the values.

ip_range object

A multi-bucket value source based aggregation that enables the user to define a set of IP ranges - each representing a bucket.

ip_prefix object

A bucket aggregation that groups documents based on the network or sub-network of an IP address.

inference object

A parent pipeline aggregation which loads a pre-trained model and performs inference on the collated result fields from the parent bucket aggregation.

buckets_path union oneOf

Path to the buckets that contain one set of values to correlate.

One of: string[] or string or string to string

format string

DecimalFormat pattern for the output value. If specified, the formatted value is returned in the aggregation’s value_as_string property.

gap_policy enum · default: skip

Policy to apply when gaps are found in the data.

Supported values include:

skip: Treats missing data as if the bucket does not exist. It will skip the bucket and continue calculating using the next available value.
insert_zeros: Replace missing values with a zero (0) and pipeline aggregation computation will proceed as normal.
keep_values: Similar to skip, except if the metric provides a non-null, non-NaN value this value is used, otherwise the empty bucket is skipped.

Values: skip insert_zeros keep_values

model_id string required

The ID or alias for the trained model.

inference_config object

Contains the inference type and its options.

line object

matrix_stats object

A numeric aggregation that computes the following statistics over a set of document fields: count, mean, variance, skewness, kurtosis, covariance, and covariance.

max object

A single-value metrics aggregation that returns the maximum value among the numeric values extracted from the aggregated documents.

max_bucket object

A sibling pipeline aggregation which identifies the bucket(s) with the maximum value of a specified metric in a sibling aggregation and outputs both the value and the key(s) of the bucket(s).

median_absolute_deviation object

A single-value aggregation that approximates the median absolute deviation of its search results.

min object

A single-value metrics aggregation that returns the minimum value among numeric values extracted from the aggregated documents.

min_bucket object

A sibling pipeline aggregation which identifies the bucket(s) with the minimum value of a specified metric in a sibling aggregation and outputs both the value and the key(s) of the bucket(s).

missing object

A field data based single bucket aggregation, that creates a bucket of all documents in the current document set context that are missing a field value (effectively, missing a field or having the configured NULL value set).

moving_avg union oneOf

One of: (determined by model)

model: linear

model enum required

Values: linear

buckets_path union oneOf

Path to the buckets that contain one set of values to correlate.

One of: string[] or string or string to string

format string

DecimalFormat pattern for the output value. If specified, the formatted value is returned in the aggregation’s value_as_string property.

gap_policy enum · default: skip

Policy to apply when gaps are found in the data.

Supported values include:

skip: Treats missing data as if the bucket does not exist. It will skip the bucket and continue calculating using the next available value.
insert_zeros: Replace missing values with a zero (0) and pipeline aggregation computation will proceed as normal.
keep_values: Similar to skip, except if the metric provides a non-null, non-NaN value this value is used, otherwise the empty bucket is skipped.

Values: skip insert_zeros keep_values

minimize boolean

predict number

window number

settings object required

moving_percentiles object

Given an ordered series of percentiles, "slides" a window across those percentiles and computes cumulative percentiles.

moving_fn object

Given an ordered series of data, "slides" a window across the data and runs a custom script on each window of data. For convenience, a number of common functions are predefined such as min, max, and moving averages.

multi_terms object

A multi-bucket value source based aggregation where buckets are dynamically built - one per unique set of values.

collect_mode enum · default: breadth_first

Specifies the strategy for data collection.

Supported values include:

depth_first: Expands all branches of the aggregation tree in one depth-first pass, before any pruning occurs.
breadth_first: Caches the set of documents that fall into the uppermost buckets for subsequent replay.

Values: depth_first breadth_first

order union oneOf

Specifies the sort order of the buckets. Defaults to sorting by descending document count.

One of: string to enum[] or string to enum

min_doc_count number · default: 1

The minimum number of documents in a bucket for it to be returned.

shard_min_doc_count number · default: 1

The minimum number of documents in a bucket on each shard for it to be returned.

shard_size number

The number of candidate terms produced by each shard. By default, shard_size will be automatically estimated based on the number of shards and the size parameter.

show_term_doc_count_error boolean · default: false

Calculates the doc count error on per term basis.

size number · default: 10

The number of term buckets should be returned out of the overall terms list.

terms object[] required

The field from which to generate sets of terms.

nested object

A special single bucket aggregation that enables aggregating nested documents.

normalize object

A parent pipeline aggregation which calculates the specific normalized/rescaled value for a specific bucket value.

parent object

A special single bucket aggregation that selects parent documents that have the specified type, as defined in a join field.

percentile_ranks object

A multi-value metrics aggregation that calculates one or more percentile ranks over numeric values extracted from the aggregated documents.

percentiles object

A multi-value metrics aggregation that calculates one or more percentiles over numeric values extracted from the aggregated documents.

percentiles_bucket object

A sibling pipeline aggregation which calculates percentiles across all bucket of a specified metric in a sibling aggregation.

range object

A multi-bucket value source based aggregation that enables the user to define a set of ranges - each representing a bucket.

rare_terms object

A multi-bucket value source based aggregation which finds "rare" terms — terms that are at the long-tail of the distribution and are not frequent.

rate object

Calculates a rate of documents or a field in each bucket. Can only be used inside a date_histogram or composite aggregation.

reverse_nested object

A special single bucket aggregation that enables aggregating on parent documents from nested documents. Should only be defined inside a nested aggregation.

random_sampler object

A single bucket aggregation that randomly includes documents in the aggregated results. Sampling provides significant speed improvement at the cost of accuracy.

sampler object

A filtering aggregation used to limit any sub aggregations' processing to a sample of the top-scoring documents.

scripted_metric object

A metric aggregation that uses scripts to provide a metric output.

serial_diff object

An aggregation that subtracts values in a time series from themselves at different time lags or periods.

significant_terms object

Returns interesting or unusual occurrences of terms in a set.

background_filter {} Query

A background filter that can be used to focus in on significant terms within a narrower context, instead of the entire index.

chi_square object

Use Chi square, as described in "Information Retrieval", Manning et al., Chapter 13.5.2, as the significance score.

exclude union oneOf

Terms to exclude.

One of: string[] or string

execution_hint enum

Mechanism by which the aggregation should be executed: using field values directly or using global ordinals.

Values: map global_ordinals global_ordinals_hash global_ordinals_low_cardinality

field string

The field from which to return significant terms.

gnd object

Use Google normalized distance as described in "The Google Similarity Distance", Cilibrasi and Vitanyi, 2007, as the significance score.

include union oneOf

Terms to include.

One of:

string[]

jlh object

Use JLH score as the significance score.

min_doc_count number · default: 3

Only return terms that are found in more than min_doc_count hits.

mutual_information object

Use mutual information as described in "Information Retrieval", Manning et al., Chapter 13.5.1, as the significance score.

percentage object

A simple calculation of the number of documents in the foreground sample with a term divided by the number of documents in the background with the term.

script_heuristic object

Customized score, implemented via a script.

p_value object

Significant terms heuristic that calculates the p-value between the term existing in foreground and background sets.

The p-value is the probability of obtaining test results at least as extreme as the results actually observed, under the assumption that the null hypothesis is correct. The p-value is calculated assuming that the foreground set and the background set are independent https://en.wikipedia.org/wiki/Bernoulli_trial, with the null hypothesis that the probabilities are the same.

shard_min_doc_count number

Regulates the certainty a shard has if the term should actually be added to the candidate list or not with respect to the min_doc_count. Terms will only be considered if their local shard frequency within the set is higher than the shard_min_doc_count.

shard_size number

Can be used to control the volumes of candidate terms produced by each shard. By default, shard_size will be automatically estimated based on the number of shards and the size parameter.

size number

The number of buckets returned out of the overall terms list.

significant_text object

Returns interesting or unusual occurrences of free-text terms in a set.

background_filter {} Query: A background filter that can be used to focus in on significant terms within a narrower context, instead of the entire index.
chi_square object: Use Chi square, as described in "Information Retrieval", Manning et al., Chapter 13.5.2, as the significance score.
exclude union oneOf: Values to exclude.; One of: string[] or string
execution_hint enum: Determines whether the aggregation will use field values directly or global ordinals.; Values: map global_ordinals global_ordinals_hash global_ordinals_low_cardinality
field string: The field from which to return significant text.
filter_duplicate_text boolean: Whether to out duplicate text to deal with noisy data.
gnd object: Use Google normalized distance as described in "The Google Similarity Distance", Cilibrasi and Vitanyi, 2007, as the significance score.
include union oneOf: Values to include.; One of:
jlh object: Use JLH score as the significance score.
min_doc_count number · default: 3: Only return values that are found in more than min_doc_count hits.
mutual_information object: Use mutual information as described in "Information Retrieval", Manning et al., Chapter 13.5.1, as the significance score.
percentage object: A simple calculation of the number of documents in the foreground sample with a term divided by the number of documents in the background with the term.
script_heuristic object: Customized score, implemented via a script.
shard_min_doc_count number: Regulates the certainty a shard has if the values should actually be added to the candidate list or not with respect to the min_doc_count. Values will only be considered if their local shard frequency within the set is higher than the shard_min_doc_count.
shard_size number: The number of candidate terms produced by each shard. By default, shard_size will be automatically estimated based on the number of shards and the size parameter.
size number: The number of buckets returned out of the overall terms list.
source_fields union oneOf: Overrides the JSON _source fields from which text will be analyzed.; One of: string[] or string

stats object

A multi-value metrics aggregation that computes stats over numeric values extracted from the aggregated documents.

stats_bucket object

A sibling pipeline aggregation which calculates a variety of stats across all bucket of a specified metric in a sibling aggregation.

string_stats object

A multi-value metrics aggregation that computes statistics over string values extracted from the aggregated documents.

sum object

A single-value metrics aggregation that sums numeric values that are extracted from the aggregated documents.

sum_bucket object

A sibling pipeline aggregation which calculates the sum of a specified metric across all buckets in a sibling aggregation.

terms object

A multi-bucket value source based aggregation where buckets are dynamically built - one per unique value.

collect_mode enum

Determines how child aggregations should be calculated: breadth-first or depth-first.

Supported values include:

depth_first: Expands all branches of the aggregation tree in one depth-first pass, before any pruning occurs.
breadth_first: Caches the set of documents that fall into the uppermost buckets for subsequent replay.

Values: depth_first breadth_first

exclude union oneOf

Values to exclude. Accepts regular expressions and partitions.

One of: string[] or string

execution_hint enum

Determines whether the aggregation will use field values directly or global ordinals.

Values: map global_ordinals global_ordinals_hash global_ordinals_low_cardinality

field string

The field from which to return terms.

include union oneOf

Values to include. Accepts regular expressions and partitions.

One of:

string[]

min_doc_count number · default: 1

Only return values that are found in more than min_doc_count hits.

missing boolean | number | string

The value to apply to documents that do not have a value. By default, documents without a value are ignored.

missing_order enum

Values: first last default

missing_bucket boolean

value_type string

Coerced unmapped fields into the specified type.

order union oneOf

Specifies the sort order of the buckets. Defaults to sorting by descending document count.

One of: string to enum[] or string to enum

script string

shard_min_doc_count number

Regulates the certainty a shard has if the term should actually be added to the candidate list or not with respect to the min_doc_count. Terms will only be considered if their local shard frequency within the set is higher than the shard_min_doc_count.

shard_size number

The number of candidate terms produced by each shard. By default, shard_size will be automatically estimated based on the number of shards and the size parameter.

show_term_doc_count_error boolean

Set to true to return the doc_count_error_upper_bound, which is an upper bound to the error on the doc_count returned by each shard.

size number · default: 10

The number of buckets returned out of the overall terms list.

format string

time_series object

The time series aggregation queries data created using a time series index. This is typically data such as metrics or other data streams with a time component, and requires creating an index using the time series mode.

top_hits object

A metric aggregation that returns the top matching documents per bucket.

field string: The field on which to run the aggregation.
missing boolean | number | string: The value to apply to documents that do not have a value. By default, documents without a value are ignored.
script string
docvalue_fields object[]: Fields for which to return doc values.
explain boolean · default: false: If true, returns detailed information about score computation as part of a hit.
fields object[]: Array of wildcard (*) patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
from number · default: 0: Starting document offset.
highlight object: Specifies the highlighter to use for retrieving highlighted snippets from one or more fields in the search results.
script_fields map string to object: Returns the result of one or more script evaluations for each hit.
size number · default: 3: The maximum number of top matching hits to return per bucket.
sort union oneOf: Sort order of the top matching hits. By default, the hits are sorted by the score of the main query.; Same options as sort in bucket_sort
_source union oneOf: Selects the fields of the source that are returned.; One of:
stored_fields union oneOf: Returns values for the specified stored fields (fields that use the store mapping option).; One of: string[] or string
track_scores boolean · default: false: If true, calculates and returns document scores, even if the scores are not used for sorting.
version boolean · default: false: If true, returns document version as part of a hit.
seq_no_primary_term boolean: If true, returns sequence number and primary term of the last modification of each hit.

t_test object

A metrics aggregation that performs a statistical hypothesis test in which the test statistic follows a Student’s t-distribution under the null hypothesis on numeric values extracted from the aggregated documents.

top_metrics object

A metric aggregation that selects metrics from the document with the largest or smallest sort value.

value_count object

A single-value metrics aggregation that counts the number of values that are extracted from the aggregated documents.

weighted_avg object

A single-value metrics aggregation that computes the weighted average of numeric values that are extracted from the aggregated documents.

variable_width_histogram object

A multi-bucket aggregation similar to the histogram, except instead of providing an interval to use as the width of each bucket, a target number of buckets is provided.

Properties