Browse Source

[DOCS][ESQL] Document _source metadata field (#105237)

* [DOCS][ESQL] Document _source metadata field

* 🚗 Minor copyedit to entire page
Liam Thompson 1 year ago
parent
commit
fb743da0d7
1 changed files with 16 additions and 10 deletions
  1. 16 10
      docs/reference/esql/metadata-fields.asciidoc

+ 16 - 10
docs/reference/esql/metadata-fields.asciidoc

@@ -5,10 +5,10 @@
 <titleabbrev>Metadata fields</titleabbrev>
 ++++
 
-{esql} can access <<mapping-fields, metadata fields>>. The currently
-supported ones are:
+{esql} can access <<mapping-fields, metadata fields>>. The following are currently
+supported:
 
-  * <<mapping-index-field,`_index`>>: the index to which the document belongs.
+  * <<mapping-index-field,`_index`>>: the index the document belongs to.
   The field is of the type <<keyword, keyword>>.
 
   * <<mapping-id-field,`_id`>>: the source document's ID. The field is of the
@@ -17,20 +17,26 @@ supported ones are:
   * `_version`: the source document's version. The field is of the type
   <<number,long>>.
 
-To enable the access to these fields, the <<esql-from,`FROM`>> source command needs
-to be provided with a dedicated directive:
+   * <<mapping-source-field,`_source`>>: the original JSON document body 
+  that was passed at index time (or a reconstructed version if 
+  <<synthetic-source, synthetic `_source_`>> is enabled). The field is 
+  loaded as a special `_source` type. This field is not supported by 
+  functions.
+
+To enable access to these fields, the <<esql-from,`FROM`>> source command 
+requires a dedicated directive:
 
 [source,esql]
 ----
-FROM index [METADATA _index, _id]
+FROM index [METADATA _index, _id, _source]
 ----
 
 Metadata fields are only available if the source of the data is an index.
 Consequently, `FROM` is the only source commands that supports the `METADATA`
 directive.
 
-Once enabled, the fields are then available to subsequent processing commands, just
-like the other index fields:
+Once enabled, these fields will be available to subsequent processing commands, just
+like other index fields:
 
 [source.merge.styled,esql]
 ----
@@ -41,9 +47,9 @@ include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=multipleIndices]
 include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=multipleIndices-result]
 |===
 
-Also, similar to the index fields, once an aggregation is performed, a
+Similar to index fields, once an aggregation is performed, a
 metadata field will no longer be accessible to subsequent commands, unless
-used as grouping field:
+used as a grouping field:
 
 [source.merge.styled,esql]
 ----