Browse Source

Docs: Refine note about `after_key` (#50475)

* Docs: Refine note about `after_key`

I was curious about composite aggregations, specifically I wanted to
know how to write a composite aggregation that had all of its buckets
filtered out so you *had* to use the `after_key`. Then I saw that we've
declared composite aggregations not to work with pipelines in #44180. So
I'm not sure you *can* do that any more. Which makes the note about
`after_key` inaccurate. This rejiggers that section of the docs a little
so it is more obvious that you send the `after_key` back to us. And so
it is more obvious that you should *only* use the `after_key` that we
give you rather than try to work it out for yourself.

* Apply suggestions from code review

Co-Authored-By: James Rodewig <james.rodewig@elastic.co>

Co-authored-by: James Rodewig <james.rodewig@elastic.co>
Nik Everett 5 years ago
parent
commit
a7cc0b0159
1 changed files with 8 additions and 12 deletions
  1. 8 12
      docs/reference/aggregations/bucket/composite-aggregation.asciidoc

+ 8 - 12
docs/reference/aggregations/bucket/composite-aggregation.asciidoc

@@ -441,7 +441,7 @@ GET /_search
     ...
     "aggregations": {
         "my_buckets": {
-            "after_key": { <1>
+            "after_key": {
                 "date": 1494288000000,
                 "product": "mad max"
             },
@@ -467,17 +467,9 @@ GET /_search
 --------------------------------------------------
 // TESTRESPONSE[s/\.\.\.//]
 
-<1> The last composite bucket returned by the query.
-
-NOTE: The `after_key` is equals to the last bucket returned in the response before
-any filtering that could be done by <<search-aggregations-pipeline, Pipeline aggregations>>.
-If all buckets are filtered/removed by a pipeline aggregation, the `after_key` will contain
-the last bucket before filtering.
-
-The `after` parameter can be used to retrieve the composite buckets that are **after**
-the last composite buckets returned in a previous round.
-For the example below the last bucket can be found in `after_key` and the next
-round of result can be retrieved with:
+To get the next set of buckets, resend the same aggregation with the `after`
+parameter set to the `after_key` value returned in the response.
+For example, this request uses the `after_key` value provided in the previous response:
 
 [source,console,id=composite-aggregation-after-example]
 --------------------------------------------------
@@ -501,6 +493,10 @@ GET /_search
 
 <1> Should restrict the aggregation to buckets that sort **after** the provided values.
 
+NOTE: The `after_key` is *usually* the key to the last bucket returned in
+the response, but that isn't guaranteed. Always use the returned `after_key` instead
+of derriving it from the buckets.
+
 ==== Early termination
 
 For optimal performance the <<index-modules-index-sorting,index sort>> should be set on the index so that it matches