Delete documents

Finds documents in a collection using filter clauses, and then deletes those documents.

If you specify an empty filter, this method will delete all documents in the collection.

This method does not support sort parameters, including vector search. If you want to use sort parameters to find documents, use the method to find documents instead. Then, use the method to delete a single document to delete each found document by ID.

Method signature

Python
TypeScript
Java
curl

collection.delete_many(
    filter: Dict[str, Any],
    *,
    max_time_ms: int,
) -> DeleteResult

collection.deleteMany(
  filter: Filter<Schema>,
  options?: {
    maxTimeMS?: number,
  },
): Promise<DeleteManyResult>

DeleteResult deleteMany(
  Filter filter
)

DeleteResult deleteMany(
  Filter filter,
  DeleteManyOptions options
)

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/COLLECTION_NAME" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "deleteMany": {
    "filter": FILTER
  }
}'

Result

Python
TypeScript
Java
curl

Deletes documents that match the specified parameters and returns a DeleteResult object that includes details about the success of the operation.

A result that includes a deleted count of -1 indicates that every document in the collection was deleted.

Example response:

DeleteResult(deleted_count=2, raw_results=...)

Deletes documents that match the specified parameters and returns a promise that resolves to a DeleteManyResult object that includes details about the success of the operation.

A result that includes a deleted count of -1 indicates that every document in the collection was deleted.

Example resolved response:

{ deletedCount: 1 }

Deletes documents that match the specified parameters and returns DeleteResult, which includes the number of documents that were deleted.

A result that includes a deleted count of -1 indicates that every document in the collection was deleted.

Deletes documents that match the specified parameters and returns an object that includes details about the number of documents that were deleted.

A result that includes a deleted count of -1 indicates that every document in the collection was deleted.

Example response:

{
  "status": {
    "deletedCount": 1
  }
}

If more than 20 documents match the specified filter parameters, only the first 20 documents are deleted. In this case, the status.deletedCount is 20, and the status.moreData value is true. To delete the next batch of 20 documents, you must resend the request.

Example response if more documents match the filter than were deleted:

{
  "status": {
    "deletedCount":20,
    "moreData":true
  }
}

Parameters

Python
TypeScript
Java
curl

Name Type Summary

Name	Type	Summary
`filter`	`Dict[str, Any]`	Optional. An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match this filter criteria. For a list of available filter operators and more examples, see Data API operators. Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.
`max_time_ms`	`int`	Optional. The maximum time, in milliseconds, that the client should wait for each underlying HTTP request. Default: The default value for the collection. This default is 30 seconds unless you specified a different default when you initialized the `Collection` object.

filter

Dict[str, Any]

Optional. An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match this filter criteria.

For a list of available filter operators and more examples, see Data API operators.

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.

max_time_ms

int

Optional. The maximum time, in milliseconds, that the client should wait for each underlying HTTP request.

Default: The default value for the collection. This default is 30 seconds unless you specified a different default when you initialized the Collection object.

Name Type Summary

Name	Type	Summary
`filter`	`Filter<Schema>`	An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match this filter criteria. For a list of available filter operators and more examples, see Data API operators. Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.
`options`	`WithTimeout`	Optional. The options for this operation. See the `options` table for more details.

filter

Filter<Schema>

An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match this filter criteria.

For a list of available filter operators and more examples, see Data API operators.

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.

options

WithTimeout

Optional. The options for this operation. See the options table for more details.

Properties of `options`
Name	Type	Summary
`maxTimeMS`	`number`	Optional. The maximum time, in milliseconds, that the client should wait for each underlying HTTP request. Default: The default value for the collection. This default is 30 seconds unless you specified a different default when you initialized the `Collection` object.

Name Type Summary

Name	Type	Summary
`filter`	`Filter`	An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match this filter criteria. For a list of available filter operators and more examples, see Data API operators. Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.
`options`	`DeleteManyOptions`	Optional. The options for this operation. This class does not include any methods that are specific to the `deleteMany` method.

filter

Filter

An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match this filter criteria.

For a list of available filter operators and more examples, see Data API operators.

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.

options

DeleteManyOptions

Optional. The options for this operation. This class does not include any methods that are specific to the deleteMany method.

Use the deleteMany command with these parameters:

Name Type Summary

Name	Type	Summary
`filter`	`object`	An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match this filter criteria. For a list of available filter operators and more examples, see Data API operators. Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.

filter

object

An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match this filter criteria.

For a list of available filter operators and more examples, see Data API operators.

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.

Examples

The following examples demonstrate how to delete documents in a collection.

Delete documents that match a filter

You can use a filter to find documents that match specific criteria. For example, you can find documents with an isCheckedOut value of false and a numberOfPages value less than 300.

For a list of available filter operators and more examples, see Data API operators.

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Delete documents
result = collection.delete_many(
    {
        "$and": [
            {"isCheckedOut": False},
            {"numberOfPages": {"$lt": 300}},
        ]
    }
)

print(result)

import { DataAPIClient } from '@datastax/astra-db-ts';

// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');

// Delete documents
(async function () {
  const result = await collection.deleteMany(
    {
      $and: [
        { isCheckedOut: false },
        { numberOfPages: { $lt: 300 } }
      ],
    }
  );

  console.log(result);
})();

package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.Filter;
import com.datastax.astra.client.model.Filters;
import com.datastax.astra.client.model.DeleteResult;

public class DeleteMany {

    public static void main(String[] args) {
        // Get an existing collection
        Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getCollection("COLLECTION_NAME");

        // Delete documents
        Filter filter = Filters.and(
          Filters.eq("isCheckedOut", false),
          Filters.lt("numberOfPages", 300));
        DeleteResult result = collection.deleteMany(filter);
        System.out.println(result.getDeletedCount());
    }
}

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "deleteMany": {
    "filter": {"$and": [
      {"isCheckedOut": false},
      {"numberOfPages": {"$lt": 300}}
    ]}
  }
}'

Delete all documents

To delete all documents, use an empty filter.

A result that includes a deleted count of -1 indicates that every document in the collection was deleted.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient

# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Delete all documents
result = collection.delete_many({})

print(result)

import { DataAPIClient } from '@datastax/astra-db-ts';

// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');

// Delete documents
(async function () {
  const result = await collection.deleteMany({});

  console.log(result);
})();

package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.DeleteResult;

public class DeleteMany {

    public static void main(String[] args) {
        // Get an existing collection
        Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
            .getDatabase("ASTRA_DB_API_ENDPOINT")
            .getCollection("COLLECTION_NAME");

        // Delete documents
        DeleteResult result = collection.deleteMany(null);
        System.out.println(result.getDeletedCount());
    }
}

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "deleteMany": {
    "filter": {}
  }
}'

Delete more than 20 documents

Python
TypeScript
Java
curl

The client automatically issues multiple Data API HTTP requests to delete all documents that match your filter.

You can only delete 20 documents per HTTP request.

If more than 20 documents match the specified filter parameters, only the first 20 documents will be deleted. In this case, the status.deletedCount is 20, and the status.moreData value is true.

To delete the next batch of 20 documents, you must resend the request. To delete all documents, continue sending the request until the status.moreData value is omitted from the response.

If you use an empty filter, you do not need to batch your requests. In that case, the server automatically iterates over batches of documents until all documents are deleted.

Client reference

Python
TypeScript
Java
curl

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Delete documents

Method signature

Result

Parameters

Examples

Delete documents that match a filter

Delete all documents

Delete more than 20 documents

Client reference

Was this helpful?

Give Feedback