Docs: Improve the Field Usage Stats API Documentation (#96333)

Adds descriptions of the values returned in the response body of the _field_usage_stats API.

Closes #88313

docs/reference/indices/field-usage-stats.asciidoc

@@ -56,6 +56,85 @@ Comma-separated list or wildcard expressions of fields
 to include in the statistics.
 --
 
+[role="child_attributes"]
+[[field-usage-stats-api-response-body]]
+==== {api-response-body-title}
+The response body reports the per-shard usage count of the data structures that back the fields in the index.
+A given request will increment each count by a maximum value of 1, even if the request accesses the same field multiple times.
+
+`any`::
+(integer)
+Denotes any kind of use of the field (e.g. via the _inverted index_, _stored fields_, _doc values_, etc.)
+such that any usage is counted once for a given search request.
+
+`inverted_index`::
+(object)
+The _inverted index_ is enabled by the <<mapping-index,`index`>> mapping parameter and configured by setting the <<index-options,`index_options`>> for the field.
++
+.Properties of `inverted_index`:
+[%collapsible%open]
+====
+`terms`::
+(integer)
+Denotes the usages of _terms_ in the _inverted index_, answering the question "Is this field's inverted index used?".
+
+`postings`::
+(integer)
+Denotes the usage of the _posting list_ which contains the document ids for a given term.
+
+`proximity`::
+(integer)
+Denotes any kind of usage of either _positions_, _offsets_ or _payloads_ in the _inverted index_
+such that any usage is counted once for a given search request.
+
+`positions`::
+(integer)
+Denotes the usage of _position_ data (order of the term) in the _inverted index_.
+
+`term_frequencies`::
+(integer)
+Denotes the usage of the _term frequencies_ in the _inverted index_ which are used to calculate scores.
+
+`offsets`::
+(integer)
+Denotes the usage of the _offsets_ in the _inverted index_ which store the start and end character offsets of the terms.
+
+`payloads`::
+(integer)
+Denotes the usage of _payloads_ in the _inverted index_,
+e.g. via the <<analysis-delimited-payload-tokenfilter, delimited payload token filter>>, or by user-defined analysis components and plugins.
+
+====
+
+`stored_fields`::
+(integer)
+Denotes the usage of _stored fields_. These are enabled via the <<mapping-store,`store`>> mapping option,
+and accessed by specifying the <<stored-fields, `stored_fields`>> query option.
+Note that the <<mapping-source-field,`_source`>> and <<mapping-id-field, `_id`>> fields are stored by default and their usage is counted here.
+
+`doc_values`::
+(integer)
+Denotes the usage of _doc values_, which are primarily used for sorting and aggregations. These are enabled via the <<doc-values,`doc_values`>> mapping parameter.
+
+`points`::
+(integer)
+Denotes the usage of the Lucene _PointValues_ which are the basis of most numeric _field data types_, including <<spatial_datatypes, spacial data types>>, <<number,numbers>>, <<_core_datatypes,dates>>, and more.
+These are used by queries/aggregations for ranges, counts, bucketing, min/max, histograms, spacial, etc.
+
+`norms`::
+(integer)
+Denotes the usage of <<norms,_norms_>> which contain index-time boost values used for scoring.
+
+`term_vectors`::
+(integer)
+Denotes the usage of <<term-vector,_term vectors_>> which allow for a document's terms to be retrieved at search time.
+Usages include <<highlighting,highlighting>> and the <<query-dsl-mlt-query,More Like This Query>>.
+
+`knn_vectors`::
+(integer)
+Denotes the usage of the <<dense-vector,_knn_vectors_>> field type,
+primarily used for <<knn-search,k-nearest neighbor (kNN) search>>.
+
 [[field-usage-stats-api-example]]
 ==== {api-examples-title}
 
@@ -113,12 +192,12 @@ The API returns the following response:
                     "relocating_node": null
                 },
                 "stats" : {
-                    "all_fields": {
-                        "any": "6", <1>
+                    "all_fields": { <1>
+                        "any": "6",
                         "inverted_index": {
                             "terms" : 1,
                             "postings" : 1,
-                            "proximity" : 1, <2>
+                            "proximity" : 1,
                             "positions" : 0,
                             "term_frequencies" : 1,
                             "offsets" : 0,
@@ -132,7 +211,7 @@ The API returns the following response:
                         "knn_vectors" : 0
                     },
                     "fields": {
-                        "_id": {
+                        "_id": { <2>
                             "any" : 1,
                             "inverted_index": {
                                 "terms" : 1,
@@ -163,7 +242,5 @@ The API returns the following response:
 // TESTRESPONSE[s/: \{\.\.\.\}/: $body.$_path/]
 // TESTRESPONSE[s/: (\-)?[0-9]+/: $body.$_path/]
 // TESTRESPONSE[s/: "[^"]*"/: $body.$_path/]
-<1> denotes any kind of use of the field, either inverted index,
-    or stored fields, or doc values, etc.
-<2> denotes any kind of use of either positions, offsets or
-    payloads.
+<1> Reports the sums of the usage-counts for all fields in the index (on the listed shard).
+<2> The field name for which the following usage-counts are reported (on the listed shard).