Delete a document

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 a document

Locate and delete one document in a collection.

deleteOne is similar to findOneAndDelete, except that the response includes only the result of the operation. The response doesn’t include a document object, and the request doesn’t support response-related parameters, such as projection or returnDocument.

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 a document matching a filter condition, and then delete it:

# Find by ID
response = collection.delete_one({ "_id": "1" })

# Find by a document property
document = collection.delete_one({"location": "warehouse_C"})

# Find with a filter operator
document = collection.delete_one({"tag": {"$exists": True}})

Locate and delete the document most similar to a query vector from either $vector or $vectorize:

# Find by vector search with $vector
result = collection.delete_one({}, sort={"$vector": [.12, .52, .32]})

# Find by vector search with $vectorize
result = collection.delete_one({}, sort={"$vectorize": "Text to vectorize"})

Parameters:

Name Type Summary

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.
`sort`	`Optional[Dict[str, Any]]`	See Find a document and Sort clauses.
`max_time_ms`	`Optional[int]`	A timeout, in milliseconds, for the underlying HTTP request. This method uses the collection-level timeout by default.

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.

sort

Optional[Dict[str, Any]]

See Find a document and Sort clauses.

max_time_ms

Optional[int]

A timeout, in milliseconds, for the underlying HTTP request. 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.

Example response

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

Example:

from astrapy import DataAPIClient
import astrapy
client = DataAPIClient("TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.my_collection

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

collection.delete_one({"seq": 1})
# prints: DeleteResult(deleted_count=1, raw_results=...)
collection.distinct("seq")
# prints: [0, 2]
collection.delete_one(
    {"seq": {"$exists": True}},
    sort={"seq": astrapy.constants.SortDocuments.DESCENDING},
)
# prints: DeleteResult(deleted_count=1, raw_results=...)
collection.distinct("seq")
# prints: [0]
collection.delete_one({"seq": 2})
# prints: DeleteResult(deleted_count=0, raw_results=...)

For more information, see the Client reference.

Find a document matching a filter condition, and then delete it:

// Find by ID
const result = await collection.deleteOne({ _id: '1' });

// Find by a document property
const result = await collection.deleteOne({ location: 'warehouse_C' });

// Find with a filter operator
const result = await collection.deleteOne({ tag: { $exists: true } });

Locate and delete the document most similar to a query vector from either $vector or $vectorize:

// Find by vector search with $vector
const result = await collection.deleteOne({}, { sort: { $vector: [.12, .52, .32] } });

// Find by vector search with $vectorize
const result = await collection.deleteOne({}, { sort: { $vectorize: 'Text to vectorize' } });

Parameters:

Name Type Summary

Name	Type	Summary
`filter`	`Filter<Schema>`	A filter to select the document to delete. For a list of available operators, see Data API operators. For additional examples, see Find documents using filter clauses.
`options?`	`DeleteOneOptions`	The options for this operation.

filter

Filter<Schema>

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

options?

DeleteOneOptions

The options for this operation.

Options (DeleteOneOptions):

Name Type Summary

Name	Type	Summary
`sort?`	`Sort`	See Find a document and Sort clauses.
`maxTimeMS?`	`number`	The maximum time in milliseconds that the client should wait for the operation to complete each underlying HTTP request.

sort?

Sort

See Find a document and Sort clauses.

maxTimeMS?

number

The maximum time in milliseconds that the client should wait for the operation to complete each underlying HTTP request.

Returns:

Promise<DeleteOneResult> - The result of the deletion operation.

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.deleteOne({ seq: 1 });

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

  // { deletedCount: 1 }
  await collection.deleteOne({ seq: { $exists: true } }, { sort: { seq: -1 } });

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

  // { deletedCount: 0 }
  await collection.deleteOne({ seq: 2 });
})();

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 deleteOne(Filter filter);
DeleteResult deleteOne(Filter filter, DeleteOneOptions options);

// Asynchronous
CompletableFuture<DeleteResult> deleteOneAsync(Filter filter);
CompletableFuture<DeleteResult> deleteOneAsync(Filter filter, DeleteOneOptions options);

Parameters:

Name Type Summary

Name	Type	Summary
`filter` (optional)	`Filter`	Filter criteria to find the document 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 examples and options, including `projection` and `sort`, see Find documents using filter clauses.
`options` (optional)	`DeleteOneOptions`	Set the different options for the `deleteOne()` operation, including `sort`.

filter (optional)

Filter

Filter criteria to find the document 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 examples and options, including projection and sort, see Find documents using filter clauses.

options (optional)

DeleteOneOptions

Set the different options for the deleteOne() operation, including sort.

Returns:

DeleteResult - Wrapper that contains the deleted count.

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.DeleteOneOptions;
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 com.datastax.astra.client.model.Sorts;

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

public class DeleteOne {
    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"));

        // Delete one options
        DeleteOneOptions options = new DeleteOneOptions()
                .sort(Sorts.ascending("field2"));
        DeleteResult result = collection.deleteOne(filter, options);
        System.out.println("Deleted Count:" + result.getDeletedCount());
    }
}

Find a document matching a filter condition, and then delete it:

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 '{
  "deleteOne": {
    "filter": {
      "tags": "first"
    }
  }
}' | jq

Locate and update the document most similar to a query vector from either $vector or $vectorize:

"deleteOne": {
  "sort": { "$vector": [0.1, 0.2, 0.3] }
}

Parameters:

Name Type Summary

Name	Type	Summary
`deleteOne`	`command`	The Data API command to find and delete the first document in a collection that matches the given `filter`/`sort` criteria. If there is no match, then no action is taken.
`sort`, `filter`	`object`	Search criteria to find the document to delete. For a list of available operators, see Data API operators. For `sort` and `filter` examples, see Find a document and Sort clauses.

deleteOne

command

The Data API command to find and delete the first document in a collection that matches the given filter/sort criteria. If there is no match, then no action is taken.

sort, filter

object

Search criteria to find the document to delete. For a list of available operators, see Data API operators. For sort and filter examples, see Find a document and Sort clauses.

Returns:

A successful response returns the number of deleted documents. For deleteOne, this is either 1 (one document deleted) or 0 (no matches).

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

Delete a document

Delete a document

Was this helpful?

Give Feedback