db.collection.deleteOne.txt

=========================
db.collection.deleteOne()
=========================

.. default-domain:: mongodb

.. meta::
   :description: Delete a single document from a collection.

.. facet::
   :name: programming_language 
   :values: shell

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. include:: /includes/wayfinding/mongosh-method-deleteOne.rst

Definition
----------

.. method:: db.collection.deleteOne()


   Removes a single document from a collection.

   :returns:
      
      A document containing:

      - A boolean ``acknowledged`` as ``true`` if the operation ran with 
        :term:`write concern` or ``false`` if write concern was disabled    
      - ``deletedCount`` containing the number of deleted documents

Compatibility
-------------

.. |operator-method| replace:: ``db.collection.deleteOne()``

This method is available in deployments hosted in the following environments:

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-all.rst

.. include:: /includes/fact-environments-onprem-only.rst

Syntax
------

The :method:`~db.collection.deleteOne()` method has the following form:

.. code-block:: javascript

   db.collection.deleteOne(
       <filter>,
       {
         writeConcern: <document>,
         collation: <document>,
         hint: <document|string>  
       }
   )

The :method:`~db.collection.deleteOne()` method takes the following
parameters:

.. list-table::
   :header-rows: 1
   :widths: 20 20 80

   * - Parameter
     - Type
     - Description

   * - :ref:`filter <deleteOne-filter>`
     - document
     - .. _deleteOne-filter:
    
       Specifies deletion criteria using a :ref:`query predicate
       <query-predicates-ref>`. 
      
       Specify an empty document ``{ }`` to delete the first document returned in 
       the collection.
      
   * - :ref:`writeConcern <deleteOne-wc>`
     - document
     - .. _deleteOne-wc:
    
       Optional. A document expressing the :doc:`write concern
       </reference/write-concern>`. Omit to use the default write concern.
      
       .. include:: /includes/extracts/transactions-operations-write-concern.rst
      
   * - :ref:`collation <deleteOne-collation>`
     - document
     - .. _deleteOne-collation:
  
       Optional. 
      
       .. include:: /includes/extracts/collation-option.rst
      
   * - :ref:`hint <deleteOne-hint>`
     - document
     - .. _deleteOne-hint:
 
       Optional. A document or string that specifies the :ref:`index
       <indexes>` to use to support the :ref:`query predicate
       <deleteOne-filter>`.
      
       The option can take an index specification document or the
       index name string.
      
       If you specify an index that does not exist, the operation
       errors.

       For an example, see :ref:`ex-deleteOne-hint`.

Behavior
--------

.. _deleteOne-deletion-order:

Deletion Order
~~~~~~~~~~~~~~

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


Sharded Collections
~~~~~~~~~~~~~~~~~~~

To use :method:`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,

- If you set ``limit: 1``, you do not need to provide the :term:`shard key` 
  or ``_id`` field in the query specification.

Transactions
~~~~~~~~~~~~

.. include:: /includes/extracts/transactions-supported-operation.rst

.. include:: /includes/extracts/transactions-operations-write-concern.rst

.. include:: /includes/extracts/transactions-usage.rst

.. |operation| replace:: :method:`db.collection.deleteOne()`

Oplog Entries
~~~~~~~~~~~~~

If a ``db.collection.deleteOne()`` operation successfully deletes a
document, the operation adds an entry on the :term:`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. 

Examples
--------

.. _deleteOne-example-delete-single-document:

Delete a Single Document
~~~~~~~~~~~~~~~~~~~~~~~~

The ``orders`` collection has documents with the following structure:

.. code-block:: javascript

   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")`` : 

.. code-block:: javascript

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

.. code-block:: javascript

   { acknowledged: true, deletedCount: 1 }
   
The following operation deletes the first document with ``expiryts`` greater 
than ``ISODate("2015-11-01T12:40:15Z")``

.. code-block:: javascript

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

The operation returns:

.. code-block:: javascript

   { acknowledged: true, deletedCount: 1 }
   
.. _deleteOne-example-update-with-write-concern:

deleteOne() with Write Concern
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: javascript

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

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

.. code-block:: javascript

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

.. seealso::

   :data:`WriteResult.writeConcernError`

Specify Collation
~~~~~~~~~~~~~~~~~

.. include:: /includes/extracts/collation-versionadded.rst

A collection ``restaurants`` has the following documents:

.. code-block:: javascript

   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 :ref:`collation <collation>`
option:

.. code-block:: javascript

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

.. _ex-deleteOne-hint:

Specify ``hint`` for Delete Operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In :binary:`~bin.mongosh`, create a ``students`` collection
with the following documents:

.. code-block:: javascript

   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:

.. code-block:: javascript

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

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

.. code-block:: javascript

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

.. note::
   
   If you specify an index that does not exist, the operation errors.

The delete command returns the following:

.. code-block:: javascript

   { acknowledged: true, deletedCount: 1 }

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

.. code-block:: javascript

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

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

.. seealso::

   To delete multiple documents, see 
   :method:`db.collection.deleteMany()`