DOCSP-13859: UpdateOne usage example

source/code-snippets/updateOne.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"go.mongodb.org/mongo-driver/bson"
+	"go.mongodb.org/mongo-driver/bson/primitive"
+	"go.mongodb.org/mongo-driver/mongo"
+	"go.mongodb.org/mongo-driver/mongo/options"
+)
+
+func main() {
+	// Replace the uri string with your MongoDB deployment's connection string.
+	uri := "mongodb+srv://<username>:<password>@<cluster-address>/test?w=majority"
+
+	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 updateone
+	myCollection := client.Database("sample_restaurants").Collection("restaurants")
+	id, _ := primitive.ObjectIDFromHex("5eb3d668b31de5d588f42a7a")
+	filter := bson.D{{"_id", id}}
+	update := bson.D{{"$set", bson.D{{"avg_rating", 4.4}}}}
+
+	result, err := myCollection.UpdateOne(context.TODO(), filter, update)
+	// end updateone
+
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Printf("%v document was updated.\n", result.ModifiedCount)
+}

source/includes/run-example-tip.rst

@@ -0,0 +1,4 @@
+.. tip::
+
+   Read the :doc:`Usage Examples guide </usage-examples>` to learn how
+   to run this example.

source/usage-examples.txt

@@ -7,10 +7,10 @@ Usage Examples
 .. toctree::
 
    /usage-examples/find-operations
+   /usage-examples/update-operations
 
 ..
    /usage-examples/insert-operations
-   /usage-examples/update-operations
    /usage-examples/delete-operations
    /usage-examples/bulkWrite
    /usage-examples/watch

source/usage-examples/updateOne.txt

@@ -3,3 +3,56 @@ Update a Document
 =================
 
 .. default-domain:: mongodb
+
+You can update a document in a collection by using the ``UpdateOne()``
+method. 
+
+The following example passes a query filter and an update parameter to the
+``UpdateOne()`` method, which matches a document in the ``restaurants`` collection
+by the value of its ``_id`` field and creates a new field in that document called
+``avg_rating`` with a value of *4.4*:
+
+.. include:: /includes/run-example-tip.rst
+
+.. literalinclude:: /code-snippets/updateOne.go
+   :start-after: begin updateone
+   :end-before: end updateone
+   :emphasize-lines: 6
+   :language: go
+   :dedent:
+
+Click here **<TODO: github link to file>** to see a fully runnable example.
+
+Expected Result
+---------------
+
+After you run the code example, the document will include the
+``avg_rating`` field with the specified value:
+
+.. code-block:: json
+   :copyable: false
+
+   // result truncated
+   { 
+      "_id" : ObjectId("5eb3d668b31de5d588f42a7a"),
+      ...
+      "name" : "Green House Cafe",
+      "restaurant_id" : "40372112",
+      "avg_rating" : 4.4
+   }
+
+Additional Information
+----------------------
+
+For more information on updating documents, specifying query filters, and
+handling potential errors, see our guide on **<TODO: change a document
+fundamental page>**.
+
+For more information on update operators,
+see the :manual:`MongoDB update operator reference documentation
+</reference/operator/update/#update-operators>`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+`UpdateOne() <https://pkg.go.dev/go.mongodb.org/[email protected]/mongo#Collection.UpdateOne>`_