Skip to content

updates #124135

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

updates #124135

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions ...nalysis/aggregations/search-aggregations-bucket-adjacency-matrix-aggregation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
---
navigation_title: "Adjacency matrix"
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-adjacency-matrix-aggregation.html
---

# Adjacency matrix aggregation [search-aggregations-bucket-adjacency-matrix-aggregation]
Expand Down Expand Up @@ -88,6 +86,12 @@ The response contains buckets with document counts for each filter and combinati
}
```

% TESTRESPONSE[s/"took": 9/"took": $body.took/]

% TESTRESPONSE[s/"_shards": \.\.\./"_shards": $body._shards/]

% TESTRESPONSE[s/"hits": \.\.\./"hits": $body.hits/]


## Parameters [adjacency-matrix-agg-params]

Expand All @@ -96,9 +100,9 @@ The response contains buckets with document counts for each filter and combinati

::::{dropdown} Properties of `filters`
`<filter>`
: (Required, [Query DSL object](/reference/query-languages/querydsl.md)) Query used to filter documents. The key is the filter name.
: (Required, [Query DSL object](query-dsl.md)) Query used to filter documents. The key is the filter name.

At least one filter is required. The total number of filters cannot exceed the [`indices.query.bool.max_clause_count`](/reference/elasticsearch/configuration-reference/search-settings.md#indices-query-bool-max-clause-count) setting. See [Filter limits](#adjacency-matrix-agg-filter-limits).
At least one filter is required. The total number of filters cannot exceed the [`indices.query.bool.max_clause_count`](search-settings.md#indices-query-bool-max-clause-count) setting. See [Filter limits](search-aggregations-bucket-adjacency-matrix-aggregation.md#adjacency-matrix-agg-filter-limits).


::::
Expand Down
28 changes: 21 additions & 7 deletions ...alysis/aggregations/search-aggregations-bucket-autodatehistogram-aggregation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
---
navigation_title: "Auto-interval date histogram"
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-autodatehistogram-aggregation.html
---

# Auto-interval date histogram aggregation [search-aggregations-bucket-autodatehistogram-aggregation]


A multi-bucket aggregation similar to the [Date histogram](/reference/data-analysis/aggregations/search-aggregations-bucket-datehistogram-aggregation.md) except instead of providing an interval to use as the width of each bucket, a target number of buckets is provided indicating the number of buckets needed and the interval of the buckets is automatically chosen to best achieve that target. The number of buckets returned will always be less than or equal to this target number.
A multi-bucket aggregation similar to the [Date histogram](search-aggregations-bucket-datehistogram-aggregation.md) except instead of providing an interval to use as the width of each bucket, a target number of buckets is provided indicating the number of buckets needed and the interval of the buckets is automatically chosen to best achieve that target. The number of buckets returned will always be less than or equal to this target number.

The buckets field is optional, and will default to 10 buckets if not specified.

Expand All @@ -29,12 +27,14 @@ POST /sales/_search?size=0
}
```

% TEST[setup:sales]

## Keys [_keys]

Internally, a date is represented as a 64 bit number representing a timestamp in milliseconds-since-the-epoch. These timestamps are returned as the bucket `key`s. The `key_as_string` is the same timestamp converted to a formatted date string using the format specified with the `format` parameter:

::::{tip}
If no `format` is specified, then it will use the first date [format](/reference/elasticsearch/mapping-reference/mapping-date-format.md) specified in the field mapping.
::::{tip}
If no `format` is specified, then it will use the first date [format](mapping-date-format.md) specified in the field mapping.
::::


Expand All @@ -55,7 +55,9 @@ POST /sales/_search?size=0
}
```

1. Supports expressive date [format pattern](/reference/data-analysis/aggregations/search-aggregations-bucket-daterange-aggregation.md#date-format-pattern)
% TEST[setup:sales]

1. Supports expressive date [format pattern](search-aggregations-bucket-daterange-aggregation.md#date-format-pattern)


Response:
Expand Down Expand Up @@ -88,6 +90,8 @@ Response:
}
```

% TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]


## Intervals [_intervals]

