---
type: api
title: Run an ES|QL query
description: Get search results for an ES|QL (Elasticsearch query language) query.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-esql-query
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-esql-query
products:
  - Elasticsearch
---

# Run an ES|QL query

Availability: 8.11+

## Paths

- `POST` `/_query`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#bearerauth)

## Description

Get search results for an ES|QL (Elasticsearch query language) query.

## Required authorization

* Index privileges: `read`

[More about ES|QL reference](https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql)

## Query String Parameters

- `format` (enum EsqlFormat)
  A short version of the Accept header, e.g. json, yaml.

`csv`, `tsv`, and `txt` formats will return results in a tabular format, excluding other metadata fields from the response.
  Values: `csv`, `json`, `tsv`, `txt`, `yaml`, `cbor`, `smile`, `arrow`
- `delimiter` (string · default: ,)
  The character to use between values within a CSV row. Only valid for the CSV format.
- `drop_null_columns` (boolean · default: false)
  Should columns that are entirely `null` be removed from the `columns` and `values` portion of the results?
Defaults to `false`. If `true` then the response will include an extra section under the name `all_columns` which has the name of all columns.
- `allow_partial_results` (boolean · default: true)
  If `true`, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards.
If `false`, the query will fail if there are any failures.

To override the default behavior, you can set the `esql.query.allow_partial_results` cluster setting to `false`.

## Request Body

`application/json`

- `columnar` (boolean) — optional
  By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.
- `filter` ({} QueryContainer) — optional
  Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on.
  See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/types/_types-query_dsl-querycontainer)
- `time_zone` (string) — optional
  Sets the default timezone of the query.
- `locale` (string) — optional
  Returns results (especially dates) formatted per the conventions of the locale.
- `params` (ESQLParams) — optional
  To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.
- `profile` (boolean) — optional
  If provided and `true` the response will include an extra `profile` object
with information on how the query was executed. This information is for human debugging
and its format can change at any time but it can give some insight into the performance
of each part of the query.
- `query` (string) — required
  The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
- `tables` (map string to string to TableValuesContainer) — optional
  Tables to use with the LOOKUP operation. The top level key is the table
name and the next level key is the column name.
- `include_ccs_metadata` (boolean · default: false) — optional
  When set to `true` and performing a cross-cluster/cross-project query, the response will include an extra `_clusters`
object with information about the clusters that participated in the search along with info such as shards
count.
- `include_execution_metadata` (boolean · default: false) — optional
  When set to `true`, the response will include an extra `_clusters`
object with information about the clusters that participated in the search along with info such as shards
count.
This is similar to `include_ccs_metadata`, but it also returns metadata when the query is not CCS/CPS
- `settings` ({} EsqlQuerySettings) — optional
  Per-query settings, the request-body equivalent of the in-query `SET` command.
For example, `time_zone` can be supplied here instead of as a top-level field.
  - `time_zone` (string) — optional
    The default timezone to be used in the query.
It defaults to UTC and overrides the `time_zone` request parameter.
  - `approximation` (EsqlApproximation) — optional
    Enables query approximation if possible for the query.
`false` (the default) disables query approximation and `true` enables it with default settings.
A map value enables query approximation with custom settings.
  - `column_metadata` (boolean | string Stringifiedboolean · default: false) — optional
    When enabled, column metadata is added to the query response as additional `_meta` properties.
Currently, only `_meta.bucket` is added for columns corresponding to the `BUCKET` function, containing the bucket interval and unit for queries where it can be determined.

## Response

`application/json`

- `took` (DurationValueUnitMillis)
- `is_partial` (boolean)
- `all_columns` ([] EsqlColumnInfo)
  - `name` (string)
  - `type` (string)
- `columns` ([] EsqlColumnInfo)
  - `name` (string)
  - `type` (string)
- `values` ([] union FieldValue)
  One of: `number` or `string` or `boolean`
- `_clusters` ({} EsqlClusterInfo)
  Cross-cluster search information. Present if `include_ccs_metadata` was `true` in the request
and a cross-cluster search was performed.
  - `total` (number)
  - `successful` (number)
  - `running` (number)
  - `skipped` (number)
  - `partial` (number)
  - `failed` (number)
  - `details` (map string to EsqlClusterDetails)
    Map values ({} EsqlClusterDetails)
    - `status` (enum EsqlClusterStatus)
      Values: `running`, `successful`, `partial`, `skipped`, `failed`
    - `indices` (string)
    - `took` (DurationValueUnitMillis)
    - `_shards` ({} EsqlShardInfo)
      - `total` (number)
      - `successful` (number)
      - `skipped` (number)
      - `failed` (number)
    - `failures` ([] EsqlShardFailure)
      - `shard` (number)
      - `index` (union IndexName | string) — nullable
      - `node` (string)
      - `reason` ({} ErrorCause)
        - `type` (string)
          The type of error
        - `reason` (union string) — nullable
          A human-readable explanation of the error, in English.
          One of: `string`
        - `stack_trace` (string)
          The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
        - `caused_by` ({} ErrorCause) — recursive
          Same fields as `reason` in `failures`
        - `root_cause` ([] ErrorCause) — recursive
          Same fields as `reason` in `failures`
        - `suppressed` ([] ErrorCause) — recursive
          Same fields as `reason` in `failures`
- `profile` (object)
  Profiling information. Present if `profile` was `true` in the request.
The contents of this field are currently unstable.
## Code Examples

#### Console

```console
POST /_query
{
  "query": """
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  """,
  "include_ccs_metadata": true
}
```

#### JavaScript

```javascript
const response = await client.esql.query({
  query:
    "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
  include_ccs_metadata: true,
});
```

#### Python

```python
resp = client.esql.query(
    query="\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    include_ccs_metadata=True,
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/_query" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    "include_ccs_metadata": true
  }'
```

#### Java

```java
client.esql().query(q -> q
    .includeCcsMetadata(true)
    .query("""
        
    FROM library,remote-*:library
    | EVAL year = DATE_TRUNC(1 YEARS, release_date)
    | STATS MAX(page_count) BY year
    | SORT year
    | LIMIT 5
  
        """)
);
```

#### C#

```c#
var response = await client.Esql
    .QueryAsync(d1 => d1
        .IncludeCcsMetadata(true)
        .Query("\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ")
    );
```

#### PHP

```php
$resp = $client->esql()->query([
    "body" => [
        "query" => "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
        "include_ccs_metadata" => true,
    ],
]);
```

#### Ruby

```ruby
response = client.esql.query(
  body: {
    "query": "\n    FROM library,remote-*:library\n    | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n    | STATS MAX(page_count) BY year\n    | SORT year\n    | LIMIT 5\n  ",
    "include_ccs_metadata": true
  }
)
```