---
title: stack es delete-by-query cli command
description: Delete documents. Behaviour flags: --dry-run — validate all inputs and exit without performing any action 
url: https://www.elastic.co/elastic/docs-builder/docs/4116/reference/elastic-cli/cli/stack/es/delete-by-query
applies_to:
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Preview
---

# stack es delete-by-query cli command
<cli-modifiers>
</cli-modifiers>

```bash
elastic stack es delete-by-query --index <index> [options]
```

Delete documents.
**Behaviour flags:**
`--dry-run` — validate all inputs and exit without performing any action

## Options

<definitions>
  <definition term="--index string required">
    A comma-separated list of data streams, indices, and aliases to search.
    It supports wildcards (`*`).
    To search all data streams or indices, omit this parameter or use `*` or `_all`.
    **Repeatable:** pass `--index` multiple times to supply more than one value
  </definition>
  <definition term="--allow-no-indices">
    A setting that does two separate checks on the index expression.
    If `false`, the request returns an error (1) if any wildcard expression
    (including `_all` and `*`) resolves to zero matching indices or (2) if the
    complete set of resolved indices, aliases or data streams is empty after all
    expressions are evaluated. If `true`, index expressions that resolve to no
    indices are allowed and the request returns an empty result.
  </definition>
  <definition term="--analyzer string">
    Analyzer to use for the query string.
    This parameter can be used only when the `q` query string parameter is specified.
  </definition>
  <definition term="--analyze-wildcard">
    If `true`, wildcard and prefix queries are analyzed.
    This parameter can be used only when the `q` query string parameter is specified.
  </definition>
  <definition term="--conflicts enum">
    What to do if delete by query hits version conflicts: `abort` or `proceed`.
    **Values:** abort, proceed
  </definition>
  <definition term="--default-operator enum">
    The default operator for query string query: `and` or `or`.
    This parameter can be used only when the `q` query string parameter is specified.
    **Values:** and, or
  </definition>
  <definition term="--df string">
    The field to use as default where no field prefix is given in the query string.
    This parameter can be used only when the `q` query string parameter is specified.
  </definition>
  <definition term="--expand-wildcards enum">
    The type of index that wildcard patterns can match.
    If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
    It supports comma-separated values, such as `open,hidden`.
    **Values:** all, open, closed, hidden, none
    **Repeatable:** pass `--expand-wildcards` multiple times to supply more than one value
  </definition>
  <definition term="--from number">
    Skips the specified number of documents.
  </definition>
  <definition term="--ignore-unavailable">
    If `false`, the request returns an error if it targets a concrete (non-wildcarded)
    index, alias, or data stream that is missing, closed, or otherwise unavailable.
    If `true`, unavailable concrete targets are silently ignored.
  </definition>
  <definition term="--lenient">
    If `true`, format-based query failures (such as providing text to a numeric field) in the query string will be ignored.
    This parameter can be used only when the `q` query string parameter is specified.
  </definition>
  <definition term="--max-docs number">
    The maximum number of documents to delete.
  </definition>
  <definition term="--preference string">
    The node or shard the operation should be performed on.
    It is random by default.
  </definition>
  <definition term="--refresh">
    If `true`, Elasticsearch refreshes all shards involved in the delete by query after the request completes.
    This is different than the delete API's `refresh` parameter, which causes just the shard that received the delete request to be refreshed.
    Unlike the delete API, it does not support `wait_for`.
  </definition>
  <definition term="--request-cache">
    If `true`, the request cache is used for this request.
    Defaults to the index-level setting.
  </definition>
  <definition term="--requests-per-second number">
    The maximum number of documents to delete per second, across the entire delete-by-query operation (including slices).
    It can be either `-1` to turn off throttling or any decimal number like `1.7` or `12` to throttle to that level.
  </definition>
  <definition term="--routing string">
    A custom value used to route operations to a specific shard.
    Not allowed when `index.slice.enabled` is `true` for the target index; use `_slice` instead.
    **Repeatable:** pass `--routing` multiple times to supply more than one value
  </definition>
  <definition term="--q string">
    A query in the Lucene query string syntax.
  </definition>
  <definition term="--scroll string">
    The period to retain the search context for scrolling.
  </definition>
  <definition term="--scroll-size number">
    The size of the scroll request that powers the operation.
  </definition>
  <definition term="--search-timeout string">
    The explicit timeout for each search request.
    It defaults to no timeout.
  </definition>
  <definition term="--search-type enum">
    The type of the search operation.
    Available options include `query_then_fetch` and `dfs_query_then_fetch`.
    **Values:** query_then_fetch, dfs_query_then_fetch
  </definition>
  <definition term="--slices string">
    The number of slices this task should be divided into.
  </definition>
  <definition term="--sort string">
    A sort object that specifies the order of deleted documents.
    **Repeatable:** pass `--sort` multiple times to supply more than one value
  </definition>
  <definition term="--stats string[]">
    The specific `tag` of the request for logging and statistical purposes.
    **Repeatable:** pass `--stats` multiple times to supply more than one value
  </definition>
  <definition term="--terminate-after number">
    The maximum number of documents to collect for each shard.
    If a query reaches this limit, Elasticsearch terminates the query early.
    Elasticsearch collects documents before sorting. Use with caution.
    Elasticsearch applies this parameter to each shard handling the request.
    When possible, let Elasticsearch perform early termination automatically.
    Avoid specifying this parameter for requests that target data streams with backing indices across multiple data tiers.
  </definition>
  <definition term="--timeout string">
    The period each deletion request waits for active shards.
  </definition>
  <definition term="--version">
    If `true`, returns the document version as part of a hit.
  </definition>
  <definition term="--wait-for-active-shards string">
    The number of shard copies that must be active before proceeding with the operation.
    Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).
    The `timeout` value controls how long each write request waits for unavailable shards to become available.
  </definition>
  <definition term="--wait-for-completion">
    If `true`, the request blocks until the operation is complete.
    If `false`, Elasticsearch performs some preflight checks, launches the request, and returns a task you can use to cancel or get the status of the task. Elasticsearch creates a record of this task as a document at `.tasks/task/${taskId}`. When you are done with a task, you should delete the task document so Elasticsearch can reclaim the space.
  </definition>
  <definition term="--query string">
    The documents to delete specified with Query DSL.
  </definition>
  <definition term="--slice string">
    Slice the request manually using the provided slice ID and total number of slices.
  </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>