Expand Down Expand Up @@ -183,6 +187,8 @@ UTC is used if no time zone is specified, three 1-hour buckets are returned star
}
```

% TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]

If a `time_zone` of `-01:00` is specified, then midnight starts at one hour before midnight UTC:

```console
Expand All @@ -200,6 +206,8 @@ GET my-index-000001/_search?size=0
}
```

% TEST[continued]

Now three 1-hour buckets are still returned but the first bucket starts at 11:00pm on 30 September 2015 since that is the local time for the bucket in the specified time zone.

```console-result
Expand Down Expand Up @@ -230,10 +238,12 @@ Now three 1-hour buckets are still returned but the first bucket starts at 11:00
}
```

% TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]

1. The `key_as_string` value represents midnight on each day in the specified time zone.


::::{warning}
::::{warning}
When using time zones that follow DST (daylight savings time) changes, buckets close to the moment when those changes happen can have slightly different sizes than neighbouring buckets. For example, consider a DST start in the `CET` time zone: on 27 March 2016 at 2am, clocks were turned forward 1 hour to 3am local time. If the result of the aggregation was daily buckets, the bucket covering that day will only hold data for 23 hours instead of the usual 24 hours for other buckets. The same is true for shorter intervals like e.g. 12h. Here, we will have only a 11h bucket on the morning of 27 March when the DST shift happens.
::::

Expand Down Expand Up @@ -269,6 +279,8 @@ POST /sales/_search?size=0
}
```

% TEST[setup:sales]


## Missing value [_missing_value]

Expand All @@ -291,6 +303,8 @@ POST /sales/_search?size=0
}
```

% TEST[setup:sales]

1. Documents without a value in the `publish_date` field will fall into the same bucket as documents that have the value `2000-01-01`.


Expand Down
20 changes: 17 additions & 3 deletions ...ce/data-analysis/aggregations/search-aggregations-bucket-iprange-aggregation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
---
navigation_title: "IP range"
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-iprange-aggregation.html
---

# IP range aggregation [search-aggregations-bucket-iprange-aggregation]


Just like the dedicated [date](/reference/data-analysis/aggregations/search-aggregations-bucket-daterange-aggregation.md) range aggregation, there is also a dedicated range aggregation for IP typed fields:
Just like the dedicated [date](search-aggregations-bucket-daterange-aggregation.md) range aggregation, there is also a dedicated range aggregation for IP typed fields:

Example:

Expand All @@ -31,6 +29,8 @@ GET /ip_addresses/_search
}
```

% TEST[setup:iprange]

Response:

```console-result
Expand All @@ -56,6 +56,8 @@ Response:
}
```

% TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]

IP ranges can also be defined as CIDR masks:

$$$ip-range-cidr-example$$$
Expand All @@ -78,6 +80,8 @@ GET /ip_addresses/_search
}
```

% TEST[setup:iprange]

Response:

```console-result
Expand Down Expand Up @@ -105,6 +109,8 @@ Response:
}
```

% TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]

## Keyed Response [_keyed_response_3]

Setting the `keyed` flag to `true` will associate a unique string key with each bucket and return the ranges as a hash rather than an array:
Expand All @@ -130,6 +136,8 @@ GET /ip_addresses/_search
}
```

% TEST[setup:iprange]

Response:

```console-result
Expand All @@ -153,6 +161,8 @@ Response:
}
```

% TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]

It is also possible to customize the key for each range:

$$$ip-range-keyed-customized-keys-example$$$
Expand All @@ -176,6 +186,8 @@ GET /ip_addresses/_search
}
```

% TEST[setup:iprange]

Response:

```console-result
Expand All @@ -199,4 +211,6 @@ Response:
}
```

% TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]


69 changes: 61 additions & 8 deletions ...ata-analysis/aggregations/search-aggregations-bucket-multi-terms-aggregation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,52 @@
---
navigation_title: "Multi Terms"
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-multi-terms-aggregation.html
---

# Multi Terms aggregation [search-aggregations-bucket-multi-terms-aggregation]


A multi-bucket value source based aggregation where buckets are dynamically built - one per unique set of values. The multi terms aggregation is very similar to the [`terms aggregation`](/reference/data-analysis/aggregations/search-aggregations-bucket-terms-aggregation.md#search-aggregations-bucket-terms-aggregation-order), however in most cases it will be slower than the terms aggregation and will consume more memory. Therefore, if the same set of fields is constantly used, it would be more efficient to index a combined key for this fields as a separate field and use the terms aggregation on this field.

The multi_term aggregations are the most useful when you need to sort by a number of document or a metric aggregation on a composite key and get top N results. If sorting is not required and all values are expected to be retrieved using nested terms aggregation or [`composite aggregations`](/reference/data-analysis/aggregations/search-aggregations-bucket-composite-aggregation.md) will be a faster and more memory efficient solution.
A multi-bucket value source based aggregation where buckets are dynamically built - one per unique set of values. The multi terms aggregation is very similar to the [`terms aggregation`](search-aggregations-bucket-terms-aggregation.md#search-aggregations-bucket-terms-aggregation-order), however in most cases it will be slower than the terms aggregation and will consume more memory. Therefore, if the same set of fields is constantly used, it would be more efficient to index a combined key for this fields as a separate field and use the terms aggregation on this field.

The multi_term aggregations are the most useful when you need to sort by a number of document or a metric aggregation on a composite key and get top N results. If sorting is not required and all values are expected to be retrieved using nested terms aggregation or [`composite aggregations`](search-aggregations-bucket-composite-aggregation.md) will be a faster and more memory efficient solution.

%
% [source,js]
% --------------------------------------------------
% PUT /products
% {
% "mappings": {
% "properties": {
% "genre": {
% "type": "keyword"
% },
% "product": {
% "type": "keyword"
% },
% "quantity": {
% "type": "integer"
% }
% }
% }
% }
%
% POST /products/_bulk?refresh
% {"index":{"_id":0}}
% {"genre": "rock", "product": "Product A", "quantity": 4}
% {"index":{"_id":1}}
% {"genre": "rock", "product": "Product A", "quantity": 5}
% {"index":{"_id":2}}
% {"genre": "rock", "product": "Product B", "quantity": 1}
% {"index":{"_id":3}}
% {"genre": "jazz", "product": "Product B", "quantity": 10}
% {"index":{"_id":4}}
% {"genre": "electronic", "product": "Product B", "quantity": 3}
% {"index":{"_id":5}}
% {"genre": "electronic"}
%
% -------------------------------------------------
% // NOTCONSOLE
% // TESTSETUP
%

Example:

Expand All @@ -32,7 +69,9 @@ GET /products/_search
}
```

