DOCSP-43070: Delete documents

source/includes/write/delete.c

@@ -0,0 +1,66 @@
+#include <stdio.h>
+#include <bson/bson.h>
+#include <mongoc/mongoc.h>
+
+int
+main (void)
+{
+    mongoc_client_t *client;
+    mongoc_collection_t *collection;
+    mongoc_init ();
+
+    client = mongoc_client_new ("<connection string URI>");
+    collection = mongoc_client_get_collection (client, "sample_restaurants", "restaurants");
+
+    {
+        // Deletes a document that has a "name" value of "Ready Penny Inn"
+        // start-delete-one
+        bson_t *filter = BCON_NEW ("name", BCON_UTF8 ("Ready Penny Inn"));
+        bson_error_t error;
+
+        if (!mongoc_collection_delete_one (collection, filter, NULL, NULL, &error)) {
+            printf ("Delete error: %s\n", error.message);
+        }
+
+        bson_destroy (filter);
+        // end-delete-one
+    }
+
+    {
+        // Deletes documents that have a "borough" value of "Brooklyn"
+        // start-delete-many
+        bson_t *filter = BCON_NEW ("borough", BCON_UTF8 ("Brooklyn"));
+        bson_error_t error;
+
+        if (!mongoc_collection_delete_many (collection, filter, NULL, NULL, &error)) {
+            printf ("Delete error: %s\n", error.message);
+        }
+
+        bson_destroy (filter);
+        // end-delete-many
+    }
+
+    {
+        // Deletes matching documents and attaches a comment to the operation
+        // start-delete-options
+        bson_t *filter = BCON_NEW ("name", "{", "$regex", BCON_UTF8 ("Mongo"), "}");
+        bson_error_t error;
+        bson_t opts;
+        bson_init(&opts);
+        BCON_APPEND (&opts, "comment", BCON_UTF8 ("Deleting Mongo restaurants"));
+
+        if (!mongoc_collection_delete_many (collection, filter, &opts, NULL, &error)) {
+            printf ("Delete error: %s\n", error.message);
+        }
+
+        bson_destroy (filter);
+        bson_destroy (&opts);
+        // end-delete-options
+    }
+
+    mongoc_collection_destroy (collection);
+    mongoc_client_destroy (client);
+    mongoc_cleanup ();
+
+    return 0;
+}

source/write.txt

@@ -10,3 +10,4 @@ Write Data to MongoDB
 
    /write/insert
    /write/update
+   /write/delete

source/write/delete.txt

@@ -0,0 +1,150 @@
+.. _c-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 the {+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 ``mongoc_collection_delete_one()``
+or ``mongoc_collection_delete_many()`` functions.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
+database 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
+:atlas:`Get Started with Atlas </getting-started>` guide.
+
+Delete Operations
+-----------------
+
+You can perform delete operations by using the following functions:
+
+- ``mongoc_collection_delete_one()``, which deletes *the first document* that matches
+  the search criteria
+- ``mongoc_collection_delete_many()``, which deletes *all documents* that match the
+  search criteria
+
+Each delete function accepts the following parameters:
+
+- **Collection**: Specifies the collection to modify.
+
+- **Query filter** document: Specifies which collection documents to delete. For
+  more information about query filters, see the 
+  :manual:`Query Filter Documents section </core/document/#query-filter-documents>` in
+  the {+mdb-server+} manual.
+
+- **Results** location: Specifies a pointer to overwritable storage that will contain
+  operation results, or ``NULL``.
+
+- **Error** location: Specifies a location for an error value, or ``NULL``.
+
+Delete One Document
+~~~~~~~~~~~~~~~~~~~
+
+The following example uses the ``mongoc_collection_delete_one()`` function to remove a document in
+the ``restaurants`` collection that has a ``name`` value of ``"Ready Penny Inn"``:
+
+.. literalinclude:: /includes/write/delete.c
+   :start-after: start-delete-one
+   :end-before: end-delete-one
+   :language: c
+   :dedent:
+
+Delete Multiple Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following example uses the ``mongoc_collection_delete_many()`` function to remove all documents
+in the ``restaurants`` collection that have a ``borough`` value of ``"Brooklyn"``:
+
+.. literalinclude:: /includes/write/delete.c
+   :start-after: start-delete-many
+   :end-before: end-delete-many
+   :language: c
+   :dedent:
+
+Customize the Delete Operation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can modify the behavior of the ``mongoc_collection_delete_one()`` and
+``mongoc_collection_delete_many()`` functions by passing a BSON document that
+specifies option values. The following table describes some options you can
+set in the document:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Field
+     - Description
+
+   * - ``collation``
+     - | Specifies the kind of language collation to use when comparing
+         text. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
+         in the {+mdb-server+} manual.
+       | **Type**: ``bson_t``
+
+   * - ``writeConcern``
+     - | Sets the write concern for the operation.
+       | Defaults to the write concern of the namespace.
+       | **Type**: ``mongoc_write_concern_t``
+
+   * - ``let``
+     - | Specifies a document with a list of values to improve operation readability.
+         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
+         {+mdb-server+} manual.
+       | **Type**: ``bson_t``
+
+   * - ``comment``
+     - | A comment to attach to the operation. For more information, see the :manual:`insert command
+         fields </reference/command/insert/#command-fields>` guide in the
+         {+mdb-server+} manual.
+       | **Type**: ``bson_value_t``
+
+The following example calls the ``mongoc_collection_delete_many()`` function to delete
+all documents in the ``restaurants`` collection that have a ``name`` value containing
+the string ``"Mongo"``. It also sets the ``comment`` option to add a comment to the
+operation:
+
+.. literalinclude:: /includes/write/delete.c
+   :start-after: start-delete-options
+   :end-before: end-delete-options
+   :language: c
+   :dedent:
+
+.. tip::
+
+   If you use the ``mongoc_collection_delete_one()`` function instead of
+   ``mongoc_collection_delete_many()`` in the preceding example, the driver
+   deletes only the first document that has a ``name`` value containing ``"Mongo"``.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the functions discussed in this
+guide, see the following API documentation:
+
+- `mongoc_collection_delete_one() <{+api-libmongoc+}/mongoc_collection_delete_one.html>`__
+- `mongoc_collection_delete_many() <{+api-libmongoc+}/mongoc_collection_delete_many.html>`__