Create or update an ES|QL view

PUT /_query/view/{name}

Auth

Stores an ES|QL query that runs whenever the view is referenced. A query that cannot be parsed is rejected. Replacing a reserved view fails.

Define reusable queries with ES|QL views

Required privileges

Index privileges create_view

Path parameters

name string required: The view name to create or update.

Query parameters

validate boolean · default: false

Whether to analyze the view query and return a warning when validation fails.

Validation reports an unknown index or column, including an index the caller cannot read. The view is saved even when validation reports a problem. Failures unrelated to the query, such as an overloaded cluster, produce no warning.

Request body

query string required: The ES|QL query string that defines the view. A query that cannot be parsed is rejected.
description string The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.: A free-text description of the view.

Response

application/json

acknowledged boolean required: For a successful response, this value is always true. On failure, an exception is returned instead.

View as Markdown

Examples

Request Console 1 / 7 languages

Create a view that normalizes country names and counts addresses by country.

Console Kibana Dev Tools

PUT /_query/view/country_addresses
{
  "query": """
    FROM addresses
    | RENAME city.country.name AS country
    | EVAL country = CASE(country == "United States of America", "United States", country)
    | STATS count=COUNT() BY country
  """,
  "description": "Address counts by country"
}

JavaScript Elasticsearch JavaScript Client

const response = await client.esql.putView({
  name: "country_addresses",
  query:
    '\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == "United States of America", "United States", country)\n    | STATS count=COUNT() BY country\n  ',
  description: "Address counts by country",
});

Python Elasticsearch Python Client

resp = client.esql.put_view(
    name="country_addresses",
    query="\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \"United States of America\", \"United States\", country)\n    | STATS count=COUNT() BY country\n  ",
    description="Address counts by country",
)

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_query/view/country_addresses" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \u0022United States of America\u0022, \u0022United States\u0022, country)\n    | STATS count=COUNT() BY country\n  ",
    "description": "Address counts by country"
  }'

C# Elasticsearch .NET Client

var response = await client.Esql
    .PutViewAsync(name: "country_addresses", d1 => d1
        .Description("Address counts by country")
        .Query("\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \"United States of America\", \"United States\", country)\n    | STATS count=COUNT() BY country\n  ")
    );

PHP Elasticsearch PHP Client

$resp = $client->esql()->putView([
    "name" => "country_addresses",
    "body" => [
        "query" => "\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \"United States of America\", \"United States\", country)\n    | STATS count=COUNT() BY country\n  ",
        "description" => "Address counts by country",
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.esql.put_view(
  name: "country_addresses",
  body: {
    "query": "\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \"United States of America\", \"United States\", country)\n    | STATS count=COUNT() BY country\n  ",
    "description": "Address counts by country"
  }
)

Response

The view definition was stored successfully.

{
  "acknowledged": true
}

Request Console 1 / 7 languages

Analyze the view query before saving it. When the query uses an unknown index or column, the response includes a warning and the view is still saved.

Console Kibana Dev Tools

PUT /_query/view/country_addresses?validate=true
{
  "query": """
    FROM addresses
    | RENAME city.country.name AS country
    | EVAL country = CASE(country == "United States of America", "United States", country)
    | STATS count=COUNT() BY country
  """,
  "description": "Address counts by country"
}

JavaScript Elasticsearch JavaScript Client

const response = await client.esql.putView({
  name: "country_addresses",
  validate: "true",
  query:
    '\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == "United States of America", "United States", country)\n    | STATS count=COUNT() BY country\n  ',
  description: "Address counts by country",
});

Python Elasticsearch Python Client

resp = client.esql.put_view(
    name="country_addresses",
    validate=True,
    query="\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \"United States of America\", \"United States\", country)\n    | STATS count=COUNT() BY country\n  ",
    description="Address counts by country",
)

curl Shell

curl -X PUT "$ELASTICSEARCH_URL/_query/view/country_addresses?validate=true" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \u0022United States of America\u0022, \u0022United States\u0022, country)\n    | STATS count=COUNT() BY country\n  ",
    "description": "Address counts by country"
  }'

C# Elasticsearch .NET Client

var response = await client.Esql
    .PutViewAsync(name: "country_addresses", d1 => d1
        .Validate(true)
        .Description("Address counts by country")
        .Query("\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \"United States of America\", \"United States\", country)\n    | STATS count=COUNT() BY country\n  ")
    );

PHP Elasticsearch PHP Client

$resp = $client->esql()->putView([
    "name" => "country_addresses",
    "validate" => "true",
    "body" => [
        "query" => "\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \"United States of America\", \"United States\", country)\n    | STATS count=COUNT() BY country\n  ",
        "description" => "Address counts by country",
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.esql.put_view(
  name: "country_addresses",
  validate: "true",
  body: {
    "query": "\n    FROM addresses\n    | RENAME city.country.name AS country\n    | EVAL country = CASE(country == \"United States of America\", \"United States\", country)\n    | STATS count=COUNT() BY country\n  ",
    "description": "Address counts by country"
  }
)

Response

The view definition was stored successfully.

{
  "acknowledged": true
}