From 41d6529d062bcfd53a10d2c9f3c537d0c9fe1500 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Wed, 5 Oct 2016 11:16:40 -0400 Subject: [PATCH] CONSOLEify scroll docs This causes the snippets to be tested during the build and gives helpful links to the reader to open the docs in console or copy them as curl commands. Relates to #18160 --- docs/build.gradle | 1 - docs/reference/search/request/scroll.asciidoc | 55 ++++++++++--------- 2 files changed, 30 insertions(+), 26 deletions(-) diff --git a/docs/build.gradle b/docs/build.gradle index 2d550e1f191..44b467dee9e 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -171,7 +171,6 @@ buildRestTests.expectedUnconvertedCandidates = [ 'reference/search/request/highlighting.asciidoc', 'reference/search/request/inner-hits.asciidoc', 'reference/search/request/rescore.asciidoc', - 'reference/search/request/scroll.asciidoc', 'reference/search/search-template.asciidoc', 'reference/search/suggesters/completion-suggest.asciidoc', ] diff --git a/docs/reference/search/request/scroll.asciidoc b/docs/reference/search/request/scroll.asciidoc index d924a56b652..bee8e158175 100644 --- a/docs/reference/search/request/scroll.asciidoc +++ b/docs/reference/search/request/scroll.asciidoc @@ -38,7 +38,7 @@ should keep the ``search context'' alive (see <>), eg `?s [source,js] -------------------------------------------------- -curl -XGET 'localhost:9200/twitter/tweet/_search?scroll=1m' -d ' +POST /twitter/tweet/_search?scroll=1m { "query": { "match" : { @@ -46,8 +46,9 @@ curl -XGET 'localhost:9200/twitter/tweet/_search?scroll=1m' -d ' } } } -' -------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] The result from the above request includes a `_scroll_id`, which should be passed to the `scroll` API in order to retrieve the next batch of @@ -55,13 +56,14 @@ results. [source,js] -------------------------------------------------- -curl -XGET <1> 'localhost:9200/_search/scroll' <2> -d' +POST <1> /_search/scroll <2> { "scroll" : "1m", <3> - "scroll_id" : "c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1" <4> + "scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==" <4> } -' -------------------------------------------------- +// CONSOLE +// TEST[continued s/DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==/$body._scroll_id/] <1> `GET` or `POST` can be used. <2> The URL should not include the `index` or `type` name -- these @@ -73,14 +75,6 @@ curl -XGET <1> 'localhost:9200/_search/scroll' <2> -d' Each call to the `scroll` API returns the next batch of results until there are no more results left to return, ie the `hits` array is empty. -For backwards compatibility, `scroll_id` and `scroll` can be passed in the query string. -And the `scroll_id` can be passed in the request body - -[source,js] --------------------------------------------------- -curl -XGET 'localhost:9200/_search/scroll?scroll=1m' -d 'c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1' --------------------------------------------------- - IMPORTANT: The initial search request and each subsequent scroll request returns a new `_scroll_id` -- only the most recent `_scroll_id` should be used. @@ -94,14 +88,15 @@ order, this is the most efficient option: [source,js] -------------------------------------------------- -curl -XGET 'localhost:9200/_search?scroll=1m' -d ' +GET /_search?scroll=1m { "sort": [ "_doc" ] } -' -------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] [[scroll-search-context]] ==== Keeping the search context alive @@ -130,8 +125,9 @@ You can check how many search contexts are open with the [source,js] --------------------------------------- -curl -XGET localhost:9200/_nodes/stats/indices/search?pretty +GET /_nodes/stats/indices/search --------------------------------------- +// CONSOLE ==== Clear scroll API @@ -143,37 +139,46 @@ cleared as soon as the scroll is not being used anymore using the [source,js] --------------------------------------- -curl -XDELETE localhost:9200/_search/scroll -d ' +DELETE /_search/scroll { - "scroll_id" : ["c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1"] -}' + "scroll_id" : ["DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ=="] +} --------------------------------------- +// CONSOLE +// TEST[catch:missing] Multiple scroll IDs can be passed as array: [source,js] --------------------------------------- -curl -XDELETE localhost:9200/_search/scroll -d ' +DELETE /_search/scroll { - "scroll_id" : ["c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1", "aGVuRmV0Y2g7NTsxOnkxaDZ"] -}' + "scroll_id" : [ + "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==", + "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAAABFmtSWWRRWUJrU2o2ZExpSGJCVmQxYUEAAAAAAAAAAxZrUllkUVlCa1NqNmRMaUhiQlZkMWFBAAAAAAAAAAIWa1JZZFFZQmtTajZkTGlIYkJWZDFhQQAAAAAAAAAFFmtSWWRRWUJrU2o2ZExpSGJCVmQxYUEAAAAAAAAABBZrUllkUVlCa1NqNmRMaUhiQlZkMWFB" + ] +} --------------------------------------- +// CONSOLE +// TEST[catch:missing] All search contexts can be cleared with the `_all` parameter: [source,js] --------------------------------------- -curl -XDELETE localhost:9200/_search/scroll/_all +DELETE /_search/scroll/_all --------------------------------------- +// CONSOLE The `scroll_id` can also be passed as a query string parameter or in the request body. Multiple scroll IDs can be passed as comma separated values: [source,js] --------------------------------------- -curl -XDELETE localhost:9200/_search/scroll \ - -d 'c2Nhbjs2OzM0NDg1ODpzRlBLc0FXNlNyNm5JWUc1,aGVuRmV0Y2g7NTsxOnkxaDZ' +DELETE /_search/scroll/DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAD4WYm9laVYtZndUQlNsdDcwakFMNjU1QQ==,DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAAABFmtSWWRRWUJrU2o2ZExpSGJCVmQxYUEAAAAAAAAAAxZrUllkUVlCa1NqNmRMaUhiQlZkMWFBAAAAAAAAAAIWa1JZZFFZQmtTajZkTGlIYkJWZDFhQQAAAAAAAAAFFmtSWWRRWUJrU2o2ZExpSGJCVmQxYUEAAAAAAAAABBZrUllkUVlCa1NqNmRMaUhiQlZkMWFB --------------------------------------- +// CONSOLE +// TEST[catch:missing] [[sliced-scroll]] ==== Sliced Scroll