Skip to content

Commit

Permalink
Improve top_metrics docs (#53521) (#53619)
Browse files Browse the repository at this point in the history 
* Removes experimental.
* Replaces `"v"` (for value) with `"m"` (for metric).
* Move the note about tiebreaking into the list of limitations of the
  sort.
* Explain how you ask for `metrics`.
* Clean up some wording.
* Link to the docs from `top_metrics`.

Closes #51813
  • Loading branch information
@nik9000
nik9000 authored Mar 16, 2020
1 parent 031932b commit f7482f7
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 48 deletions.
93 changes: 45 additions & 48 deletions docs/reference/aggregations/metrics/top-metrics-aggregation.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,24 @@
[[search-aggregations-metrics-top-metrics]]
=== Top Metrics Aggregation

experimental[We expect to change the response format of this aggregation as we add more features., https://github.com/elastic/elasticsearch/issues/51813]

The `top_metrics` aggregation selects metrics from the document with the largest or smallest "sort"
value. For example, This gets the value of the `v` field on the document with the largest value of `s`:
value. For example, this gets the value of the `m` field on the document with the largest value of `s`:

[source,console,id=search-aggregations-metrics-top-metrics-simple]
----
POST /test/_bulk?refresh
{"index": {}}
{"s": 1, "v": 3.1415}
{"s": 1, "m": 3.1415}
{"index": {}}
{"s": 2, "v": 1.0}
{"s": 2, "m": 1.0}
{"index": {}}
{"s": 3, "v": 2.71828}
{"s": 3, "m": 2.71828}
POST /test/_search?filter_path=aggregations
{
"aggs": {
"tm": {
"top_metrics": {
"metrics": {"field": "v"},
"metrics": {"field": "m"},
"sort": {"s": "desc"}
}
}
Expand All @@ -37,7 +35,7 @@ Which returns:
{
"aggregations": {
"tm": {
"top": [ {"sort": [3], "metrics": {"v": 2.718280076980591 } } ]
"top": [ {"sort": [3], "metrics": {"m": 2.718280076980591 } } ]
}
}
}
Expand All @@ -54,7 +52,7 @@ The `sort` field in the metric request functions exactly the same as the `sort`
<<request-body-search-sort, search>> request except:
* It can't be used on <<binary,binary>>, <<flattened,flattened>, <<ip,ip>>,
<<keyword,keyword>>, or <<text,text>> fields.
* It only supports a single sort value.
* It only supports a single sort value so which document wins ties is not specified.

The metrics that the aggregation returns is the first hit that would be returned by the search
request. So,
Expand All @@ -65,14 +63,12 @@ request. So,
gets metrics from the documents with `location` *closest* to `35.7796, -78.6382`
`"sort": "_score"`:: gets metrics from the document with the highest score

NOTE: This aggregation doesn't support any sort of "tie breaking". If two documents have
the same sort values then this aggregation could return either document's fields.

==== `metrics`

`metrics` selects the fields to of the "top" document to return.

You can return multiple metrics by providing a list:
`metrics` selects the fields to of the "top" document to return. You can return
a request a single metric with something like `"metric": {"field": "m"}` or multiple
metrics by requesting a list of metrics like `"metric": [{"field": "m"}, {"field": "i"}`.
Here is a more complete example:

[source,console,id=search-aggregations-metrics-top-metrics-list-of-metrics]
----
Expand All @@ -86,19 +82,19 @@ PUT /test
}
POST /test/_bulk?refresh
{"index": {}}
{"s": 1, "v": 3.1415, "m": 1, "d": "2020-01-01T00:12:12Z"}
{"s": 1, "m": 3.1415, "i": 1, "d": "2020-01-01T00:12:12Z"}
{"index": {}}
{"s": 2, "v": 1.0, "m": 6, "d": "2020-01-02T00:12:12Z"}
{"s": 2, "m": 1.0, "i": 6, "d": "2020-01-02T00:12:12Z"}
{"index": {}}
{"s": 3, "v": 2.71828, "m": -12, "d": "2019-12-31T00:12:12Z"}
{"s": 3, "m": 2.71828, "i": -12, "d": "2019-12-31T00:12:12Z"}
POST /test/_search?filter_path=aggregations
{
"aggs": {
"tm": {
"top_metrics": {
"metrics": [
{"field": "v"},
{"field": "m"},
{"field": "i"},
{"field": "d"}
],
"sort": {"s": "desc"}
Expand All @@ -118,8 +114,8 @@ Which returns:
"top": [ {
"sort": [3],
"metrics": {
"v": 2.718280076980591,
"m": -12,
"m": 2.718280076980591,
"i": -12,
"d": "2019-12-31T00:12:12.000Z"
}
} ]
Expand All @@ -137,19 +133,19 @@ Which returns:
----
POST /test/_bulk?refresh
{"index": {}}
{"s": 1, "v": 3.1415}
{"s": 1, "m": 3.1415}
{"index": {}}
{"s": 2, "v": 1.0}
{"s": 2, "m": 1.0}
{"index": {}}
{"s": 3, "v": 2.71828}
{"s": 3, "m": 2.71828}
POST /test/_search?filter_path=aggregations
{
"aggs": {
"tm": {
"top_metrics": {
"metrics": {"field": "v"},
"metrics": {"field": "m"},
"sort": {"s": "desc"},
"size": 2
"size": 3
}
}
}
Expand All @@ -164,8 +160,9 @@ Which returns:
"aggregations": {
"tm": {
"top": [
{"sort": [3], "metrics": {"v": 2.718280076980591 } },
{"sort": [2], "metrics": {"v": 1.0 } }
{"sort": [3], "metrics": {"m": 2.718280076980591 } },
{"sort": [2], "metrics": {"m": 1.0 } },
{"sort": [1], "metrics": {"m": 3.1414999961853027 } }
]
}
}
Expand All @@ -179,7 +176,8 @@ is a *very* conservative default maximum and you can raise it if you need to by
changing the `top_metrics_max_size` index setting. But know that large sizes can
take a fair bit of memory, especially if they are inside of an aggregation which
makes many buckes like a large
<<search-aggregations-metrics-top-metrics-example-terms, terms aggregation>>.
<<search-aggregations-metrics-top-metrics-example-terms, terms aggregation>>. If
you till want to raise it, use something like:

[source,console]
----
Expand All @@ -190,8 +188,7 @@ PUT /test/_settings
----
// TEST[continued]

NOTE: If `size` is more than `1` the `top_metrics` aggregation can't be the target of a sort.

NOTE: If `size` is more than `1` the `top_metrics` aggregation can't be the *target* of a sort.

==== Examples

Expand All @@ -214,11 +211,11 @@ PUT /node
}
POST /node/_bulk?refresh
{"index": {}}
{"ip": "192.168.0.1", "date": "2020-01-01T01:01:01", "v": 1}
{"ip": "192.168.0.1", "date": "2020-01-01T01:01:01", "m": 1}
{"index": {}}
{"ip": "192.168.0.1", "date": "2020-01-01T02:01:01", "v": 2}
{"ip": "192.168.0.1", "date": "2020-01-01T02:01:01", "m": 2}
{"index": {}}
{"ip": "192.168.0.2", "date": "2020-01-01T02:01:01", "v": 3}
{"ip": "192.168.0.2", "date": "2020-01-01T02:01:01", "m": 3}
POST /node/_search?filter_path=aggregations
{
"aggs": {
Expand All @@ -229,7 +226,7 @@ POST /node/_search?filter_path=aggregations
"aggs": {
"tm": {
"top_metrics": {
"metrics": {"field": "v"},
"metrics": {"field": "m"},
"sort": {"date": "desc"}
}
}
Expand All @@ -251,14 +248,14 @@ Which returns:
"key": "192.168.0.1",
"doc_count": 2,
"tm": {
"top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"v": 2 } } ]
"top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"m": 2 } } ]
}
},
{
"key": "192.168.0.2",
"doc_count": 1,
"tm": {
"top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"v": 3 } } ]
"top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"m": 3 } } ]
}
}
],
Expand All @@ -280,12 +277,12 @@ POST /node/_search?filter_path=aggregations
"ip": {
"terms": {
"field": "ip",
"order": {"tm.v": "desc"}
"order": {"tm.m": "desc"}
},
"aggs": {
"tm": {
"top_metrics": {
"metrics": {"field": "v"},
"metrics": {"field": "m"},
"sort": {"date": "desc"}
}
}
Expand All @@ -308,14 +305,14 @@ Which returns:
"key": "192.168.0.2",
"doc_count": 1,
"tm": {
"top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"v": 3 } } ]
"top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"m": 3 } } ]
}
},
{
"key": "192.168.0.1",
"doc_count": 2,
"tm": {
"top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"v": 2 } } ]
"top": [ {"sort": ["2020-01-01T02:01:01.000Z"], "metrics": {"m": 2 } } ]
}
}
],
Expand All @@ -337,17 +334,17 @@ always sorted independantly of whole numbered fields.
----
POST /test/_bulk?refresh
{"index": {"_index": "test1"}}
{"s": 1, "v": 3.1415}
{"s": 1, "m": 3.1415}
{"index": {"_index": "test1"}}
{"s": 2, "v": 1}
{"s": 2, "m": 1}
{"index": {"_index": "test2"}}
{"s": 3.1, "v": 2.71828}
{"s": 3.1, "m": 2.71828}
POST /test*/_search?filter_path=aggregations
{
"aggs": {
"tm": {
"top_metrics": {
"metrics": {"field": "v"},
"metrics": {"field": "m"},
"sort": {"s": "asc"}
}
}
Expand All @@ -362,7 +359,7 @@ Which returns:
{
"aggregations": {
"tm": {
"top": [ {"sort": [3.0999999046325684], "metrics": {"v": 2.718280076980591 } } ]
"top": [ {"sort": [3.0999999046325684], "metrics": {"m": 2.718280076980591 } } ]
}
}
}
Expand All @@ -380,7 +377,7 @@ POST /test*/_search?filter_path=aggregations
"aggs": {
"tm": {
"top_metrics": {
"metrics": {"field": "v"},
"metrics": {"field": "m"},
"sort": {"s": {"order": "asc", "numeric_type": "double"}}
}
}
Expand All @@ -396,7 +393,7 @@ Which returns the much more expected:
{
"aggregations": {
"tm": {
"top": [ {"sort": [1.0], "metrics": {"v": 3.1414999961853027 } } ]
"top": [ {"sort": [1.0], "metrics": {"m": 3.1414999961853027 } } ]
}
}
}
Expand Down
3 changes: 3 additions & 0 deletions docs/reference/aggregations/metrics/tophits-aggregation.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,9 @@ The top_hits aggregation returns regular search hits, because of this many per h
* <<request-body-search-version,Include versions>>
* <<request-body-search-seq-no-primary-term,Include Sequence Numbers and Primary Terms>>

IMPORTANT: If you *only* need `docvalue_fields`, `size`, and `sort` then
<<search-aggregations-metrics-top-metrics>> might be a more efficient choice than the Top Hits Aggregation.

==== Example

In the following example we group the sales by type and per type we show the last sale.
Expand Down

0 comments on commit f7482f7

Please sign in to comment.