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

The following method belongs to the astrapy.Collection class.

delete_many(
  filter: Dict[str, Any],
  *,
  general_method_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> CollectionDeleteResult

The following method belongs to the Collection class.

async deleteMany(
  filter: CollectionFilter<Schema>,
  options?: {
    timeout?: number | TimeoutDescriptor,
  },
): CollectionDeleteManyResult

The following methods belong to the com.datastax.astra.client.Collection class.

CollectionDeleteResult deleteMany(
  Filter filter
)

CollectionDeleteResult deleteMany(
  Filter filter,
  CollectionDeleteManyOptions 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 CollectionDeleteResult 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:

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

Deletes documents that match the specified parameters and returns a promise that resolves to a CollectionDeleteManyResult 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 CollectionDeleteResult, 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 Filter operators for collections. 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.
`general_method_timeout_ms`	`int`	Optional. The maximum time, in milliseconds, that the whole operation, which may involve multiple HTTP requests, can take. Default: The default value for the collection. This default is 30 seconds unless you specified a different default when you initialized the `Collection` or `DataAPIClient` object. For more information, see Timeout options.
`request_timeout_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 10 seconds unless you specified a different default when you initialized the `Collection` or `DataAPIClient` object. For more information, see Timeout options.
`timeout_ms`	`int`	Optional. An alias for `general_method_timeout_ms`.

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 Filter operators for collections.

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.

general_method_timeout_ms

int

Optional. The maximum time, in milliseconds, that the whole operation, which may involve multiple HTTP requests, can take.

Default: The default value for the collection. This default is 30 seconds unless you specified a different default when you initialized the Collection or DataAPIClient object. For more information, see Timeout options.

request_timeout_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 10 seconds unless you specified a different default when you initialized the Collection or DataAPIClient object. For more information, see Timeout options.

timeout_ms

int

Optional. An alias for general_method_timeout_ms.

Name Type Summary

Name	Type	Summary
`filter`	`CollectionFilter<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 Filter operators for collections. 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`	`object`	Optional. The options for this operation. See the `options` table for more details.

filter

CollectionFilter<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 Filter operators for collections.

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

object

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

Properties of `options`
Name	Type	Summary
`timeout`	`number` \| `TimeoutDescriptor`	Optional. The timeout(s) to apply to this method. You can specify `requestTimeoutMs` and `generalMethodTimeoutMs`. Details about the `timeout` parameter The `TimeoutDescriptor` object can contain these properties: `requestTimeoutMs` (`number`): 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 10 seconds unless you specified a different default when you initialized the `Collection` or `DataAPIClient` object. `generalMethodTimeoutMs` (`number`): The maximum time, in milliseconds, that the whole operation, which may involve multiple HTTP requests, can take. Since this method issues a single HTTP request, `generalMethodTimeoutMs` and `requestTimeoutMs` are equivalent. If you specify both, the minimum of the two will be used. Default: The default value for the collection. This default is 30 seconds unless you specified a different default when you initialized the `Collection` or `DataAPIClient` object. If you specify a number instead of a `TimeoutDescriptor` object, that number will be applied to `generalMethodTimeoutMs`.

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 Filter operators for collections. 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`	`CollectionDeleteManyOptions`	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 Filter operators for collections.

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

CollectionDeleteManyOptions

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 Filter operators for collections. 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 Filter operators for collections.

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 Filter operators for collections.

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.examples;

import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.collections.commands.results.CollectionDeleteResult;

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));
        CollectionDeleteResult 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.examples;

import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.collections.commands.results.CollectionDeleteResult;

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
        CollectionDeleteResult 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