DOCSP-13868 bulk usage example (#26)

* added bulk usage example page

Author: kyuan-mongodb

source/includes/usage-examples/code-snippets/bulk.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"go.mongodb.org/mongo-driver/bson"
+	"go.mongodb.org/mongo-driver/mongo"
+	"go.mongodb.org/mongo-driver/mongo/options"
+)
+
+func main() {
+	var uri string
+	if uri = os.Getenv("MONGODB_URI"); uri == "" {
+		log.Fatal("You must set your 'MONGODB_URI' environmental variable. See\n\t https://docs.mongodb.com/drivers/go/current/usage-examples/")
+	}
+
+	client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		if err = client.Disconnect(context.TODO()); err != nil {
+			panic(err)
+		}
+	}()
+
+	// begin bulk
+	coll := client.Database("insertDB").Collection("haikus")
+	models := []mongo.WriteModel{
+		mongo.NewReplaceOneModel().SetFilter(bson.D{{"title", "Record of a Shriveled Datum"}}).
+			SetReplacement(bson.D{{"title", "Dodging Greys"}, {"text", "When there're no matches, no longer need to panic. You can use upsert"}}),
+		mongo.NewUpdateOneModel().SetFilter(bson.D{{"title", "Dodging Greys"}}).
+			SetUpdate(bson.D{{"$set", bson.D{{"title", "Dodge The Greys"},}},}),
+	}
+	opts := options.BulkWrite().SetOrdered(true)
+
+	results, err := coll.BulkWrite(context.TODO(), models, opts)
+	// end bulk
+
+	if err != nil {
+		panic(err)
+	}
+
+	// When you run this file for the first time, it should print: 
+	// Number of documents replaced or modified: 2
+	fmt.Printf("Number of documents replaced or modified: %d", results.ModifiedCount)
+}

source/usage-examples.txt

@@ -19,10 +19,10 @@ Usage Examples
    /usage-examples/command
    /usage-examples/struct-tagging
    /usage-examples/distinct
+   /usage-examples/bulkWrite
 
 ..
    /usage-examples/insert-operations
-   /usage-examples/bulkWrite
    /usage-examples/watch
 
 

source/usage-examples/bulkWrite.txt

@@ -4,10 +4,57 @@ Perform Bulk Operations
 
 .. default-domain:: mongodb
 
+You can perform bulk write operations on a collection using the
+``BulkWrite()`` method. 
 
-The ``bulkWrite()`` method performs batch write operations against a
-*single* collection. This method reduces the number of network round trips from
-your application to the server which therefore increases the potential
-throughput and performance. Since you only receive the success status after
-all the operations return, we recommend you use this if that meets the
-requirements of your use case.
+The following example specifies a slice of ``WriteModels`` and an option
+to the ``BulkWrite()`` method, which performs the following in order:
+
+- Match a document where the ``title`` is "Record of a Shriveled Datum" and replace it with a new document
+- Match a document where the ``title`` is "Dodging Greys" and update that field to "Dodge The Greys"
+
+.. include:: /includes/usage-examples/run-example-tip.rst
+
+.. literalinclude:: /includes/usage-examples/code-snippets/bulk.go
+   :start-after: begin bulk
+   :end-before: end bulk
+   :emphasize-lines: 10
+   :language: go
+   :dedent:
+
+Click `here <{+example+}/bulk.go>`__ to see a fully runnable example.
+
+Expected Result
+---------------
+
+After you run the preceding code snippet, you should be able to find the
+document in the ``haikus`` collection: 
+
+.. code-block:: json
+   :copyable: false
+
+   { 
+      "_id" : ObjectId("..."),
+      "title" : "Dodge The Greys",
+      "text" : "When there're no matches, no longer need to panic. You can use upsert."
+   }
+
+For an example on how to find a document, see our :doc:`Find
+One Usage Example </usage-examples/findOne>`.
+
+Additional Information
+----------------------
+
+For more information on performing bulk write operations on a collection
+and handling potential errors, see our guide on <TODO: Bulk Write
+Fundamentals>. 
+
+For more information, see our :manual:`Bulk Write Operations
+</core/bulk-write-operations/>` page.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+- `BulkWrite() <{+godocs+}/mongo#Collection.BulkWrite>`__
+- `NewUpdateOneModel() <{+godocs+}/mongo#NewUpdateOneModel>`__
+- `NewReplaceOneModel() <{+godocs+}/mongo#NewReplaceOneModel>`__