elasticsearch/docs/reference/esql/metadata-fields.asciidoc

[[esql-metadata-fields]]
=== {esql} metadata fields

++++
<titleabbrev>Metadata fields</titleabbrev>
++++

{esql} can access <<mapping-fields, metadata fields>>. The following are currently
supported:

  * <<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
  type <<keyword, keyword>>.

  * `_version`: the source document's version. The field is of the type
  <<number,long>>.

   * <<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, _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, these fields will be available to subsequent processing commands, just
like other index fields:

[source.merge.styled,esql]
----
include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=multipleIndices]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=multipleIndices-result]
|===

Similar to index fields, once an aggregation is performed, a
metadata field will no longer be accessible to subsequent commands, unless
used as a grouping field:

[source.merge.styled,esql]
----
include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=metaIndexInAggs]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/metadata-IT_tests_only.csv-spec[tag=metaIndexInAggs-result]
|===