---
title: stack es esql query cli command
description: Run an ES|QL query. Behaviour flags: --dry-run — validate all inputs and exit without performing any action 
url: https://www.elastic.co/elastic/docs-builder/docs/4118/reference/elastic-cli/cli/stack/es/esql/query
applies_to:
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Preview
---

# stack es esql query cli command
<cli-modifiers>
</cli-modifiers>

```bash
elastic stack es esql query --query <query> [options]
```

Run an ES|QL query.
**Behaviour flags:**
`--dry-run` — validate all inputs and exit without performing any action

## Options

<definitions>
  <definition term="--query string required">
    The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.
  </definition>
  <definition term="--format enum">
    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
  </definition>
  <definition term="--delimiter string">
    The character to use between values within a CSV row. Only valid for the CSV format.
  </definition>
  <definition term="--drop-null-columns">
    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.
  </definition>
  <definition term="--allow-partial-results">
    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`.
  </definition>
  <definition term="--columnar">
    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.
  </definition>
  <definition term="--filter string">
    Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on.
  </definition>
  <definition term="--time-zone string">
    Sets the default timezone of the query.
  </definition>
  <definition term="--locale string">
    Returns results (especially dates) formatted per the conventions of the locale.
  </definition>
  <definition term="--params string">
    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.
    **Repeatable:** pass `--params` multiple times to supply more than one value
  </definition>
  <definition term="--profile">
    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.
  </definition>
  <definition term="--tables string">
    Tables to use with the LOOKUP operation. The top level key is the table
    name and the next level key is the column name.
  </definition>
  <definition term="--include-ccs-metadata">
    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.
  </definition>
  <definition term="--include-execution-metadata">
    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
  </definition>
  <definition term="--settings string">
    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.
  </definition>
  <definition term="--error-trace">
    When set to `true` Elasticsearch will include the full stack trace of errors
    when they occur.
  </definition>
  <definition term="--filter-path string">
    Comma-separated list of filters in dot notation which reduce the response
    returned by Elasticsearch.
    **Repeatable:** pass `--filter-path` multiple times to supply more than one value
  </definition>
  <definition term="--human">
    When set to `true` will return statistics in a format suitable for humans.
    For example `"exists_time": "1h"` for humans and
    `"exists_time_in_millis": 3600000` for computers. When disabled the human
    readable values will be omitted. This makes sense for responses being consumed
    only by machines.
  </definition>
  <definition term="--pretty">
    If set to `true` the returned JSON will be "pretty-formatted". Only use
    this option for debugging only.
  </definition>
  <definition term="--input-file string">
    path to a JSON file to use as command input
  </definition>
  <definition term="--dry-run">
    validate all inputs and exit without performing any action (preview changes without applying them)
  </definition>
</definitions>


## Global Options

<definitions>
  <definition term="--json">
    output as JSON
  </definition>
</definitions>