From 55107ce8ae46f96a51d28681f87b3c6986be0a8d Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Thu, 2 Jan 2020 10:02:55 -0500 Subject: [PATCH] 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 Co-authored-by: James Rodewig --- .../bucket/composite-aggregation.asciidoc | 20 ++++++++----------- 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/reference/aggregations/bucket/composite-aggregation.asciidoc b/docs/reference/aggregations/bucket/composite-aggregation.asciidoc index e6059358d1d..0d5dad25b8e 100644 --- a/docs/reference/aggregations/bucket/composite-aggregation.asciidoc +++ b/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 <>. -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] -------------------------------------------------- @@ -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 <> should be set on the index so that it matches