DOCSP-37537 Delete Operations (#47)

Author: jordan-smith721

source/includes/write/delete.py

@@ -0,0 +1,11 @@
+# start-delete-one
+
+# end-delete-one
+
+# start-delete-many
+
+# end-delete-many
+
+# start-delete-options
+
+# end-delete-options

source/write-operations.txt

@@ -14,8 +14,9 @@ Write Data to MongoDB
    /write/insert
    /write/update
    /write/replace
+   /write/delete
 
 - :ref:`pymongo-write-insert`
 - :ref:`pymongo-write-update`
 - :ref:`pymongo-write-replace`
-
+- :ref:`pymongo-write-delete`

source/write/delete.txt

@@ -0,0 +1,177 @@
+.. _pymongo-write-delete:
+
+================
+Delete Documents
+================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: remove, drop, code example
+
+Overview
+--------
+
+In this guide, you can learn how to use {+driver-short+} to remove
+documents from a MongoDB collection by performing delete operations.
+
+A delete operation removes one or more documents from a MongoDB collection.
+You can perform a delete operation by using the ``delete_one()`` or
+``delete_many()`` methods.
+
+.. .. tip:: Interactive Lab
+
+..    This page includes a short interactive lab that demonstrates how to
+..    modify data by using the ``delete_many()`` method. You can complete this
+..    lab directly in your browser window without installing MongoDB or a code editor.
+
+..    To start the lab, click the :guilabel:`Open Interactive Tutorial` button at the
+..    top of the page. To expand the lab to a full-screen format, click the
+..    full-screen button (:guilabel:`⛶`) in the top-right corner of the lab pane.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``sample_restaurants.restaurants`` collection
+from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+free MongoDB Atlas cluster and load the sample datasets, see the
+:ref:`<pymongo-get-started>` tutorial.
+
+Delete Operations
+-----------------
+
+You can perform delete operations in MongoDB by using the following methods:
+
+- ``delete_one()``, which deletes *the first document* that matches the search criteria
+- ``delete_many()``, which deletes *all documents* that match the search criteria
+
+Each delete method requires a **query filter** document, which specifies the
+search criteria that determine which documents to select for removal.
+For more information about query filters, see the 
+:manual:`Query Filter Documents section </core/document/#query-filter-documents>` in
+the MongoDB Server manual.
+
+Delete One Document
+~~~~~~~~~~~~~~~~~~~
+
+The following example uses the ``delete_one()`` method to remove a document in
+the ``restaurants`` collection with a ``name`` value of ``"Ready Penny Inn"``:
+
+.. literalinclude:: /includes/write/delete.py
+   :start-after: start-delete-one
+   :end-before: end-delete-one
+   :language: python
+   :copyable:
+
+Delete Multiple Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following example uses the ``delete_many()`` method to remove all documents
+in the ``restaurants`` collection with a ``borough`` value of ``"Brooklyn"``:
+
+.. literalinclude:: /includes/write/delete.py
+   :start-after: start-delete-many
+   :end-before: end-delete-many
+   :language: python
+   :copyable:
+
+Customize the Delete Operation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``delete_one()`` and ``delete_many()`` methods optionally accept additional
+parameters, which represent options you can use to configure the delete
+operation. If you don't specify any additional options, the driver does not customize
+the delete operation.
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Property
+     - Description
+
+   * - ``collation``
+     - | Specifies the kind of language collation to use when sorting
+         results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
+         in the MongoDB Server manual.
+
+   * - ``hint``
+     - | Gets or sets the index to scan for documents. 
+         For more information, see the :manual:`hint statement </reference/command/delete/#std-label-deletes-array-hint>`
+         in the MongoDB Server manual.
+
+   * - ``session``
+     - | An instance of ``ClientSession``.
+
+   * - ``let``
+     - | A map of parameter names and values. Values must be constant or closed
+         expressions that don't reference document fields. For more information,
+         see the :manual:`let statement
+         </reference/command/delete/#std-label-delete-let-syntax>` in the
+         MongoDB Server manual.
+
+   * - ``comment``
+     - | A comment to attach to the operation. For more information, see the :manual:`delete command
+         fields </reference/command/delete/#command-fields>` guide in the
+         MongoDB Server manual for more information.
+
+The following code uses the ``delete_many()`` method to delete all documents in
+the ``restaurants`` collection with a ``name`` value that includes the string ``"Mongo"``.
+It also uses the ``comment`` option to add a comment to the operation:
+
+.. literalinclude:: /includes/write/delete.py
+   :start-after: start-delete-options
+   :end-before: end-delete-options
+   :language: python
+   :copyable:
+
+.. tip::
+
+   If the preceding example used the ``delete_one()`` method instead of
+   ``delete_many()``, the driver would delete only the first document with a
+   ``name`` value that includes ``"Mongo"``.
+
+Return Value
+~~~~~~~~~~~~
+
+The ``delete_one()`` and ``delete_many()`` methods return a
+``DeleteResult`` type. This type contains the following properties:
+
+- ``deleted_count``, which indicates the number of documents deleted
+- ``acknowledged``, which indicates if the server acknowledges the result
+- ``raw_result``, which is the raw result returned by the server
+
+.. note::
+
+   If the ``acknowledged`` attribute is ``False``, all other attributes of ``DeleteResult``
+   raise an ``InvalidOperation`` exception when accessed. The driver cannot
+   determine these values if the server does not acknowledge the write operation.
+
+If the query filter does not match any documents, the driver doesn't delete any
+documents and ``deleted_count`` is 0.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API Documentation:
+
+- `delete_one() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.delete_one>`__
+- `delete_many() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.delete_many>`__
+- `DeleteResult <{+api-root+}pymongo/results.html#pymongo.results.DeleteResult>`__
+- `ClientSession <{+api-root+}pymongo/client_session.html#pymongo.client_session.ClientSession>`__
+
+
+.. .. _pymongo-delete-instruqt-lab:
+
+.. .. instruqt:: /mongodb-docs/tracks/delete-documents---c-net-driver?token=em_69t_l-j0BC_en7Uy
+..    :title: delete_many() Lesson
+..    :drawer: