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

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

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

  * <<mapping-index-field,`_index`>>: the index to which the document belongs.
  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>>.

To enable the access to these fields, the <<esql-from,`FROM`>> source command needs
to be provided with a dedicated directive:

[source,esql]
----
FROM index [METADATA _index, _id]
----

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:

[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]
|===

Also, similar to the index fields, once an aggregation is performed, a
metadata field will no longer be accessible to subsequent commands, unless
used as 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]
|===