Delete by query

Introduced 1.0

You can include a query as part of your delete request so OpenSearch deletes all documents that match that query.

Example

  1. POST sample-index1/_delete_by_query
  2. {
  3. "query": {
  4. "match": {
  5. "movie-length": "124"
  6. }
  7. }
  8. }

Path and HTTP methods

  1. POST <index>/_delete_by_query

URL parameters

All URL parameters are optional.

ParameterTypeDescription
<index>StringName or list of the data streams, indices, or aliases to delete from. Supports wildcards. If left blank, OpenSearch searches all indices.
allow_no_indicesBooleanWhether to ignore wildcards that don’t match any indices. Default is true.
analyzerStringThe analyzer to use in the query string.
analyze_wildcardBooleanSpecifies whether to analyze wildcard and prefix queries. Default is false.
conflictsStringIndicates to OpenSearch what should happen if the delete by query operation runs into a version conflict. Valid options are abort and proceed. Default is abort.
default_operatorStringIndicates whether the default operator for a string query should be AND or OR. Default is OR.
dfStringThe default field in case a field prefix is not provided in the query string.
expand_wildcardsStringSpecifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are all (match any index), open (match open, non-hidden indices), closed (match closed, non-hidden indices), hidden (match hidden indices), and none (deny wildcard expressions). Default is open.
fromIntegerThe starting index to search from. Default is 0.
ignore_unavailableBooleanSpecifies whether to include missing or closed indices in the response. Default is false.
lenientBooleanSpecifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
max_docsIntegerHow many documents the delete by query operation should process at most. Default is all documents.
preferenceStringSpecifies which shard or node OpenSearch should perform the delete by query operation on.
qStringLucene query string’s query.
request_cacheBooleanSpecifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings.
refreshBooleanIf true, OpenSearch refreshes shards to make the delete by query operation available to search results. Valid options are true, false, and wait_for, which tells OpenSearch to wait for a refresh before executing the operation. Default is false.
requests_per_secondIntegerSpecifies the request’s throttling in sub-requests per second. Default is -1, which means no throttling.
routingStringValue used to route the operation to a specific shard.
scrollTimeAmount of time the search context should be open.
scroll_sizeIntegerSize of the operation’s scroll requests. Default is 1000.
search_typeStringWhether OpenSearch should use global term and document frequencies calculating revelance scores. Valid choices are query_then_fetch and dfs_query_then_fetch. query_then_fetch scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. dfs_query_then_fetch scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is query_then_fetch.
search_timeoutTimeHow long to wait until OpenSearch deems the request timed out. Default is no timeout.
slicesString or IntegerHow many slices to cut the operation into for faster processing. Specify an integer to set how many slices to divide the operation into, or use auto, which tells OpenSearch it should decide how many slices to divide into. If you have a lot of shards in your index, set a lower number for better efficiency. Default is 1, which means the task should not be divided.
sortStringA comma-separated list of <field> : <direction> pairs to sort by.
_sourceStringSpecifies whether to include the _source field in the response.
_source_excludesStringA comma-separated list of source fields to exclude from the response.
_source_includesStringA comma-separated list of source fields to include in the response.
statsStringValue to associate with the request for additional logging.
terminate_afterIntegerThe maximum number of documents OpenSearch should process before terminating the request.
timeoutTimeHow long the operation should wait from a response from active shards. Default is 1m.
versionBooleanWhether to include the document version as a match.
wait_for_active_shardsStringThe number of shards that must be active before OpenSearch executes the operation. Valid values are all or any integer up to the total number of shards in the index. Default is 1, which is the primary shard.
wait_for_completionBooleanSetting this parameter to false indicates to OpenSearch it should not wait for completion and perform this request asynchronously. Asynchronous requests run in the background, and you can use the Tasks API to monitor progress.

Request body

To search your index for specific documents, you must include a query in the request body that OpenSearch uses to match documents. If you don’t use a query, OpenSearch treats your delete request as a simple delete document operation.

  1. {
  2. "query": {
  3. "match": {
  4. "movie-length": "124"
  5. }
  6. }
  7. }

Response

  1. {
  2. "took": 143,
  3. "timed_out": false,
  4. "total": 1,
  5. "deleted": 1,
  6. "batches": 1,
  7. "version_conflicts": 0,
  8. "noops": 0,
  9. "retries": {
  10. "bulk": 0,
  11. "search": 0
  12. },
  13. "throttled_millis": 0,
  14. "requests_per_second": -1.0,
  15. "throttled_until_millis": 0,
  16. "failures": []
  17. }

Response body fields

FieldDescription
tookThe amount of time in milliseconds OpenSearch needed to complete the operation.
timed_outWhether any delete requests during the operation timed out.
totalTotal number of documents processed.
deletedTotal number of documents deleted.
batchesNumber of scroll responses the request processed.
version_conflictsNumber of conflicts the request ran into.
noopsHow many delete requests OpenSearch ignored during the operation. This field always returns 0.
retriesThe number of bulk and search retry requests.
throttled_millisNumber of throttled milliseconds during the request.
requests_per_secondNumber of requests executed per second during the operation.
throttled_until_millisThe amount of time until OpenSearch executes the next throttled request. Always equal to 0 in a delete by query request.
failuresAny failures that occur during the request.