honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve top_metrics docs (#53521) (#53619) 

* 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
This commit is contained in:
Nik Everett 2020-03-16 13:47:43 -04:00 committed by GitHub
parent 031932b32f
commit f7482f794a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 48 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
docs/reference/aggregations/metrics/top-metrics-aggregation.asciidoc
View File

@ -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"}
}
}
@ -37,7 +35,7 @@ Which returns:
{
"aggregations": {
"tm": {
"top": [ {"sort": [3], "metrics": {"v": 2.718280076980591 } } ]
"top": [ {"sort": [3], "metrics": {"m": 2.718280076980591 } } ]
}
}
}
@ -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,
@ -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]
----
@ -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"}
@ -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"
}
} ]
@ -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
}
}
}
@ -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 } }
]
}
}
@ -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]
----
@ -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
@ -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": {
@ -229,7 +226,7 @@ POST /node/_search?filter_path=aggregations
"aggs": {
"tm": {
"top_metrics": {
"metrics": {"field": "v"},
"metrics": {"field": "m"},
"sort": {"date": "desc"}
}
}
@ -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 } } ]
}
}
],
@ -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"}
}
}
@ -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 } } ]
}
}
],
@ -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"}
}
}
@ -362,7 +359,7 @@ Which returns:
{
"aggregations": {
"tm": {
"top": [ {"sort": [3.0999999046325684], "metrics": {"v": 2.718280076980591 } } ]
"top": [ {"sort": [3.0999999046325684], "metrics": {"m": 2.718280076980591 } } ]
}
}
}
@ -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"}}
}
}
@ -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 } } ]
}
}
}

3
docs/reference/aggregations/metrics/tophits-aggregation.asciidoc
View File

@ -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.