Add docs for the fields retrieval API. (#58787)

This PR adds docs for the `fields` parameter. We now present `fields` as the
preferred way to load specific fields in a search, with `docvalue_fields` and
`stored_fields` as other options to look into. Source filtering is no longer
featured prominently, and its section is moved to the end.

Author: jtibshirani

docs/build.gradle

@@ -144,23 +144,28 @@ Closure setupTwitter = { String name, int count ->
                   type: date
                 likes:
                   type: long
+                location:
+                  properties:
+                    city:
+                      type: keyword
+                    country:
+                      type: keyword
   - do:
         bulk:
           index: twitter
           refresh: true
           body: |'''
   for (int i = 0; i < count; i++) {
-    String user, text
+    String body
     if (i == 0) {
-      user = 'kimchy'
-      text = 'trying out Elasticsearch'
+      body = """{"user": "kimchy", "message": "trying out Elasticsearch", "date": "2009-11-15T14:12:12", "likes": 0,
+              "location": { "city": "Amsterdam", "country": "Netherlands" }}"""
     } else {
-      user = 'test'
-      text = "some message with the number $i"
+      body = """{"user": "test", "message": "some message with the number $i", "date": "2009-11-15T14:12:12", "likes": $i}"""
     }
     buildRestTests.setups[name] += """
             {"index":{"_id": "$i"}}
-            {"user": "$user", "message": "$text", "date": "2009-11-15T14:12:12", "likes": $i}"""
+            $body"""
   }
 }
 setupTwitter('twitter', 5)

docs/reference/aggregations/misc.asciidoc

@@ -105,7 +105,8 @@ GET /twitter/_search?typed_keys
       "aggregations": {
         "top_users": {
             "top_hits": {
-                "size": 1
+                "size": 1,
+                "_source": ["user", "likes", "message"]
             }
         }
       }
@@ -141,9 +142,8 @@ In the response, the aggregations names will be changed to respectively `date_hi
                                   "_id": "0",
                                   "_score": 1.0,
                                   "_source": {
-                                    "date": "2009-11-15T14:12:12",
-                                    "message": "trying out Elasticsearch",
                                     "user": "kimchy",
+                                    "message": "trying out Elasticsearch",
                                     "likes": 0
                                   }
                                 }
@@ -167,12 +167,12 @@ request. This is the case for Terms, Significant Terms and Percentiles aggregati
 also contains information about the type of the targeted field: `lterms` (for a terms aggregation on a Long field),
  `sigsterms` (for a significant terms aggregation on a String field), `tdigest_percentiles` (for a percentile
  aggregation based on the TDigest algorithm).
- 
+
 
 [[indexing-aggregation-results]]
 == Indexing aggregation results with {transforms}
- 
-<<transforms,{transforms-cap}>> enable you to convert existing {es} indices 
-into summarized indices, which provide opportunities for new insights and 
-analytics. You can use {transforms} to persistently index your aggregation 
+
+<<transforms,{transforms-cap}>> enable you to convert existing {es} indices
+into summarized indices, which provide opportunities for new insights and
+analytics. You can use {transforms} to persistently index your aggregation
 results into entity-centric indices.

docs/reference/docs/get.asciidoc

@@ -241,7 +241,11 @@ The API returns the following result:
         "user" : "kimchy",
         "date" : "2009-11-15T14:12:12",
         "likes": 0,
-        "message" : "trying out Elasticsearch"
+        "message" : "trying out Elasticsearch",
+        "location" : {
+          "city": "Amsterdam",
+          "country": "Netherlands"
+        }
     }
 }
 --------------------------------------------------

docs/reference/modules/cross-cluster-search.asciidoc

@@ -76,7 +76,8 @@ GET /cluster_one:twitter/_search
     "match": {
       "user": "kimchy"
     }
-  }
+  },
+  "_source": ["user", "message", "likes"]
 }
 --------------------------------------------------
 // TEST[continued]
@@ -113,7 +114,6 @@ The API returns the following response:
         "_score": 1,
         "_source": {
           "user": "kimchy",
-          "date": "2009-11-15T14:12:12",
           "message": "trying out Elasticsearch",
           "likes": 0
         }
@@ -147,7 +147,8 @@ GET /twitter,cluster_one:twitter,cluster_two:twitter/_search
     "match": {
       "user": "kimchy"
     }
-  }
+  },
+  "_source": ["user", "message", "likes"]
 }
 --------------------------------------------------
 // TEST[continued]
@@ -184,7 +185,6 @@ The API returns the following response:
         "_score": 2,
         "_source": {
           "user": "kimchy",
-          "date": "2009-11-15T14:12:12",
           "message": "trying out Elasticsearch",
           "likes": 0
         }
@@ -195,7 +195,6 @@ The API returns the following response:
         "_score": 1,
         "_source": {
           "user": "kimchy",
-          "date": "2009-11-15T14:12:12",
           "message": "trying out Elasticsearch",
           "likes": 0
         }
@@ -206,7 +205,6 @@ The API returns the following response:
         "_score": 1,
         "_source": {
           "user": "kimchy",
-          "date": "2009-11-15T14:12:12",
           "message": "trying out Elasticsearch",
           "likes": 0
         }