---
title: ES|QL metadata fields
description: ES|QL can access metadata fields. To access these fields, use the METADATA directive with the FROM source command. For example: The following fields identify...
url: https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/query-languages/esql/esql-metadata-fields
products:
- Elasticsearch
applies_to:
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Generally available
---
# ES|QL metadata fields
ES|QL can access [metadata fields](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/document-metadata-fields).
To access these fields, use the `METADATA` directive with the [`FROM`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/query-languages/esql/commands/from) source command. For example:
```esql
FROM index METADATA _index, _id
```
## Available metadata fields
### Source metadata fields
- Elastic Stack: Planned
The following fields identify the source that produced each row:
| Metadata field | Type | Description |
|----------------|------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| `_class` | [keyword](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/keyword) | What kind of source the row came from: `index`, `view`, `subquery`, or `dataset`. |
| `_name` | [keyword](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/keyword) | What the source is called: the index name on an index, the view name on a view, `null` on a subquery, and the dataset name on a dataset. |
### Index metadata fields
The following fields describe index and document metadata:
| Metadata field | Type | Description |
|-----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`_id`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/mapping-id-field) | [keyword](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/keyword) | Unique document ID. |
| [`_ignored`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/mapping-ignored-field) | [keyword](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/keyword) | Names every field in a document that was ignored when the document was indexed. |
| [`_index`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/mapping-index-field) | [keyword](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/keyword) | Index name. |
| `_index_mode` | [keyword](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/keyword) | [Index mode](/elastic/elasticsearch/pull/162667/reference/elasticsearch/index-settings/index-modules#index-mode-setting). For example: `standard`, `lookup`, or `logsdb`. |
| `_score` | [`float`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/number) | Query relevance score (when enabled). Scores are updated when using [full text search functions](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/query-languages/esql/functions-operators/search-functions). |
| `_size` | [`integer`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/number) | Size in bytes of the original `_source` field when the [mapper-size plugin](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch-plugins/mapper-size) is enabled. |
| [`_source`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/mapping-source-field) | Special `_source` type | Original JSON document body passed at index time (or a reconstructed version if [synthetic `_source`](/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/mapping-source-field#synthetic-source) is enabled). |
| `_version` | [`long`](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/number) | Document version number |
## Usage and limitations
- Most index metadata fields are available only for index sources. When a field is unavailable for a given source, its value is `null`. For source-specific behavior, refer to [views](/elastic/elasticsearch/pull/162667/reference/query-languages/esql/esql-views#views-with-metadata), [subqueries](/elastic/elasticsearch/pull/162667/reference/query-languages/esql/esql-from-subquery#subqueries-with-metadata), and [datasets](/elastic/elasticsearch/pull/162667/reference/query-languages/esql/esql-data-federation-querying#use-metadata-columns).
- The `_source` type is not supported by functions
- Only the `FROM` command supports the `METADATA` directive
- Once enabled, metadata fields work like regular index fields
## Examples
### Basic metadata usage
Once enabled, metadata fields are available to subsequent processing commands, just like other index fields:
```esql
FROM ul_logs, apps METADATA _index, _version
| WHERE id IN (13, 14) AND _version == 1
| EVAL key = CONCAT(_index, "_", TO_STR(id))
| SORT id, _index
| KEEP id, _index, _version, key
```
| id:long | _index:keyword | _version:long | key:keyword |
|---------|----------------|---------------|-------------|
| 13 | apps | 1 | apps_13 |
| 13 | ul_logs | 1 | ul_logs_13 |
| 14 | apps | 1 | apps_14 |
| 14 | ul_logs | 1 | ul_logs_14 |
### Metadata fields and aggregations
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:
```esql
FROM employees METADATA _index, _id
| STATS max = MAX(emp_no) BY _index
```
| max:integer | _index:keyword |
|-------------|----------------|
| 10100 | employees |
### Sort results by search score
```esql
FROM products METADATA _score
| WHERE MATCH(description, "wireless headphones")
| SORT _score DESC
| KEEP name, description, _score
```
Refer to [ES|QL for search](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/solutions/search/esql-for-search#esql-for-search-scoring) for more information on relevance scoring and how to use `_score` in your queries.
### Scores across mixed sources
A [subquery](/elastic/elasticsearch/pull/162667/reference/query-languages/esql/esql-from-subquery#subqueries-with-metadata) or [view](/elastic/elasticsearch/pull/162667/reference/query-languages/esql/esql-views#views-with-metadata) returns `null` for `_score` when its output does not contain that field. This example combines rows from a subquery over `languages` with rows read directly from the same index:
```esql
FROM (FROM languages), languages METADATA _score
| WHERE MATCH(language_name, "English") OR MATCH(language_name, "French")
| SORT _score DESC NULLS LAST, language_code
| EVAL _score = ROUND(_score)
```
| language_code:integer | language_name:keyword | _score:double |
|-----------------------|-----------------------|---------------|
| 1 | English | 1.0 |
| 2 | French | 1.0 |
| 1 | English | null |
| 2 | French | null |
The `WHERE` filter applies to both sources. The index rows return a score from `MATCH`. The subquery rows return `null`, because the subquery does not produce `_score`.
### Retrieving _source
Using _`source` is useful when you want to retrieve most or all fields from a document.
You should consider retrieving `_source` instead of individual fields when:
- You need several fields from a document, and most of them are text fields.
- You have long text fields or geoshape fields in your documents.
- You want the original document instead of the indexed values for your fields.
- You have nested objects or arrays that you want to preserve in their original structure.
You might want to avoid retrieving `_source` when:
- Your fields are stored as [doc_values](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/doc-values). `doc_values` access is faster than _`source`.
- Your index uses [synthetic source](/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/mapping-source-field#synthetic-source). Accessing _`source` in synthetic source mode has a performance penalty.
- The text fields you need are [stored fields](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/pull/162667/reference/elasticsearch/mapping-reference/mapping-store).
Using `_source` or selecting fields are both valid options, but can have performance and data format implications that you should consider based on your use case.