> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete records matching a filter
> This operation doesn't accept empty filters.
This operation is resource-intensive.
Use it only if you can't get the object IDs of the records you want to delete.
It's more efficient to get a list of object IDs with the [`browse` operation](https://www.algolia.com/doc/rest-api/search/browse),
and then delete the records using the [`batch` operation](https://www.algolia.com/doc/rest-api/search/batch).
This operation is subject to [indexing rate limits](https://support.algolia.com/hc/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
**Required ACL:** `deleteIndex`
**See also:** [Should I use the deleteBy method for deleting records](https://support.algolia.com/hc/articles/16385098766353-Should-I-use-the-deleteBy-method-for-deleting-records-that-match-a-query)
## OpenAPI
````yaml specs/search.yml post /1/indexes/{indexName}/deleteByQuery
openapi: 3.1.0
info:
title: Search API
summary: >-
The Algolia Search API lets you search, configure, and manage your indices
and records
description: >
## Client libraries
Use Algolia's API clients and libraries to reliably integrate Algolia's APIs
with your apps.
The official API clients are covered by Algolia's [Service Level
Agreement](https://www.algolia.com/policies/sla).
For more information, see [Algolia's
ecosystem](https://www.algolia.com/doc/libraries).
## Base URLs
Base URLs for the Search API:
- `https://{APPLICATION_ID}.algolia.net`
- `https://{APPLICATION_ID}-dsn.algolia.net`.
If your subscription includes a [Distributed Search Network](https://dashboard.algolia.com/infra),
this ensures that requests are sent to servers closest to users.
Both URLs provide high availability by distributing requests with load
balancing.
**All requests must use HTTPS.**
## Retry strategy
To guarantee high availability, implement a retry strategy for all API
requests using the URLs of your servers as fallbacks:
- `https://{APPLICATION_ID}-1.algolianet.com`
- `https://{APPLICATION_ID}-2.algolianet.com`
- `https://{APPLICATION_ID}-3.algolianet.com`
These URLs use a different DNS provider than the primary URLs.
Randomize this list to ensure an even load across the three servers.
All Algolia API clients implement this retry strategy.
## Authentication
Add these headers to authenticate requests:
- `x-algolia-application-id`. Your Algolia application ID.
- `x-algolia-api-key`. An API key with the necessary permissions to make the
request.
The required access control list (ACL) to make a request is listed in each endpoint's reference.
You can find your application ID and API key in the [Algolia
dashboard](https://dashboard.algolia.com/account/api-keys).
## Request format
Depending on the endpoint, request bodies are either JSON objects or arrays
of JSON objects.
## Parameters
Parameters are passed as query parameters for GET and DELETE requests,
and in the request body for POST and PUT requests.
Query parameters must be
[URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).
Non-ASCII characters must be UTF-8 encoded.
Plus characters (`+`) are interpreted as spaces.
Arrays as query parameters must be one of:
- A comma-separated string: `attributesToRetrieve=title,description`
- A URL-encoded JSON array:
`attributesToRetrieve=%5B%22title%22,%22description%22%D`
## Response status and errors
The Search API returns JSON responses.
Since JSON doesn't guarantee any specific ordering, don't rely on the order
of attributes in the API response.
Successful responses return `2xx` statuses. Client errors return `4xx`
statuses. Server errors return `5xx` statuses.
Error responses have a `message` property with more information.
## Version
The current version of the Search API is version 1, indicated by the `/1/`
in each endpoint's URL.
version: 1.0.0
servers:
- url: https://{appId}.algolia.net
variables:
appId:
default: ALGOLIA_APPLICATION_ID
- url: https://{appId}-1.algolianet.com
variables:
appId:
default: ALGOLIA_APPLICATION_ID
- url: https://{appId}-2.algolianet.com
variables:
appId:
default: ALGOLIA_APPLICATION_ID
- url: https://{appId}-3.algolianet.com
variables:
appId:
default: ALGOLIA_APPLICATION_ID
- url: https://{appId}-dsn.algolia.net
variables:
appId:
default: ALGOLIA_APPLICATION_ID
security:
- appId: []
apiKey: []
tags:
- name: Advanced
description: Query your logs.
- name: Api Keys
x-displayName: API keys
description: >
Manage your API keys.
API requests must be authenticated with an API key.
API keys can have permissions (access control lists, ACL) and
restrictions.
externalDocs:
url: https://www.algolia.com/doc/guides/security/api-keys
description: API keys.
- name: Clusters
description: |
Multi-cluster operations.
Multi-cluster operations are **deprecated**.
If you have issues with your Algolia infrastructure
due to large volumes of data, contact the Algolia support team.
- name: Dictionaries
description: >
Manage your dictionaries.
Customize language-specific settings, such as stop words, plurals, or word
segmentation.
Dictionaries are application-wide.
externalDocs:
url: >-
https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp
description: Natural languages.
- name: Indices
description: >
Manage your indices and index settings.
Indices are copies of your data that are stored on Algolia's servers.
They're optimal data structures for fast search and are made up of records
and settings.
externalDocs:
url: >-
https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices
description: Manage your indices.
- name: Records
description: >
Add, update, and delete records from your indices.
Records are individual items in your index.
When they match a search query, they're returned as search results, in the
order determined by your ranking.
Records are schemaless JSON objects.
When adding or updating many records, check the [indexing rate
limits](https://support.algolia.com/hc/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
externalDocs:
url: >-
https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data
description: Prepare your records.
- name: Rules
description: >
Create, update, delete, and search for rules.
Rules are _if-then_ statements that you can use to curate search results.
Rules have _conditions_ that can trigger _consequences_.
Consequences are changes to the search results, such as changing the order
of search results or boosting a facet.
This can be useful for tuning specific queries or for merchandising.
externalDocs:
url: https://www.algolia.com/doc/guides/managing-results/rules/rules-overview
description: Index Rules.
- name: Search
description: Search one or more indices for matching records or facet values.
- name: Synonyms
description: |
Create, update, delete, and search for synonyms.
Synonyms are terms that the search engine should consider equal.
externalDocs:
url: >-
https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms
description: Synonyms.
- name: Vaults
description: >-
Algolia Vault lets you restrict access to your clusters to specific IP
addresses and provides disk-level encryption at rest.
externalDocs:
url: https://www.algolia.com/doc/guides/security/algolia-vault
description: Algolia Vault.
- name: _model_index_settings
x-displayName: Index settings
description: |
.
paths:
/1/indexes/{indexName}/deleteByQuery:
post:
tags:
- Records
summary: Delete records matching a filter
description: >
This operation doesn't accept empty filters.
This operation is resource-intensive.
Use it only if you can't get the object IDs of the records you want to
delete.
It's more efficient to get a list of object IDs with the [`browse`
operation](https://www.algolia.com/doc/rest-api/search/browse),
and then delete the records using the [`batch`
operation](https://www.algolia.com/doc/rest-api/search/batch).
This operation is subject to [indexing rate
limits](https://support.algolia.com/hc/articles/4406975251089-Is-there-a-rate-limit-for-indexing-on-Algolia).
operationId: deleteBy
parameters:
- $ref: '#/components/parameters/IndexName'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/deleteByParams'
responses:
'200':
$ref: '#/components/responses/UpdatedAt'
'400':
$ref: '#/components/responses/BadRequest'
'402':
$ref: '#/components/responses/FeatureNotEnabled'
'403':
$ref: '#/components/responses/MethodNotAllowed'
'404':
$ref: '#/components/responses/IndexNotFound'
externalDocs:
url: >-
https://support.algolia.com/hc/articles/16385098766353-Should-I-use-the-deleteBy-method-for-deleting-records-that-match-a-query
description: Should I use the deleteBy method for deleting records.
x-codeSamples:
- lang: csharp
label: C#
source: >-
// Initialize the client
var client = new SearchClient(new
SearchConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY"));
// Call the API
var response = await client.DeleteByAsync(
"",
new DeleteByParams { Filters = "brand:brandName" }
);
// print the response
Console.WriteLine(response);
- lang: dart
label: Dart
source: |-
// Initialize the client
final client =
SearchClient(appId: 'ALGOLIA_APPLICATION_ID', apiKey: 'ALGOLIA_API_KEY');
// Call the API
final response = await client.deleteBy(
indexName: "",
deleteByParams: DeleteByParams(
filters: "brand:brandName",
),
);
// print the response
print(response);
- lang: go
label: Go
source: >-
// Initialize the client
client, err := search.NewClient("ALGOLIA_APPLICATION_ID",
"ALGOLIA_API_KEY")
if err != nil {
// The client can fail to initialize if you pass an invalid parameter.
panic(err)
}
// Call the API
response, err := client.DeleteBy(client.NewApiDeleteByRequest(
"",
search.NewEmptyDeleteByParams().SetFilters("brand:brandName")))
if err != nil {
// handle the eventual error
panic(err)
}
// print the response
print(response)
- lang: java
label: Java
source: >-
// Initialize the client
SearchClient client = new SearchClient("ALGOLIA_APPLICATION_ID",
"ALGOLIA_API_KEY");
// Call the API
UpdatedAtResponse response = client.deleteBy("",
new DeleteByParams().setFilters("brand:brandName"));
// print the response
System.out.println(response);
- lang: javascript
label: JavaScript
source: >-
// Initialize the client
const client = algoliasearch('ALGOLIA_APPLICATION_ID',
'ALGOLIA_API_KEY');
// Call the API
const response = await client.deleteBy({ indexName: 'theIndexName',
deleteByParams: { filters: 'brand:brandName' } });
// print the response
console.log(response);
- lang: kotlin
label: Kotlin
source: >-
// Initialize the client
val client = SearchClient(appId = "ALGOLIA_APPLICATION_ID", apiKey =
"ALGOLIA_API_KEY")
// Call the API
var response =
client.deleteBy(
indexName = "",
deleteByParams = DeleteByParams(filters = "brand:brandName"),
)
// print the response
println(response)
- lang: php
label: PHP
source: >-
// Initialize the client
$client = SearchClient::create('ALGOLIA_APPLICATION_ID',
'ALGOLIA_API_KEY');
// Call the API
$response = $client->deleteBy(
'',
['filters' => 'brand:brandName',
],
);
// print the response
var_dump($response);
- lang: python
label: Python
source: >-
# Initialize the client
# In an asynchronous context, you can use SearchClient instead,
which exposes the exact same methods.
client = SearchClientSync("ALGOLIA_APPLICATION_ID",
"ALGOLIA_API_KEY")
# Call the API
response = client.delete_by(
index_name="",
delete_by_params={
"filters": "brand:brandName",
},
)
# print the response
print(response)
- lang: ruby
label: Ruby
source: >-
# Initialize the client
client = Algolia::SearchClient.create("ALGOLIA_APPLICATION_ID",
"ALGOLIA_API_KEY")
# Call the API
response = client.delete_by("",
Algolia::Search::DeleteByParams.new(filters: "brand:brandName"))
# print the response
puts(response)
- lang: scala
label: Scala
source: >-
// Initialize the client
val client = SearchClient(appId = "ALGOLIA_APPLICATION_ID", apiKey =
"ALGOLIA_API_KEY")
// Call the API
val response = Await.result(
client.deleteBy(
indexName = "",
deleteByParams = DeleteByParams(
filters = Some("brand:brandName")
)
),
Duration(100, "sec")
)
// print the response
println(response)
- lang: swift
label: Swift
source: >-
// Initialize the client
let client = try SearchClient(appID: "ALGOLIA_APPLICATION_ID",
apiKey: "ALGOLIA_API_KEY")
// Call the API
let response = try await client.deleteBy(
indexName: "",
deleteByParams: DeleteByParams(filters: "brand:brandName")
)
// print the response
print(response)
- lang: cURL
label: curl
source: |-
curl --request POST \
--url https://algolia_application_id.algolia.net/1/indexes/ALGOLIA_INDEX_NAME/deleteByQuery \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-algolia-api-key: ALGOLIA_API_KEY' \
--header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
--data '
{
"facetFilters": [
[
"category:Book",
"category:-Movie"
],
"author:John Doe"
],
"filters": "(category:Book OR category:Ebook) AND _tags:published",
"numericFilters": [
[
"inStock = 1",
"deliveryDate < 1441755506"
],
"price < 1000"
],
"tagFilters": [
[
"Book",
"Movie"
],
"SciFi"
],
"aroundLatLng": "40.71,-74.01",
"aroundRadius": 1,
"insideBoundingBox": "lorem",
"insidePolygon": [
[
47.3165,
4.9665,
47.3424,
5.0201,
47.32,
4.9
],
[
40.9234,
2.1185,
38.643,
1.9916,
39.2587,
2.0104
]
]
}
'
components:
parameters:
IndexName:
name: indexName
in: path
description: Name of the index on which to perform the operation.
required: true
schema:
type: string
example: ALGOLIA_INDEX_NAME
schemas:
deleteByParams:
type: object
additionalProperties: false
properties:
aroundLatLng:
$ref: '#/components/schemas/aroundLatLng'
aroundRadius:
$ref: '#/components/schemas/aroundRadius'
facetFilters:
$ref: '#/components/schemas/facetFilters'
filters:
$ref: '#/components/schemas/filters'
insideBoundingBox:
$ref: '#/components/schemas/insideBoundingBox'
insidePolygon:
$ref: '#/components/schemas/insidePolygon'
numericFilters:
$ref: '#/components/schemas/numericFilters'
tagFilters:
$ref: '#/components/schemas/tagFilters'
aroundLatLng:
type: string
description: >
Coordinates for the center of a circle, expressed as a comma-separated
string of latitude and longitude.
Only records included within a circle around this central location are
included in the results.
The radius of the circle is determined by the `aroundRadius` and
`minimumAroundRadius` settings.
This parameter is ignored if you also specify `insidePolygon` or
`insideBoundingBox`.
example: 40.71,-74.01
default: ''
x-categories:
- Geo-Search
aroundRadius:
description: >
Maximum radius for a search around a central location.
This parameter works in combination with the `aroundLatLng` and
`aroundLatLngViaIP` parameters.
By default, the search radius is determined automatically from the
density of hits around the central location.
The search radius is small if there are many hits close to the central
coordinates.
oneOf:
- type: integer
minimum: 1
description: Maximum search radius around a central location in meters.
- $ref: '#/components/schemas/aroundRadiusAll'
x-categories:
- Geo-Search
facetFilters:
description: >
Filter the search by facet values, so that only records with the same
facet values are retrieved.
**Prefer using the `filters` parameter, which supports all filter types
and combinations with boolean operators.**
- `[filter1, filter2]` is interpreted as `filter1 AND filter2`.
- `[[filter1, filter2], filter3]` is interpreted as `filter1 OR filter2
AND filter3`.
- `facet:-value` is interpreted as `NOT facet:value`.
While it's best to avoid attributes that start with a `-`, you can still
filter them by escaping with a backslash:
`facet:\-value`.
example:
- - category:Book
- category:-Movie
- author:John Doe
oneOf:
- type: array
items:
$ref: '#/components/schemas/facetFilters'
- type: string
x-categories:
- Filtering
filters:
type: string
description: >
Filter expression to only include items that match the filter criteria
in the response.
You can use these filter expressions:
- **Numeric filters.** ` `, where `` is one of
`<`, `<=`, `=`, `!=`, `>`, `>=`.
- **Ranges.** `: TO `, where `` and
`` are the lower and upper limits of the range (inclusive).
- **Facet filters.** `:`, where `` is a facet
attribute (case-sensitive) and `` a facet value.
- **Tag filters.** `_tags:` or just `` (case-sensitive).
- **Boolean filters.** `: true | false`.
You can combine filters with `AND`, `OR`, and `NOT` operators with the
following restrictions:
- You can only combine filters of the same type with `OR`.
**Not supported:** `facet:value OR num > 3`.
- You can't use `NOT` with combinations of filters.
**Not supported:** `NOT(facet:value OR facet:value)`
- You can't combine conjunctions (`AND`) with `OR`.
**Not supported:** `facet:value OR (facet:value AND facet:value)`
Use quotes if the facet attribute name or facet value contains spaces,
keywords (`OR`, `AND`, `NOT`), or quotes.
If a facet attribute is an array, the filter matches if it matches at
least one element of the array.
For more information, see
[Filters](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering).
example: (category:Book OR category:Ebook) AND _tags:published
x-categories:
- Filtering
insideBoundingBox:
oneOf:
- type: string
- type: 'null'
- $ref: '#/components/schemas/insideBoundingBoxArray'
insidePolygon:
type: array
items:
type: array
minItems: 6
maxItems: 20000
items:
type: number
format: double
description: >
Coordinates of a polygon in which to search.
Polygons are defined by 3 to 10,000 points. Each point is represented by
its latitude and longitude.
Provide multiple polygons as nested arrays.
For more information, see [filtering inside
polygons](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas).
This parameter is ignored if you also specify `insideBoundingBox`.
example:
- - 47.3165
- 4.9665
- 47.3424
- 5.0201
- 47.32
- 4.9
- - 40.9234
- 2.1185
- 38.643
- 1.9916
- 39.2587
- 2.0104
x-categories:
- Geo-Search
numericFilters:
description: >
Filter by numeric facets.
**Prefer using the `filters` parameter, which supports all filter types
and combinations with boolean operators.**
You can use numeric comparison operators: `<`, `<=`, `=`, `!=`, `>`,
`>=`.
Comparisons are precise up to 3 decimals.
You can also provide ranges: `facet: TO `. The range
includes the lower and upper boundaries.
The same combination rules apply as for `facetFilters`.
example:
- - inStock = 1
- deliveryDate < 1441755506
- price < 1000
oneOf:
- type: array
items:
$ref: '#/components/schemas/numericFilters'
- type: string
x-categories:
- Filtering
tagFilters:
description: >
Filter the search by values of the special `_tags` attribute.
**Prefer using the `filters` parameter, which supports all filter types
and combinations with boolean operators.**
Different from regular facets, `_tags` can only be used for filtering
(including or excluding records).
You won't get a facet count.
The same combination and escaping rules apply as for `facetFilters`.
example:
- - Book
- Movie
- SciFi
oneOf:
- type: array
items:
$ref: '#/components/schemas/tagFilters'
- type: string
x-categories:
- Filtering
updatedAtResponse:
type: object
description: Response, taskID, and update timestamp.
additionalProperties: false
required:
- taskID
- updatedAt
properties:
taskID:
$ref: '#/components/schemas/taskID'
updatedAt:
$ref: '#/components/schemas/updatedAt'
ErrorBase:
description: Error.
type: object
x-keep-model: true
additionalProperties: true
properties:
message:
type: string
example: Invalid Application-Id or API-Key
aroundRadiusAll:
title: all
type: string
description: >-
Return all records with a valid `_geoloc` attribute. Don't filter by
distance.
enum:
- all
insideBoundingBoxArray:
type: array
items:
type: array
minItems: 4
maxItems: 4
items:
type: number
format: double
description: >
Coordinates for a rectangular area in which to search.
Each bounding box is defined by the two opposite points of its diagonal,
and expressed as latitude and longitude pair:
`[p1 lat, p1 long, p2 lat, p2 long]`.
Provide multiple bounding boxes as nested arrays.
For more information, see [rectangular
area](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas).
example:
- - 47.3165
- 4.9665
- 47.3424
- 5.0201
- - 40.9234
- 2.1185
- 38.643
- 1.9916
x-categories:
- Geo-Search
taskID:
type: integer
format: int64
example: 1514562690001
description: >
Unique identifier of a task.
A successful API response means that a task was added to a queue.
It might not run immediately.
You can check the task's progress with the [`task`
operation](https://www.algolia.com/doc/rest-api/search/get-task) and
this task ID.
updatedAt:
type: string
example: '2023-07-04T12:49:15Z'
description: Date and time when the object was updated, in RFC 3339 format.
responses:
UpdatedAt:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/updatedAtResponse'
BadRequest:
description: Bad request or request arguments.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBase'
FeatureNotEnabled:
description: This feature is not enabled on your Algolia account.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBase'
MethodNotAllowed:
description: Method not allowed with this API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBase'
IndexNotFound:
description: Index not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBase'
securitySchemes:
appId:
type: apiKey
in: header
name: x-algolia-application-id
description: Your Algolia application ID.
apiKey:
type: apiKey
in: header
name: x-algolia-api-key
description: >
Your Algolia API key with the necessary permissions to make the request.
Permissions are controlled through access control lists (ACL) and access
restrictions.
The required ACL to make a request is listed in each endpoint's
reference.
````