Delete documents

Documents represent a single row or record of data in Astra DB Serverless databases.

You use the Collection class to work with documents through the Data API clients. For instructions to get a Collection object, see Work with collections.

For general information about working with documents, including common operations and operators, see the Work with documents.

For more information about the Data API and clients, see Get started with the Data API.

Delete documents

Delete all documents in a collection that match a given filter condition. If you supply an empty filter, then the operation deletes every document in the collection.

This operation doesn’t support sort conditions.

Sort and filter clauses can use only indexed fields.

If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

Python
TypeScript
Java
curl

For more information, see the Client reference.

Find documents in a collection that match a given filter, and then delete them:

delete_result = collection.delete_many({"status": "processed"})

An empty filter deletes all documents and completely empties the collection:

delete_result = collection.delete_many({})

Parameters:

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, see Data API operators. For additional examples, see Find documents using filter clauses.

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.

Returns:

DeleteResult - An object representing the response from the database after the delete operation. It includes information about the success of the operation. A response of deleted_count=-1 indicates that every document in the collection was deleted.

Example response

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

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.

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
database = client.get_database("A*PI_ENDPOINT")
collection = database.my_collection

collection.insert_many([{"seq": 1}, {"seq": 0}, {"seq": 2}])

collection.delete_many({"seq": {"$lte": 1}})
# prints: DeleteResult(raw_results=..., deleted_count=2)
collection.distinct("seq")
# prints: [2]
collection.delete_many({"seq": {"$lte": 1}})
# prints: DeleteResult(raw_results=..., deleted_count=0)

# An empty filter deletes all documents and completely empties the collection:
collection.delete_many({})
# prints: DeleteResult(raw_results=..., deleted_count=-1)

For more information, see the Client reference.

Find documents in a collection that match a given filter, and then delete them:

const result = await collection.deleteMany({ status: 'processed' });

An empty filter deletes all documents and completely empties the collection:

const result = await collection.deleteMany({});

Parameters:

Name Type Summary

filter

Filter<Schema>

A filter to select the documents to delete. For a list of available operators, see Data API operators. For additional examples, see Find documents using filter clauses.

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

options?

WithTimeout

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

Returns:

Promise<DeleteManyResult> - The result of the deletion operation. A deleted count of -1 indicates that every document in the collection was deleted.

The time required for the delete operation depends on the number of documents that match the filter.

Example:

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

// Reference an untyped collection
const client = new DataAPIClient('TOKEN');
const db = client.db('ENDPOINT', { keyspace: 'KEYSPACE' });
const collection = db.collection('COLLECTION');

(async function () {
  // Insert some document
  await collection.insertMany([{ seq: 1 }, { seq: 0 }, { seq: 2 }]);

  // { deletedCount: 1 }
  await collection.deleteMany({ seq: { $lte: 1 } });

  // [2]
  await collection.distinct('seq');

  // { deletedCount: 0 }
  await collection.deleteMany({ seq: { $lte: 1 } });

  // { deletedCount: -1 }
  await collection.deleteMany({});
})();

Operations on documents are performed at the Collection level. Collection is a generic class with the default type of Document. You can specify your own type, and the object is serialized by Jackson. For more information, see the Client reference.

Most methods have synchronous and asynchronous flavors, where the asynchronous version is suffixed by Async and returns a CompletableFuture:

// Synchronous
DeleteResult deleteMany(Filter filter);

// Asynchronous
CompletableFuture<DeleteResult> deleteManyAsync(Filter filter);

An empty filter deletes all documents and completely empties the collection:

DeleteResult deleteMany();

Parameters:

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, see Data API operators. For additional examples, see Find documents using filter clauses.

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

Returns:

DeleteResult - Wrapper that contains the deleted count.

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 iterates over batches of documents until all matching documents are deleted.

Example:

package com.datastax.astra.client.collection;

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

import static com.datastax.astra.client.model.Filters.lt;

public class DeleteMany {
    public static void main(String[] args) {
        Collection<Document> collection = new DataAPIClient("TOKEN")
                .getDatabase("API_ENDPOINT")
                .getCollection("COLLECTION_NAME");

        // Sample Filter
        Filter filter = Filters.and(
                Filters.gt("field2", 10),
                lt("field3", 20),
                Filters.eq("field4", "value"));
        DeleteResult result = collection.deleteMany(filter);
        System.out.println("Deleted Count:" + result.getDeletedCount());

    }
}

Find documents in a collection that match a filter condition, and then delete them:

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": {
      "status": "inactive"
    }
  }
}' | jq

An empty filter or deleteMany object deletes all documents and completely empties the collection:

# Empty filter object
"deleteMany": { "filter": {} }

# Empty deleteMany object
"deleteMany": {}

Parameters:

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

A filter to select the documents to delete. For a list of available operators, see Data API operators. For additional examples, see Find documents using filter clauses.

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

Returns:

A successful response returns the result of the delete operation. This operation deletes up to 20 documents at a time. If the deletedCount is 20, there might be more matching documents to delete.

{
  "status": {
    "deletedCount": 20
  }
}

To delete another batch of documents, reissue the same request. Continue issuing the deleteMany request until the deletedCount is less than 20.

Example of batch deletion

For this example, assume that you send the following deleteMany command and the server finds 30 matching documents:

{
    "deleteMany": {
        "filter": { "a": true }
    }
}

The server deletes the first 20 documents and then returns the following response:

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

The server doesn’t tell you explicitly how many matches were found. However, the deletedCount of 20 indicates there could be more matching documents to delete. To delete the next batch of documents, reissue the same deleteMany command:

{
    "deleteMany": {
        "filter": { "a": true }
    }
}

This time, the server returns the following:

{
  "status": {
    "deletedCount": 10
  }
}

Because the deletedCount is less than 20, this indicates that all matching documents were deleted.

To confirm, you can reissue the deleteMany request and get a deletedCount of 0:

{
  "status": {
    "deletedCount": 0
  }
}

A deleted count of -1 indicates that every document in the collection was deleted. This occurs if you pass an empty filter, an empty deleteMany object, or you run deleteMany against an empty collection. In this case, you don’t need to delete documents in batches. With an empty filter, the server automatically iterates over batches of documents until all documents are deleted.

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

Delete documents

Delete documents

Was this helpful?

Give Feedback