delete.txt

.. _golang-delete-guide:

================
Delete Documents
================

.. meta::
   :description: Learn how to remove documents from MongoDB collections using delete operations like `DeleteOne()` and `DeleteMany()`, with examples and options.

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

Overview
--------

In this guide, you can learn how to remove documents from your MongoDB
collections using delete operations.

Sample Data
~~~~~~~~~~~

The example in this guide uses the following ``Book`` struct as a model for documents
in the ``books`` collection:

.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/delete.go
   :start-after: start-book-struct
   :end-before: end-book-struct
   :language: go
   :dedent:

To run the example in this guide, load the sample data into the
``db.books`` collection with the following snippet:

.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/delete.go
   :language: go
   :dedent:
   :start-after: begin insertDocs
   :end-before: end insertDocs

Each document contains a description of a book that
includes the title, author, and page length corresponding to
the ``title``, ``author``, and ``length`` fields in each document.

.. include:: /includes/fundamentals/automatic-db-coll-creation.rst

Delete Operations
-----------------

Use **delete operations** to remove data from MongoDB. Delete operations
consist of the following methods:

- ``DeleteOne()``, which deletes *the first document* that matches the filter
- ``DeleteMany()``, which deletes *all* documents that match the filter

.. tip::

   If one document matches your filter when running the ``DeleteMany()``
   method, it's equivalent to running the ``DeleteOne()`` method.

Parameters
~~~~~~~~~~

The ``DeleteOne()`` and ``DeleteMany()`` methods expect you to pass a
``Context`` type and a ``non-nil`` query filter specifying which
documents to match.

They both optionally take a ``DeleteOptions`` type as a third parameter,
which represents options you can use to configure the delete operation.
If you don't specify a ``DeleteOptions``, the driver uses the default
values for each option.

The ``DeleteOptions`` type allows you to configure options with the
following methods:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Method
     - Description

   * - ``SetHint()``
     - | The index to use to scan for documents to delete.
       | Default: ``nil``

   * - ``SetCollation()``
     - | The type of language collation to use when sorting results.
       | Default: ``nil``

Return Value
~~~~~~~~~~~~

The ``DeleteOne()`` and ``DeleteMany()`` methods return a
``DeleteResult`` type. This type contains the ``DeletedCount`` property,
which states the number of documents deleted. If there are no matches to
your filter, no document gets deleted and ``DeletedCount`` is ``0``.

Example
```````

The following example performs the following with the ``DeleteMany()``
method:

- Matches and deletes documents where the ``length`` is greater than ``300``
- Instructs the method to use the ``_id`` as the index

.. io-code-block::
   :copyable: true

   .. input::
      :language: go

      filter := bson.D{{"length", bson.D{{"$gt", 300}}}}
      opts := options.Delete().SetHint(bson.D{{"_id", 1}})

      result, err := coll.DeleteMany(context.TODO(), filter, opts)
      if err != nil {
         panic(err)
      }

      fmt.Printf("Number of documents deleted: %d\n", result.DeletedCount)

   .. output::
      :language: none
      :visible: false

      Number of documents deleted: 2

.. tip::

   If the preceding example used the ``DeleteOne()`` method instead of
   ``DeleteMany()``, the driver would delete the first of the two
   matched documents.

Additional Information
----------------------

For runnable examples of the delete operations, see the following usage
examples:

- :ref:`golang-delete-one`
- :ref:`golang-delete-many`

To learn more about performing the operations mentioned, see the
following guides:

- :ref:`golang-query-document`

To learn about how the driver uses Context, see :ref:`golang-context`.

To learn more about specifying hints, see :ref:`golang-indexes`.

To learn more about collations, see :ref:`golang-collations`.

API Documentation
~~~~~~~~~~~~~~~~~

To learn more about any of the methods or types discussed in this
guide, see the following API Documentation:

- `DeleteOne() <{+api+}/mongo#Collection.DeleteOne>`__
- `DeleteMany() <{+api+}/mongo#Collection.DeleteMany>`__
- `DeleteOptions <{+api+}/mongo/options#DeleteOptions>`__
- `DeleteResult <{+api+}/mongo#DeleteResult>`__