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.
elastic · Jul 22, 2020 · 0f96e16 · 0f96e16
1 parent 0a98626
commit 0f96e16
Show file tree

Hide file tree

Showing 5 changed files with 221 additions and 104 deletions.
diff --git a/docs/build.gradle b/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)

diff --git a/docs/reference/aggregations/misc.asciidoc b/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"]
             }
         }
       }
@@ -133,17 +134,16 @@ In the response, the aggregations names will be changed to respectively `date_hi
               "total": {
                 "value": 5,
                 "relation": "eq"
-            },
+              },
               "max_score": 1.0,
               "hits": [
                 {
                   "_index": "twitter",
                   "_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.
diff --git a/docs/reference/docs/get.asciidoc b/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"
+    }
   }
 }
 --------------------------------------------------

diff --git a/docs/reference/modules/cross-cluster-search.asciidoc b/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
         }