Delete documents

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

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.

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

filter

Optional[Dict[str, Any]]

A predicate expressed as a dictionary according to the Data API filter syntax. For example: {}, {"name": "John"}, {"price": {"$lt": 100}}, {"$and": [{"name": "John"}, {"price": {"$lt": 100}}]}. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

An empty filter deletes all documents, completely emptying the collection.

max_time_ms

Optional[int]

The timeout, in milliseconds, for the entire delete operation. This method uses the collection-level timeout by default.

The time required for the delete operation depends on the number of documents that match the filter. To delete a large number of documents, this operation issues multiple sequential HTTP requests until all matching documents are deleted. You might need to increase the timeout parameter to allow enough time for all underlying HTTP requests.

Name Type Summary

filter

Filter<Schema>

A filter to select the documents to delete. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

An empty filter deletes all documents, completely emptying the collection.

options?

WithTimeout

The timeout, in milliseconds, for the entire delete operation.

Name Type Summary

filter (optional)

Filter

Filter criteria to find the documents to delete. The filter is a JSON object that can contain any valid Data API filter expression. For a list of available operators and examples, see Data API operators. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

An empty filter deletes all documents, completely emptying the collection.

Name Type Summary

deleteMany

command

The Data API command to delete all matching documents from a collection based on the provided filter criteria.

filter

object

An empty filter deletes all documents, completely emptying the collection.

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

Result

Parameters

Examples

Delete documents that match a filter

Delete all documents

Delete more than 20 documents

Client reference

Was this helpful?

Give Feedback