Navigation

collection.findOneAndDelete()

Definition

collection.findOneAndDelete()

Remove a single document from a collection based on a query filter and return a document with the same form as the document immediately before it was deleted. Unlike collection.deleteOne(), this action allows you to atomically find and delete a document with the same command. This avoids the risk of other update operations changing the document between separate find and delete operations.

Usage

Example

To call the collection.findOneAndDelete() action from a Function, get a collection handle with database.collection() then call the handle’s findOneAndUpdate() method.

// Find the first document that has a quantity greater than 25
const query = { "quantity": { "$gte": 25 } };
// Sort the documents in order of descending quantity before
// deleting the first one.
const options = {
  "sort": { "quantity": -1 }
}

return itemsCollection.findOneAndDelete(query, options)
  .then(deletedDocument => {
    if(deletedDocument) {
      console.log(`Successfully deleted document that had the form: ${deletedDocument}.`)
    } else {
      console.log("No document matches the provided query.")
    }
    return deletedDocument
  })
  .catch(err => console.error(`Failed to find and delete document: ${err}`))

To call the collection.findOneAndDelete() action from a JavaScript SDK, use the RemoteMongoCollection.findOneAndDelete() method.

// Find the first document that has a quantity greater than 25
const query = { "quantity": { "$gte": 25 } };
// Sort the documents in order of descending quantity before
// deleting the first one.
const options = {
  "sort": { "quantity": -1 }
}

itemsCollection.findOneAndDelete(query, options)
  .then(deletedDocument => {
    if(deletedDocument) {
      console.log(`Successfully deleted document that had the form: ${deletedDocument}.`)
    } else {
      console.log("No document matches the provided query.")
    }
    return deletedDocument
  })
  .catch(err => console.error(`Failed to find and delete document: ${err}`))

To call the collection.findOneAndDelete() action from the Java/Android SDK, use the RemoteMongoCollection.findOneAndDelete() method.

// Find the document that describes "legos"
Document query = new Document().append("name", "legos");

Document projection = new Document()
    .append("_id", 1)
    .append("name", 1)
    .append("price", 1);
Document sort = new Document()
    .append("name", 1);

// return the updated document has no effect
// upsert has no effect
RemoteFindOneAndModifyOptions options =
    new RemoteFindOneAndModifyOptions()
    .sort(sort)
    .projection(projection);

final Task <Document> findOneAndDeleteTask =
    itemsCollection.findOneAndDelete(query, options, Document.class);
findOneAndDeleteTask.addOnCompleteListener(new OnCompleteListener <Document> () {
    @Override
    public void onComplete(@NonNull Task <Document> task) {
        if (task.isSuccessful()) {
            Log.d("app", String.format("Successfully deleted document: %s",
                    task.getResult()));
        } else {
            Log.e("app", "Failed to findOneAndDelete: ", task.getException());
        }
    }
});

Parameters

The collection.findOneAndDelete() action has the following form:

findOneAndDelete(query, options)
Parameter Description

Query Filter

query: <document>

Required. A standard MongoDB query document that specifies which document to delete. You can use most query selectors except for evaluation, geospatial, or bitwise selectors.

If multiple documents match the query, only the first document in sort order or natural order will be updated.

Delete Options

options: <document>

A document that specifies configuration options for the query. The options document has the following form:

{
   "sort": <document>,
   "projection": <document>
}

Sort

options.sort: <document>

Optional. Specifies the query sort order. Sort documents specify one or more fields to sort on where the value of each field indicates whether MongoDB should sort it in ascending (1) or descending (0) order. The sort order determines which document collection.findOneAndReplace() affects.

Example

The following sort document specifies that documents should be sorted first by age from highest to lowest. Once sorted by age, the result set should further be sorted by name in alphabetical order for each distinct age value.

{ age: 0, name: 1 }

Projection

options.projection: <document>

Optional. A document that specifies which fields MongoDB should return or withhold in each document that matches the query.

To return all fields in the matching documents, omit this parameter or specify an empty projection document ({}).

To return specific fields and the document’s _id, specify the fields in the projection document with a value of 1:

// Includes the field in returned documents
{ <Field Name>: 1 }

To withhold specific fields, specify the fields in the projection document with a value of 0:

// Withholds the field from returned documents
{ <Field Name>: 0 }

Note

You may specify either fields to include or fields to withhold but not both. For example, the following projection is invalid because it simultaneously includes the name field and withholds the address field:

// Invalid
// Can't simultaneously include and withhold
{ "name": 1, "address": 0 }

The exception to this rule is the _id field, which you may withhold from any query:

// Valid
// Can exclude _id while including other fields
{ "_id": 0, "name": 1 }

The findOneAndDelete() method has the following form:

findOneAndDelete(query, options)
Parameter Description

Query Filter

query: <document>

Required. A standard MongoDB query document that specifies which document to delete. You can use most query selectors except for evaluation, geospatial, or bitwise selectors.

If multiple documents match the query, only the first document in sort order or natural order will be updated.

Delete Options

options: <document>

A document that specifies configuration options for the query. The options document has the following form:

{
   "sort": <document>,
   "projection": <document>
}

