Define reusable queries with ES|QL views

A view is a virtual index defined by an ES|QL query. You reference a view by name in the FROM command, just like an ordinary index. The query runs each time the view is referenced, so results always reflect the current state of the data.

A view has two components:

• Name: unique within the index namespace, used anywhere an index name is accepted in FROM.
• Definition: a complete ES|QL query that runs each time the view is referenced.

Here's how a view works in practice:

Views are a good fit when you want to:

• Reuse a named query. Wrap a frequently used ES|QL pipeline as a view and reference it by name, instead of repeating the same query in every request.
• Abstract common transformations. Centralize renames, type conversions, or derived fields so consumers see a consistent set of columns without needing to know the underlying source structure.
• Combine pre-processed data sources. Define one view per source, each with its own filters or aggregations, and query them together in a single FROM clause.
• Simplify queries for downstream tools. Dashboards, alerts, or ad-hoc analysts can query FROM my_view without needing to know the indices or processing commands behind it.

Use the REST API to create, update, delete, and list views:

• Create or update a view
• Delete a view
• Get or list views

PUT /_query/view/<name> rejects a query that cannot be parsed.

To check the query without running it, set the validate query parameter to true. Validation is off by default.

With validate=true:

• If the query uses an index or column that does not exist, the response carries a Warning header.
• A warning does not stop Elasticsearch from saving the view. The view is saved whether or not validation reports a problem, so you can create a view before the index it reads from.
• The analysis uses your privileges. An index you cannot read is reported as unknown.
• Failures unrelated to the query, such as an overloaded cluster, produce no warning.

Some views are reserved. Elasticsearch or its components create them, not users. A reserved view is marked with "reserved": true in the get view response.

You cannot modify or delete a reserved view through the REST API:

• PUT /_query/view/<name> fails if a reserved view with that name exists. You also cannot set reserved in a request.
• DELETE /_query/view/<name> fails with cannot delete reserved view [<name>].

You can query and read a reserved view like any other view, subject to the same privileges.

Use views as if they were ordinary indices:

FROM index_pattern
		

Where index_pattern is a comma-separated list of index or view names. Index expressions can include wildcards and date math. Whether a wildcard also matches views depends on the version and deployment type.

SET wildcards_match_views = true;
FROM my-view-*
		

View operations use the standard Elasticsearch index privileges, applied to the view name.

read on a view name permits querying the view but does not grant access to the data behind it. The caller must also have read on every index or alias the view definition resolves to, including through nested views.

Access is enforced at query time. Creating a view requires no privilege over the indices it references.

If some underlying indices are unauthorized, the query fails with a 403. If none are accessible, it fails with a 400 Unknown index. Wildcard patterns (FROM view-*) silently exclude unauthorized views.

Nested views are resolved under the calling user's credentials. Access to an outer view does not grant access to any inner view it references.

read on a view name must not carry DLS or FLS. If it does, the query fails with a 403 and the views_with_dls_or_fls error field lists the affected names. This applies at every nesting level.

DLS or FLS on the underlying indices is applied normally.

{
  "indices": [
    {
      "names": ["country_addresses"],
      "privileges": ["read", "create_view", "read_view_metadata", "delete_view"]
    },
    {
      "names": ["addresses"],
      "privileges": ["read"]
    }
  ]
}
		

The following examples show how to use views within the FROM command.

Assume we've defined three views in a similar way to the example above, each counting the number of documents that reference a particular country, but from three different source indices:

• country_airports - reports counts of documents per country from our airports index
• country_addresses - reports counts of documents per country from our addresses index
• country_languages - reports counts of documents per country from our languages index

Now we can query these together with a query like:

FROM country_addresses, country_airports, country_languages
| WHERE country LIKE "United*"
| SORT country ASC, count DESC
		

The same country might appear in multiple views, producing multiple rows. We could combine these with a STATS command, using SUM(count) BY country.

FROM country_*
| STATS count=SUM(count) BY country
| WHERE count > 11
| SORT count DESC, country ASC
		

Note how we used SUM to combine the counts of the three previously aggregated count columns.

We can define views with complex queries, including commands like LOOKUP JOIN:

				PUT /_query/view/airports_mp_filtered
					{
    "query": """
        FROM airports
        | RENAME abbrev AS code
        | LOOKUP JOIN airports_mp ON abbrev == code
        | WHERE abbrev IS NOT NULL
        | DROP code
       """
}
		

This creates a view called airports_mp_filtered that contains all rows from the airports index that also have a matching abbrev inside the airports_mp index. This is effectively a subset of the airports index.

We could, for example, see how many airports are defined only in airports versus how many are defined in the view, by combining both a view and an index in the same FROM command:

FROM airports_mp_filtered, airports
| STATS duplications=COUNT() BY abbrev
| STATS count=COUNT() BY duplications
| SORT count DESC
		

The METADATA directive is supported both inside and outside a view. Views follow the same rules as subqueries.

Inside the view, the directive generates columns just like other fields. You can use them for filtering and as output columns.

Except for _class and _name, an outer METADATA request returns null when the source output does not contain the requested field. When the source retains a metadata field in its output, the outer query receives its values even if it does not request that field with METADATA.