1. `multi_terms` aggregation can work with the same field types as a [`terms aggregation`](/reference/data-analysis/aggregations/search-aggregations-bucket-terms-aggregation.md#search-aggregations-bucket-terms-aggregation-order) and supports most of the terms aggregation parameters.
% TEST[s/_search/_search\?filter_path=aggregations/]

1. `multi_terms` aggregation can work with the same field types as a [`terms aggregation`](search-aggregations-bucket-terms-aggregation.md#search-aggregations-bucket-terms-aggregation-order) and supports most of the terms aggregation parameters.


Response:
Expand Down Expand Up @@ -83,6 +122,8 @@ Response:
}
```

% TESTRESPONSE[s/\.\.\.//]

1. an upper bound of the error on the document counts for each term, see <<search-aggregations-bucket-multi-terms-aggregation-approximate-counts,below>
2. when there are lots of unique terms, Elasticsearch only returns the top terms; this number is the sum of the document counts for all buckets that are not part of the response
3. the list of the top buckets.
Expand All @@ -93,7 +134,7 @@ By default, the `multi_terms` aggregation will return the buckets for the top te

## Aggregation Parameters [search-aggregations-bucket-multi-terms-aggregation-parameters]

The following parameters are supported. See [`terms aggregation`](/reference/data-analysis/aggregations/search-aggregations-bucket-terms-aggregation.md#search-aggregations-bucket-terms-aggregation-order) for more detailed explanation of these parameters.
The following parameters are supported. See [`terms aggregation`](search-aggregations-bucket-terms-aggregation.md#search-aggregations-bucket-terms-aggregation-order) for more detailed explanation of these parameters.

size
: Optional. Defines how many term buckets should be returned out of the overall terms list. Defaults to 10.
Expand Down Expand Up @@ -149,6 +190,8 @@ GET /products/_search
}
```

% TEST[s/_search/_search\?filter_path=aggregations/]

Response:

```console-result
Expand Down Expand Up @@ -189,6 +232,8 @@ Response:
}
```

% TESTRESPONSE[s/\.\.\.//]


## Missing value [_missing_value_3]

Expand Down Expand Up @@ -217,6 +262,8 @@ GET /products/_search
}
```

% TEST[s/_search/_search\?filter_path=aggregations/]

Response:

```console-result
Expand Down Expand Up @@ -273,13 +320,15 @@ Response:
}
```

% TESTRESPONSE[s/\.\.\.//]

1. Documents without a value in the `product` field will fall into the same bucket as documents that have the value `Product Z`.



## Mixing field types [_mixing_field_types]

::::{warning}
::::{warning}
When aggregating on multiple indices the type of the aggregated field may not be the same in all indices. Some types are compatible with each other (`integer` and `long` or `float` and `double`) but when the types are a mix of decimal and non-decimal number the terms aggregation will promote the non-decimal numbers to decimal numbers. This can result in a loss of precision in the bucket values.
::::

Expand Down Expand Up @@ -321,6 +370,8 @@ GET /products/_search
}
```

% TEST[s/_search/_search\?filter_path=aggregations/]

```console-result
{
...
Expand Down Expand Up @@ -379,4 +430,6 @@ GET /products/_search
}
```

% TESTRESPONSE[s/\.\.\.//]


Loading