DOCSP-39625: Add new bulk write API info (#12)

* DOCSP-39625: Add new bulk write API info

* edits

* further reading

* rewordig, deleting

* add back section

* JS feedback

* more edits

* JS feedback 2

Author: norareidy

source/libmongoc/guides/bulk.txt

@@ -14,6 +14,13 @@ This tutorial explains how to take advantage of MongoDB C driver bulk write oper
 Executing write operations in batches reduces the number of network round trips, increasing write
 throughput.
 
+.. tip::
+
+   Beginning in MongoDB Server version 8.0 and C Driver version 1.28, you can use the `mongoc_bulkwrite_t
+   <{+api-libmongoc+}/mongoc_bulkwrite_t.html>`__ type. This type uses the ``bulkWrite`` server command to
+   perform multiple kinds of write operations against mixed namespaces in a single request. For more
+   information, see the :ref:`bulkwrite_server` section of this guide.
+
 Bulk Insert
 -----------
 
@@ -229,9 +236,40 @@ The ``reply`` document is empty:
 
    { }
 
+.. _bulkwrite_server:
+
+``bulkWrite`` Server Command
+----------------------------
+
+The previous examples on this page use the `mongoc_bulk_operation_t <{+api-libmongoc+}/mongoc_bulk_operation_t.html>`__
+type to perform bulk write operations. ``mongoc_bulk_operation_t`` runs the ``insert``, ``update`` and ``delete`` server
+commands. Bulk write operations that use ``mongoc_bulk_operation_t`` group operations by type and send them in
+separate commands. You can specify only one collection for each bulk write.
+
+Alternatively, you can perform bulk writes by using the `mongoc_bulkwrite_t <{+api-libmongoc+}/mongoc_bulkwrite_t.html>`__
+type, which runs the ``bulkWrite`` server command. The ``bulkWrite`` command was introduced in MongoDB Server 8.0 and
+supports insert, update, and delete operations on multiple namespaces in the same payload.
+
+When connected to MongoDB Server version 8.0 or later, we recommend using ``mongoc_bulkwrite_t`` over
+``mongoc_bulk_operation_t`` to reduce network round trips.
+
+Example
+~~~~~~~
+
+The following example demonstrates how to use ``mongoc_bulkwrite_t`` and ``mongoc_bulkwrite_execute()`` to
+insert documents into two different collections:
+
+.. literalinclude:: /libmongoc/includes/examples/bulk/bulkwrite.c
+   :emphasize-lines: 24, 43
+   :language: c
+   :caption: bulkwrite.c
+
 Further Reading
 ---------------
 
-See the `Driver Bulk API Spec <https://github.com/mongodb/specifications/blob/master/source/driver-bulk-update.rst>`__,
-which describes bulk write operations for all MongoDB drivers.
+For more information about bulk write operations, see the following bulk API specifications:
+
+- Original `Driver Bulk API Spec <https://github.com/mongodb/specifications/blob/master/source/driver-bulk-update.rst>`__
+- New `Driver Bulk API Spec <https://github.com/mongodb/specifications/blob/master/source/crud/bulk-write.md>`__, introduced
+  in MongoDB Server 8.0
 

source/libmongoc/includes/examples/bulk/bulkwrite.c

@@ -0,0 +1,87 @@
+// example-bulkwrite shows use of `mongoc_client_bulkwrite`.
+
+#include <mongoc/mongoc.h>
+
+#define HANDLE_ERROR(...)            \
+   if (1) {                          \
+      fprintf (stderr, __VA_ARGS__); \
+      fprintf (stderr, "\n");        \
+      goto fail;                     \
+   } else                            \
+      (void) 0
+
+int
+main (int argc, char *argv[])
+{
+   bool ok = false;
+
+   mongoc_init ();
+
+   bson_error_t error;
+   mongoc_client_t *client = mongoc_client_new ("mongodb://localhost:27017");
+   mongoc_bulkwriteopts_t *bwo = mongoc_bulkwriteopts_new ();
+   mongoc_bulkwriteopts_set_verboseresults (bwo, true);
+   mongoc_bulkwrite_t *bw = mongoc_client_bulkwrite_new (client);
+
+   // Insert a document to `db.coll1`
+   {
+      bson_t *doc = BCON_NEW ("foo", "bar");
+      if (!mongoc_bulkwrite_append_insertone (bw, "db.coll1", doc, NULL, &error)) {
+         HANDLE_ERROR ("Error appending insert one: %s", error.message);
+      }
+      bson_destroy (doc);
+   }
+   // Insert a document to `db.coll2`
+   {
+      bson_t *doc = BCON_NEW ("foo", "baz");
+      if (!mongoc_bulkwrite_append_insertone (bw, "db.coll2", doc, NULL, &error)) {
+         HANDLE_ERROR ("Error appending insert one: %s", error.message);
+      }
+      bson_destroy (doc);
+   }
+
+   mongoc_bulkwritereturn_t bwr = mongoc_bulkwrite_execute (bw, bwo);
+
+   // Print results.
+   {
+      BSON_ASSERT (bwr.res); // Has results. NULL only returned for unacknowledged writes.
+      printf ("Insert count          : %" PRId64 "\n", mongoc_bulkwriteresult_insertedcount (bwr.res));
+      const bson_t *ir = mongoc_bulkwriteresult_insertresults (bwr.res);
+      BSON_ASSERT (ir); // Has verbose results. NULL only returned if verbose results not requested.
+      char *ir_str = bson_as_relaxed_extended_json (ir, NULL);
+      printf ("Insert results        : %s\n", ir_str);
+      bson_free (ir_str);
+   }
+
+   // Print all error information. To observe: try setting the `_id` fields to cause a duplicate key error.
+   if (bwr.exc) {
+      const char *msg = "(none)";
+      if (mongoc_bulkwriteexception_error (bwr.exc, &error)) {
+         msg = error.message;
+      }
+      const bson_t *we = mongoc_bulkwriteexception_writeerrors (bwr.exc);
+      char *we_str = bson_as_relaxed_extended_json (we, NULL);
+      const bson_t *wce = mongoc_bulkwriteexception_writeconcernerrors (bwr.exc);
+      char *wce_str = bson_as_relaxed_extended_json (wce, NULL);
+      const bson_t *er = mongoc_bulkwriteexception_errorreply (bwr.exc);
+      char *er_str = bson_as_relaxed_extended_json (er, NULL);
+      printf ("Top-level error       : %s\n", msg);
+      printf ("Write errors          : %s\n", we_str);
+      printf ("Write concern errors  : %s\n", wce_str);
+      printf ("Error reply           : %s\n", er_str);
+      bson_free (er_str);
+      bson_free (wce_str);
+      bson_free (we_str);
+   }
+
+   mongoc_bulkwriteresult_destroy (bwr.res);
+   mongoc_bulkwriteexception_destroy (bwr.exc);
+   mongoc_bulkwrite_destroy (bw);
+
+   ok = true;
+fail:
+   mongoc_client_destroy (client);
+   mongoc_bulkwriteopts_destroy (bwo);
+   mongoc_cleanup ();
+   return ok ? EXIT_SUCCESS : EXIT_FAILURE;
+}