_class and _name are the only metadata fields that work on a view without the view body declaring them. The outer query answers them for each view. _class is view. _name is the view name. You do not need the directive inside the view. If the view body also declares _class or _name, the outer values replace them.

FROM airports_mp_filtered, airports METADATA _class, _name
| WHERE abbrev == "LUH"
| KEEP abbrev, _class, _name
| SORT _name
		

Views behave like inline subqueries at execution time and when you start combining multiple views, it helps to know how nesting works and where the limits are.

When a query references one or more views, each view's definition query executes independently at query time, in parallel where possible. This is the same execution model used by FROM subqueries and FORK.

Results from all sources (indices, views, subqueries) are unioned into a single result set. Duplicate rows are preserved. Columns that exist in one source but not another are filled with null.

A view definition can reference another view. This is called a nested view. ES|QL allows nesting to a depth of 10.

When multiple views are referenced within the same index pattern, each view executes independently (in parallel if possible), similar to subqueries and FORK.

When a view definition contains branches, such as subqueries or references to other views, query compaction tries to flatten the inner branches into the outer branch set.

The following example shows how compaction works. Two views are each defined as a pair of subqueries:

				PUT /_query/view/view_x
					{
    "query": """
        FROM (
            FROM app-events-* | KEEP msg, level
        ), (
            FROM auth-events-* | KEEP msg, level
        )
       """
}
		

				PUT /_query/view/view_y
					{
    "query": """
        FROM (
            FROM nginx-events-* | KEEP msg, level
        ), (
            FROM apache-events-* | KEEP msg, level
        )
       """
}
		

A query references both views alongside a regular index:

FROM other-events, view_x, view_y
| STATS count(msg) BY level
		

Without compaction, this would create two levels of branching. Three outer branches exist, and two of them branch again inside their view definitions:

Compaction flattens the inner view branches into the outer branch set, producing a single-level plan with five branches:

Compaction doesn't apply if the view definition contains processing commands after its subqueries. Those commands must run on the combined branch output, so the branch level can't be collapsed.

ES|QL views have the following limitations:

A role entry that grants read on a view name must not carry DLS or FLS restrictions. If it does, the query fails with a 403. DLS/FLS on the underlying indices is applied normally. Refer to view privileges.

Views may be nested up to depth 10.

Views can reference remote indices in cross-cluster search, but you can't query a view that is defined on a remote cluster.

Views are available in serverless and cross-project search, but with some limitations:

• You can define views in both origin and linked projects.
• CPS resolves index expressions against indices in every project that the expression targets, but it resolves views only in the origin project. Views in linked projects are invisible to the query, including through qualified expressions such as FROM linked-project:view.
• CPS uses the same resolution process for index expressions in the top-level query and inside view definitions.
• An unqualified index expression can match a view in the origin project and indices in linked projects. CPS returns results from both.

				PUT /_query/view/sales_by_region
					{
  "query": "FROM sales | STATS total = COUNT(*) BY region"
}
		

				POST /_query
					{
  "query": "FROM sales_by_region | KEEP region, total | LIMIT 1000",
  "filter": {
    "bool": {
      "should": [
        { "term": { "region": "eu" } },
        { "term": { "total": 3 } }
      ],
      "minimum_should_match": 2
    }
  }
}
		

The request filter could not be fully applied to view(s); the following Query DSL constructs are not supported and were skipped: [bool[minimum_should_match=2]] on view [sales_by_region]. Use a WHERE clause to filter rows from views instead
		

A view definition can read from index aliases and data streams. An alias cannot point to a view.

An Elasticsearch transform is not an ES|QL source. To query transform results from a view, use the transform's destination index as the source in the view definition.

A view definition can read from a dataset, which ES|QL Data Federation uses to query external data.

A wildcard in the view definition matches datasets only when the view definition sets wildcards_match_datasets to true.

Query parameters are not allowed in a stored view definition. A calling query can still use parameters in commands after FROM view_name, but those parameters are not substituted into the view body.

A view that starts with TS must also contain a STATS command after it. A view without STATS is rejected when you create or update it. This ensures the view returns plain tabular results. A PROMQL view must also use an aggregation function.

Query a time series view with FROM view_name. A view name cannot be used as a source in TS or PROMQL. An exact view name in one of those source commands is rejected, and a wildcard source expression skips matching views.

When you create or update a view, Elasticsearch validates its name, size, query syntax, and the settings that are allowed in a view definition.

For a time series view, Elasticsearch also validates that TS is followed by STATS.

Elasticsearch doesn't resolve or execute the query, and it doesn't check whether referenced indices, fields, datasets, or views exist, or whether nested views form a cycle. Creation doesn't return warnings for those problems. Elasticsearch reports them when you query the view.

Deleting a resource doesn't check whether a view depends on it. Deleting an index, data stream, alias, dataset, or nested view can therefore cause existing views to fail when queried.

For a detailed comparison of views, subqueries, and FORK, refer to Combine and reuse ES|QL queries.

• ES|QL subqueries: nest queries inside other queries, in FROM or with IN / NOT IN.
• FROM command: full reference for index expressions, where view names are used.
• Query multiple indices: how index patterns, wildcards, and date math combine sources in a single FROM.