From af285f1aa4173418beb9fbfc0ba1914bcc3be103 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Tue, 20 Sep 2016 00:12:17 -0400 Subject: [PATCH] Convert more docs to CONSOLE * reference/api-conventions.asciidoc * reference/redirects.asciidoc Relates to #18160 --- .../doc/RestTestsFromSnippetsTask.groovy | 5 + docs/build.gradle | 2 - docs/reference/api-conventions.asciidoc | 230 ++++++++++++------ docs/reference/redirects.asciidoc | 4 +- 4 files changed, 159 insertions(+), 82 deletions(-) diff --git a/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy b/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy index 17a889e677f..9b83545f652 100644 --- a/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy +++ b/buildSrc/src/main/groovy/org/elasticsearch/gradle/doc/RestTestsFromSnippetsTask.groovy @@ -191,6 +191,11 @@ public class RestTestsFromSnippetsTask extends SnippetsTask { def (String path, String query) = pathAndQuery.tokenize('?') if (path == null) { path = '' // Catch requests to the root... + } else { + // Escape some characters that are also escaped by sense + path = path.replace('<', '%3C').replace('>', '%3E') + path = path.replace('{', '%7B').replace('}', '%7D') + path = path.replace('|', '%7C') } current.println(" - do:") if (catchPart != null) { diff --git a/docs/build.gradle b/docs/build.gradle index f764ea9c395..f32bed24200 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -96,7 +96,6 @@ buildRestTests.expectedUnconvertedCandidates = [ 'reference/analysis/tokenfilters/stop-tokenfilter.asciidoc', 'reference/analysis/tokenfilters/synonym-tokenfilter.asciidoc', 'reference/analysis/tokenfilters/word-delimiter-tokenfilter.asciidoc', - 'reference/api-conventions.asciidoc', 'reference/cat.asciidoc', 'reference/cat/alias.asciidoc', 'reference/cat/allocation.asciidoc', @@ -172,7 +171,6 @@ buildRestTests.expectedUnconvertedCandidates = [ 'reference/query-dsl/function-score-query.asciidoc', 'reference/query-dsl/geo-shape-query.asciidoc', 'reference/query-dsl/terms-query.asciidoc', - 'reference/redirects.asciidoc', 'reference/search/field-stats.asciidoc', 'reference/search/multi-search.asciidoc', 'reference/search/profile.asciidoc', diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index 06c3b9409eb..2cc1b9bb115 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -88,12 +88,18 @@ You must enclose date math index name expressions within angle brackets. For exa [source,js] ---------------------------------------------------------------------- -curl -XGET 'localhost:9200//_search' { +GET //_search +{ "query" : { - ... + "match": { + "test": "data" + } } } ---------------------------------------------------------------------- +// CONSOLE +// TEST[s/^/PUT logstash-2016.09.20\n/] +// TEST[s/\{now/{2016.09.20||/] NOTE: The `/` used for date rounding must be url encoded as `%2F` in any url. @@ -102,11 +108,11 @@ they resolve to given the current time is 22rd March 2024 noon utc. [options="header"] |====== -| Expression |Resolves to -| `` | `logstash-2024.03.22` -| `` | `logstash-2024.03.01` -| `` | `logstash-2024.03` -| `` | `logstash-2024.02` +| Expression |Resolves to +| `` | `logstash-2024.03.22` +| `` | `logstash-2024.03.01` +| `` | `logstash-2024.03` +| `` | `logstash-2024.02` | `` | `logstash-2024.03.23` |====== @@ -121,12 +127,18 @@ three days, assuming the indices use the default Logstash index name format, [source,js] ---------------------------------------------------------------------- -curl -XGET 'localhost:9200/,,/_search' { +GET /,,/_search +{ "query" : { - ... + "match": { + "test": "data" + } } } ---------------------------------------------------------------------- +// CONSOLE +// TEST[s/^/PUT logstash-2016.09.20\nPUT logstash-2016.09.19\nPUT logstash-2016.09.18\n/] +// TEST[s/\{now/{2016.09.20||/] [[common-options]] == Common options @@ -199,117 +211,133 @@ All REST APIs accept a `filter_path` parameter that can be used to reduce the response returned by elasticsearch. This parameter takes a comma separated list of filters expressed with the dot notation: -[source,sh] +[source,js] +-------------------------------------------------- +GET /_search?q=elasticsearch&filter_path=took,hits.hits._id,hits.hits._score +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] + +Responds: + +[source,js] -------------------------------------------------- -curl -XGET 'localhost:9200/_search?pretty&filter_path=took,hits.hits._id,hits.hits._score' { "took" : 3, "hits" : { "hits" : [ { - "_id" : "3640", - "_score" : 1.0 - }, - { - "_id" : "3642", - "_score" : 1.0 + "_id" : "0", + "_score" : 1.6375021 } ] } } -------------------------------------------------- +// TESTRESPONSE[s/"took" : 3/"took" : $body.took/] It also supports the `*` wildcard character to match any field or part of a field's name: [source,sh] -------------------------------------------------- -curl -XGET 'localhost:9200/_nodes/stats?filter_path=nodes.*.ho*' +GET /_cluster/state?filter_path=metadata.indices.*.stat* +-------------------------------------------------- +// CONSOLE +// TEST[s/^/PUT twitter\n/] + +Responds: + +[source,sh] +-------------------------------------------------- { - "nodes" : { - "lvJHed8uQQu4brS-SXKsNA" : { - "host" : "portable" + "metadata" : { + "indices" : { + "twitter": {"state": "open"} } } } -------------------------------------------------- +// TESTRESPONSE And the `**` wildcard can be used to include fields without knowing the exact path of the field. For example, we can return the Lucene version of every segment with this request: -[source,sh] +[source,js] +-------------------------------------------------- +GET /_cluster/state?filter_path=routing_table.indices.**.state +-------------------------------------------------- +// CONSOLE +// TEST[s/^/PUT twitter\n/] + +Responds: + +[source,js] -------------------------------------------------- -curl 'localhost:9200/_segments?pretty&filter_path=indices.**.version' { - "indices" : { - "movies" : { - "shards" : { - "0" : [ { - "segments" : { - "_0" : { - "version" : "5.2.0" - } - } - } ], - "2" : [ { - "segments" : { - "_0" : { - "version" : "5.2.0" - } - } - } ] - } - }, - "books" : { - "shards" : { - "0" : [ { - "segments" : { - "_0" : { - "version" : "5.2.0" - } - } - } ] + "routing_table": { + "indices": { + "twitter": { + "shards": { + "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}], + "1": [{"state": "STARTED"}, {"state": "UNASSIGNED"}], + "2": [{"state": "STARTED"}, {"state": "UNASSIGNED"}], + "3": [{"state": "STARTED"}, {"state": "UNASSIGNED"}], + "4": [{"state": "STARTED"}, {"state": "UNASSIGNED"}] + } } } } } -------------------------------------------------- +// TESTRESPONSE It is also possible to exclude one or more fields by prefixing the filter with the char `-`: -[source,sh] +[source,js] +-------------------------------------------------- +GET /_count?filter_path=-_shards +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] + +Responds: + +[source,js] -------------------------------------------------- -curl -XGET 'localhost:9200/_count?filter_path=-_shards' { - "count" : 1 + "count" : 5 } -% -------------------------------------------------- +// TESTRESPONSE And for more control, both inclusive and exclusive filters can be combined in the same expression. In this case, the exclusive filters will be applied first and the result will be filtered again using the inclusive filters: -[source,sh] +[source,js] +-------------------------------------------------- +GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-* +-------------------------------------------------- +// CONSOLE +// TEST[s/^/PUT index-1\nPUT index-2\nPUT index-3\nPUT logstash-2016.01\n/] + +Responds: + +[source,js] -------------------------------------------------- -curl -XGET 'localhost:9200/_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logs-*' { "metadata" : { "indices" : { - "index-1" : { - "state" : "open" - }, - "index-3" : { - "state" : "open" - }, - "index-2" : { - "state" : "open" - } + "index-1" : {"state" : "open"}, + "index-2" : {"state" : "open"}, + "index-3" : {"state" : "open"} } } -}% +} -------------------------------------------------- +// TESTRESPONSE Note that elasticsearch sometimes returns directly the raw value of a field, like the `_source` field. If you want to filter `_source` fields, you should @@ -317,21 +345,33 @@ consider combining the already existing `_source` parameter (see <> for more details) with the `filter_path` parameter like this: -[source,sh] +[source,js] +-------------------------------------------------- +POST /library/book?refresh +{"title": "Book #1", "rating": 200.1} +POST /library/book?refresh +{"title": "Book #2", "rating": 1.7} +POST /library/book?refresh +{"title": "Book #3", "rating": 0.1} +GET /_search?filter_path=hits.hits._source&_source=title&sort=rating:desc +-------------------------------------------------- +// CONSOLE + +[source,js] -------------------------------------------------- -curl -XGET 'localhost:9200/_search?pretty&filter_path=hits.hits._source&_source=title' { "hits" : { "hits" : [ { - "_source":{"title":"Book #2"} - }, { "_source":{"title":"Book #1"} + }, { + "_source":{"title":"Book #2"} }, { "_source":{"title":"Book #3"} } ] } } -------------------------------------------------- +// TESTRESPONSE [float] @@ -340,32 +380,64 @@ curl -XGET 'localhost:9200/_search?pretty&filter_path=hits.hits._source&_source= The `flat_settings` flag affects rendering of the lists of settings. When `flat_settings` flag is `true` settings are returned in a flat format: +[source,js] +-------------------------------------------------- +GET twitter/_settings?flat_settings=true +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] + +Returns: + [source,js] -------------------------------------------------- { - "persistent" : { }, - "transient" : { - "discovery.zen.minimum_master_nodes" : "1" + "twitter" : { + "settings": { + "index.number_of_replicas": "1", + "index.number_of_shards": "1", + "index.creation_date": "1474389951325", + "index.uuid": "n6gzFZTgS664GUfx0Xrpjw", + "index.version.created": "6000001" + } } } -------------------------------------------------- +// TESTRESPONSE[s/1474389951325/$body.twitter.settings.index\\\\.creation_date/] +// TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.twitter.settings.index\\\\.uuid/] When the `flat_settings` flag is `false` settings are returned in a more human readable structured format: +[source,js] +-------------------------------------------------- +GET twitter/_settings?flat_settings=false +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] + +Returns: + [source,js] -------------------------------------------------- { - "persistent" : { }, - "transient" : { - "discovery" : { - "zen" : { - "minimum_master_nodes" : "1" + "twitter" : { + "settings" : { + "index" : { + "number_of_replicas": "1", + "number_of_shards": "1", + "creation_date": "1474389951325", + "uuid": "n6gzFZTgS664GUfx0Xrpjw", + "version": { + "created": "6000001" + } } } } } -------------------------------------------------- +// TESTRESPONSE[s/1474389951325/$body.twitter.settings.index.creation_date/] +// TESTRESPONSE[s/n6gzFZTgS664GUfx0Xrpjw/$body.twitter.settings.index.uuid/] By default the `flat_settings` is set to `false`. diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 78a8d310aaa..570568b43a0 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -251,7 +251,7 @@ the <> parameter with the [role="exclude",id="query-dsl-geohash-cell-query"] === Geohash Cell Query -The `geohash_cell` query has been removed. Instead use the +The `geohash_cell` query has been removed. Instead use the <>. [role="exclude",id="search-more-like-this"] @@ -376,6 +376,7 @@ GET _search } } ------------------------- +// NOTCONSOLE move the query and filter to the `must` and `filter` parameters in the `bool` query: @@ -400,6 +401,7 @@ GET _search } } ------------------------- +// CONSOLE [role="exclude",id="query-dsl-or-query"] === Or query