db.collection.deleteOne()

Deletion Order

db.collection.deleteOne() deletes the first document that matches the filter. Use a field that is part of a unique index such as _id for precise deletions.

Time Series Collections

db.collection.deleteOne() returns a WriteError exception if used on a time series collection.

Sharded Collections

To use db.collection.deleteOne() on a sharded collection:

• If you only target one shard, you can use a partial shard key in the query specification or,

• You can provide the shard key or the _id field in the query specification.

Transactions

db.collection.deleteOne() can be used inside distributed transactions.

Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Transactions and Write Concern.

Oplog Entries

If a db.collection.deleteOne() operation successfully deletes a document, the operation adds an entry on the oplog (operations log). If the operation fails or does not find a document to delete, the operation does not add an entry on the oplog.

Delete a Single Document

The orders collection has documents with the following structure:

db.orders.insertOne(
   {
      _id: ObjectId("563237a41a4d68582c2509da"),
      stock: "Brent Crude Futures",
      qty: 250,
      type: "buy-limit",
      limit: 48.90,
      creationts: ISODate("2015-11-01T12:30:15Z"),
      expiryts: ISODate("2015-11-01T12:35:15Z"),
      client: "Crude Traders Inc."
   }
)

The following operation deletes the order with _id: ObjectId("563237a41a4d68582c2509da") :

try {
   db.orders.deleteOne( { _id: ObjectId("563237a41a4d68582c2509da") } );
} catch (e) {
   print(e);
}

The operation returns:

{ acknowledged: true, deletedCount: 1 }

The following operation deletes the first document with expiryts greater than ISODate("2015-11-01T12:40:15Z")

try {
   db.orders.deleteOne( { expiryts: { $lt: ISODate("2015-11-01T12:40:15Z") } } );
} catch (e) {
   print(e);
}

The operation returns:

{ acknowledged: true, deletedCount: 1 }

deleteOne() with Write Concern

Given a three member replica set, the following operation specifies a w of majority, wtimeout of 100:

try {
   db.orders.deleteOne(
       { _id: ObjectId("563237a41a4d68582c2509da") },
       { w: "majority", wtimeout: 100 }
   );
} catch (e) {
   print (e);
}

If the acknowledgement takes longer than the wtimeout limit, the following exception is thrown:

WriteConcernError({
   code: 64,
   errmsg: "waiting for replication timed out",
   errInfo: {
     wtimeout: true,
     writeConcern: {
       w: "majority",
       wtimeout: 100,
       provenance: "getLastErrorDefaults"
     }
   }
})

Specify Collation

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

A collection restaurants has the following documents:

db.restaurants.insertMany( [
   { _id: 1, category: "café", status: "A" },
   { _id: 2, category: "cafe", status: "a" },
   { _id: 3, category: "cafE", status: "a" }
] )

The following operation includes the collation option:

db.restaurants.deleteOne(
   { category: "cafe", status: "A" },
   { collation: { locale: "fr", strength: 1 } }
)

Specify hint for Delete Operations

In mongosh, create a students collection with the following documents:

db.members.insertMany( [
   { _id: 1, student: "Richard", grade: "F", points: 0 },
   { _id: 2, student: "Jane", grade: "A", points: 60 },
   { _id: 3, student: "Adam", grade: "F", points:  0 },
   { _id: 4, student: "Ronan", grade: "D", points: 20 },
   { _id: 5, student: "Noah", grade: "F", points:  0 },
   { _id: 6, student: "Henry", grade: "A", points: 86 }
] )

Create the following index on the collection:

db.members.createIndex( { grade: 1 } )

The following delete operation explicitly hints to use the index { grade: 1 }:

db.members.deleteOne(
   { points: { $lte: 20 }, grade: "F" },
   { hint: { grade: 1 } }
)

The delete command returns the following:

{ acknowledged: true, deletedCount: 1 }

To view the indexes used, you can use the $indexStats pipeline:

db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )

The accesses.ops field in the $indexStats output indicates the number of operations that used the index.