Rename _path to filter_path and update doc

Author: tlrx

docs/reference/api-conventions.asciidoc

@@ -82,15 +82,15 @@ consumption.  The default for the `human` flag is
 `false`.
 
 [float]
-=== Response filtering
+=== Response Filtering
 
-All REST APIs accept a `_path` parameter that can be used to reduce
+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]
 --------------------------------------------------
-curl -XGET 'localhost:9200/_search?pretty&_path=took,hits.hits._id,hits.hits._score'
+curl -XGET 'localhost:9200/_search?pretty&filter_path=took,hits.hits._id,hits.hits._score'
 {
   "took" : 3,
   "hits" : {
@@ -113,7 +113,7 @@ of a field's name:
 
 [source,sh]
 --------------------------------------------------
-curl -XGET 'localhost:9200/_nodes/stats?_path=nodes.*.ho*'
+curl -XGET 'localhost:9200/_nodes/stats?filter_path=nodes.*.ho*'
 {
   "nodes" : {
     "lvJHed8uQQu4brS-SXKsNA" : {
@@ -123,13 +123,13 @@ curl -XGET 'localhost:9200/_nodes/stats?_path=nodes.*.ho*'
 }
 --------------------------------------------------
 
-And the `**` wildcard can used to include fields without knowing the
+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]
 --------------------------------------------------
-curl 'localhost:9200/_segments?pretty&_path=indices.**.version'
+curl 'localhost:9200/_segments?pretty&filter_path=indices.**.version'
 {
   "indices" : {
     "movies" : {
@@ -166,9 +166,26 @@ curl 'localhost:9200/_segments?pretty&_path=indices.**.version'
 --------------------------------------------------
 
 Note that elasticsearch sometimes returns directly the raw value of a field,
-like the `_source` field. If you want to filter the response that include
-_source fields, you should consider using the already existing `_source`
-parameter (see <<get-source-filtering,Get API>> for more details).
+like the `_source` field. If you want to filter _source fields, you should
+consider combining the already existing `_source` parameter (see
+<<get-source-filtering,Get API>> for more details) with the `filter_path`
+ parameter like this:
+
+[source,sh]
+--------------------------------------------------
+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 #3"}
+    } ]
+  }
+}
+--------------------------------------------------
 
 
 [float]

rest-api-spec/api/nodes.stats.json

@@ -56,7 +56,7 @@
           "options" : ["node", "indices", "shards"],
           "default" : "node"
         },
-        "_path": {
+        "filter_path": {
           "type" : "list",
           "description" : "A comma-separated list of fields to include in the returned response"
         },

rest-api-spec/api/search.json

@@ -72,7 +72,7 @@
           "type" : "boolean",
           "description" : "Specify whether query terms should be lowercased"
         },
-        "_path": {
+        "filter_path": {
           "type" : "list",
           "description" : "A comma-separated list of fields to include in the returned response"
         },

rest-api-spec/test/nodes.stats/20_response_filtering.yaml

@@ -28,7 +28,7 @@
   # Nodes Stats with only "cluster_name" field
   - do:
       nodes.stats:
-        _path: cluster_name
+        filter_path: cluster_name
 
   - is_true:  cluster_name
   - is_false: nodes
@@ -39,7 +39,7 @@
   # Nodes Stats with "nodes" field and sub-fields
   - do:
       nodes.stats:
-        _path: nodes.*
+        filter_path: nodes.*
 
   - is_false: cluster_name
   - is_true:  nodes
@@ -59,7 +59,7 @@
   # Nodes Stats with "nodes.*.indices" field and sub-fields
   - do:
       nodes.stats:
-        _path: nodes.*.indices
+        filter_path: nodes.*.indices
 
   - is_false: cluster_name
   - is_true:  nodes
@@ -74,7 +74,7 @@
   # Nodes Stats with "nodes.*.name" and "nodes.*.indices.docs.count" fields
   - do:
       nodes.stats:
-        _path: [ "nodes.*.name", "nodes.*.indices.docs.count" ]
+        filter_path: [ "nodes.*.name", "nodes.*.indices.docs.count" ]
 
   - is_false: cluster_name
   - is_true:  nodes
@@ -88,7 +88,7 @@
   # Nodes Stats with all "count" fields
   - do:
       nodes.stats:
-        _path: "nodes.**.count"
+        filter_path: "nodes.**.count"
 
   - is_false: cluster_name
   - is_true:  nodes
@@ -108,7 +108,7 @@
   # Nodes Stats with all "count" fields in sub-fields of "jvm" field
   - do:
       nodes.stats:
-        _path: "nodes.**.jvm.**.count"
+        filter_path: "nodes.**.jvm.**.count"
 
   - is_false: cluster_name
   - is_true:  nodes
@@ -126,7 +126,7 @@
   # Nodes Stats with "nodes.*.fs.data" fields
   - do:
       nodes.stats:
-        _path: "nodes.*.fs.data"
+        filter_path: "nodes.*.fs.data"
 
   - is_false: cluster_name
   - is_true:  nodes
@@ -141,7 +141,7 @@
   # Nodes Stats with "nodes.*.fs.data.t*" fields
   - do:
       nodes.stats:
-        _path: "nodes.*.fs.data.t*"
+        filter_path: "nodes.*.fs.data.t*"
 
   - is_false: cluster_name
   - is_true:  nodes

rest-api-spec/test/search/70_response_filtering.yaml

@@ -24,7 +24,7 @@
   - do:
       search:
         index: test
-        _path: "*"
+        filter_path: "*"
         body: "{ query: { match_all: {} } }"
 
   - is_true: took
@@ -40,7 +40,7 @@
   - do:
       search:
         index: test
-        _path: "took"
+        filter_path: "took"
         body: "{ query: { match_all: {} } }"
 
   - is_true:  took
@@ -56,7 +56,7 @@
   - do:
       search:
         index: test
-        _path: "_shards.*"
+        filter_path: "_shards.*"
         body: "{ query: { match_all: {} } }"
 
   - is_false: took
@@ -72,7 +72,7 @@
   - do:
       search:
         index: test
-        _path: [ "hits.**._i*", "**.total" ]
+        filter_path: [ "hits.**._i*", "**.total" ]
         body: "{ query: { match_all: {} } }"
 
   - is_false: took

src/main/java/org/elasticsearch/rest/RestChannel.java

@@ -44,7 +44,7 @@ protected RestChannel(RestRequest request, boolean detailedErrorsEnabled) {
     }
 
     public XContentBuilder newBuilder() throws IOException {
-        return newBuilder(request.hasContent() ? request.content() : null, request.hasParam("_path"));
+        return newBuilder(request.hasContent() ? request.content() : null, request.hasParam("filter_path"));
     }
 
     public XContentBuilder newErrorBuilder() throws IOException {
@@ -65,7 +65,7 @@ public XContentBuilder newBuilder(@Nullable BytesReference autoDetectSource, boo
             contentType = XContentType.JSON;
         }
 
-        String[] filters = useFiltering ? request.paramAsStringArrayOrEmptyIfAll("_path") :  null;
+        String[] filters = useFiltering ? request.paramAsStringArrayOrEmptyIfAll("filter_path") :  null;
         XContentBuilder builder = new XContentBuilder(XContentFactory.xContent(contentType), bytesOutput(), filters);
         if (request.paramAsBoolean("pretty", false)) {
             builder.prettyPrint().lfAtEnd();