Sort

options.sort: <document>

Optional. Specifies the query sort order. Sort documents specify one or more fields to sort on where the value of each field indicates whether MongoDB should sort it in ascending (1) or descending (0) order. The sort order determines which document collection.findOneAndReplace() affects.

Example

The following sort document specifies that documents should be sorted first by age from highest to lowest. Once sorted by age, the result set should further be sorted by name in alphabetical order for each distinct age value.

{ age: 0, name: 1 }

Projection

options.projection: <document>

Optional. A document that specifies which fields MongoDB should return or withhold in each document that matches the query.

To return all fields in the matching documents, omit this parameter or specify an empty projection document ({}).

To return specific fields and the document’s _id, specify the fields in the projection document with a value of 1:

// Includes the field in returned documents
{ <Field Name>: 1 }

To withhold specific fields, specify the fields in the projection document with a value of 0:

// Withholds the field from returned documents
{ <Field Name>: 0 }

Note

You may specify either fields to include or fields to withhold but not both. For example, the following projection is invalid because it simultaneously includes the name field and withholds the address field:

// Invalid
// Can't simultaneously include and withhold
{ "name": 1, "address": 0 }

The exception to this rule is the _id field, which you may withhold from any query:

// Valid
// Can exclude _id while including other fields
{ "_id": 0, "name": 1 }

The findOneAndDelete() method has the following form:

findOneAndDelete​(Bson filter, RemoteFindOneAndModifyOptions options, Class<ResultT> resultClass)
Parameter Description

Query Filter

filter: <document>

Required. A standard MongoDB query document that specifies which document to delete. You can use most query selectors except for evaluation, geospatial, or bitwise selectors.

If multiple documents match the query, only the first document in sort order or natural order will be deleted.

Update Options

options: <RemoteFindOneAndModifyOptions>

Optional: An instance of the RemoteFindOneAndModifyOptions. class. The returnNewDocument and upsert options can be configured for a RemoteFindOneAndModifyOptions object used for a findOneAndDelete operation, but have no effect.

RemoteFindOneAndModifyOptions options =
  new RemoteFindOneAndModifyOptions()
  .sort(<document>)
  .projection(<document>);

Sort

RemoteFindOneAndModifyOptions.sort: <document>

Optional. Specifies the query sort order. Sort documents specify one or more fields to sort on where the value of each field indicates whether MongoDB should sort it in ascending (1) or descending (0) order. The sort order determines which document collection.findOneAndDelete() affects.

Example

The following sort document specifies that documents should be sorted first by age from highest to lowest. Once sorted by age, the result set should further be sorted by name in alphabetical order for each distinct age value.

Document sort = new Document()
 .append("age", 0)
 .append("name", 1);

Projection

RemoteFindOneAndModifyOptions.projection: <document>

Optional. A document that specifies which fields MongoDB should return or withhold in the document returned by the query.

To return all fields in the matching document, omit this parameter or specify an empty projection document (new Document()).

To return specific fields and the document’s _id, specify the fields in the projection document with a value of 1:

// Includes the field in returned document
Document sort = new Document()
  .append(<Field Name>, 1);

To withhold specific fields, specify the fields in the projection document with a value of 0:

// Withholds the field from returned document
Document sort = new Document()
  .append(<Field Name>, 0);

Note

You may specify either fields to include or fields to withhold but not both. For example, the following projection is invalid because it simultaneously includes the name field and withholds the address field:

// Invalid
// Can't simultaneously include and withhold
Document sort = new Document()
 .append("name", 1)
 .append("address", 0);

The exception to this rule is the _id field, which you may withhold from any query:

// Valid
// Can exclude _id while including other fields
Document sort = new Document()
 .append("_id", 0)
 .append("name", 1);

Result Class

resultClass: <class>
Optional. Indicates the type of the document returned by the operation.
public func findOneAndDelete(filter: Document,
                 options: RemoteFindOneAndModifyOptions? = nil,
                 _ completionHandler: @escaping (StitchResult<CollectionType?>) -> Void)

Return Value

The collection.findOneAndDelete() action returns a :mdn:`Promise

<Web/JavaScript/Reference/Global_Objects/Promise>` that resolves to a single document that the query deleted. If no documents match the specified query, the promise resolves to null.

Promise<document|null>

The collection.findOneAndDelete() action returns a Promise that resolves to a single document that the query deleted. If no documents match the specified query, the promise resolves to null.

Promise<document|null>

The findOneAndDelete() function returns a Task containing the deleted document, which can be accessed using the task.getResult() method. The type of the result contained within the Task varies based on the configuration of the RemoteMongoCollection used for the operation and the value of the resultClass parameter.

  • If resultClass is specified, the returned Task contains an object of type ResultT, which resolves to type resultClass.
  • If a resultClass is not specified, the returned Task contains an object of type DocumentT, which resolves to type Document unless otherwise specified when the RemoteMongoCollection was instantiated.
  • If no document matches the provided query, the task will fail and details can be accessed using task.getException().
Task<ResultT result | DocumentT result>

The findOneAndDelete method will call the supplied completionHandler with a StitchResult.