Docsp 13855 usage example find a doc (#2)

Docsp 13855 Usage Example Find a Document
Co-authored-by: Chris Cho <[email protected]>
Co-authored-by: Kevin Albertson <[email protected]>
Co-authored-by: Isabella Siu <[email protected]>

Author: 4 people

source/fundamentals/context.txt

@@ -0,0 +1 @@
+TODO: Discussion of the ``context`` package

source/includes/sample-data-note.rst

@@ -0,0 +1,5 @@
+.. note::
+   
+    This example uses the MongoDB Atlas sample dataset.
+    You can learn how to set up a free-tier Atlas cluster with the sample
+    dataset by following our :doc:`quick start guide </quick-start>`.

source/usage-examples.txt

@@ -6,8 +6,9 @@ Usage Examples
 
 .. toctree::
 
-..
    /usage-examples/find-operations
+
+..
    /usage-examples/insert-operations
    /usage-examples/update-operations
    /usage-examples/delete-operations

source/usage-examples/findOne-output.txt

@@ -0,0 +1 @@
+{"title":"The Room","imdb":{"rating":3.5,"votes":25673,"id":368226}}

source/usage-examples/findOne.go

@@ -0,0 +1,46 @@
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"go.mongodb.org/mongo-driver/bson"
+	"go.mongodb.org/mongo-driver/mongo"
+	"go.mongodb.org/mongo-driver/mongo/options"
+)
+
+// Replace the uri string with your MongoDB deployment's connection string.
+const uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority"
+
+func main() {
+	ctx := context.TODO()
+	client, err := mongo.Connect(ctx, options.Client().ApplyURI(uri))
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		if err = client.Disconnect(ctx); err != nil {
+			panic(err)
+		}
+	}()
+
+	coll := client.Database("sample_mflix").Collection("movies")
+	var result bson.D
+	opts := options.FindOne().
+		SetProjection(bson.D{{"_id", 0}, {"title", 1}, {"imdb", 1}}).
+		SetSort(bson.D{{"imdb.rating", -1}})
+	err = coll.FindOne(ctx, bson.D{{"title", "The Room"}}, opts).Decode(&result)
+	if err != nil {
+		if err == mongo.ErrNoDocuments {
+			// This error means your query did not match any documents.
+			return
+		}
+		panic(err)
+	}
+
+	relaxedJSONBytes, err := bson.MarshalExtJSON(result, false, false)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("%s\n", relaxedJSONBytes)
+}

source/usage-examples/findOne.txt

@@ -3,3 +3,103 @@ Find a Document
 ===============
 
 .. default-domain:: mongodb
+
+You can retrieve a single document from your collection with the
+``Collection.FindOne()`` method. 
+
+..
+   method
+
+The ``FindOne()`` method takes a filter document. Calling the ``FindOne()``
+method retrieves a document from your MongoDB instance that matches your
+filter document. If you pass the ``FindOne()`` method an empty filter document,
+MongoDB considers your entire collection when retrieving your document. For more
+information on documents in the MongoDB Go driver, see our
+:doc:`guide on data formats </fundamentals/data-formats>`.
+
+You must pass the ``FindOne()`` method a ``context.Context`` interface type
+value. For more information on the ``context.Context`` interface and the
+``context`` package, see our :doc:`guide on contexts </fundamentals/context>`.
+
+..
+   options
+
+You can specify options that change the behavior of the ``FindOne()`` method.
+One example of an option is **sort**, which instructs your MongoDB instance to
+order the matching documents of your collection before it retrieves the
+first document. Another example of an option is a **projection**, which
+specifies or restricts the fields in your returned document. You can specify
+options by passing the ``FindOne()`` method a pointer to a ``FindOneOptions`` struct.  
+You can configure a ``FindOneOptions`` struct by using setter methods such as the
+``FindOneOptions.SetProjection()`` method. For more information on the sort option,
+:doc:`see our guide on sorting </fundamentals/crud/read-operations/sort/>`.
+For more information on the projection option, 
+:doc:`see our guide on projections </fundamentals/crud/read-operations/project/>`.  
+
+..
+   return
+
+If the query filter you specified in your ``FindOne()`` method call matches one
+or more documents in your collection, it returns the first matched result. The
+return type ``SingleResult`` represents a single document returned from a query
+to a MongoDB instance. You can call the ``SingleResult.Decode()`` method
+to unmarshal a ``SingleResult`` struct type into a variable. Pass the ``Decode()`` 
+method a pointer to the variable that you would like to contain your returned
+document. 
+
+..
+   error 
+
+When you call the ``Decode()`` method to unmarshal your result, the method
+returns an ``error`` interface type which can contain one of the following
+values: 
+
+- ``nil`` if a document matched your query, and there were no errors retrieving
+  the document. 
+- ``ErrNoDocuments`` if no documents matched your query.
+- If the driver retrieved your document but could not unmarshal your result, the
+  ``Decode()`` method returns the unmarshaling error.
+- If there was an error retrieving your document during execution of the
+  ``FindOne()`` method, the error propagates to the ``Decode()`` method and
+  the ``Decode()`` method returns the error. 
+
+Example
+-------
+
+The following code example retrieves a single document from the ``movies``
+collection. It uses the following arguments for the ``FindOne()`` method:
+
+- An empty **Context** instance returned from the ``context.TODO()`` function.
+- A **filter document** that only matches movies with the title exactly matching
+  the text ``"The Room"``.
+- **Options** that specify a **sort** of matched documents in
+  descending order by rating, such that the first document has the highest
+  rating. The options also specify a **projection** for the results so
+  that the MongoDB instance only sends the ``title`` and ``imdb`` fields of
+  the retrieved document.
+
+.. include:: /includes/connect-guide-note.rst
+
+.. literalinclude:: findOne.go
+   :language: go
+
+If you run the example above, you should see a result that looks like this:
+
+.. literalinclude:: findOne-output.txt
+   :language: none
+
+.. include:: /includes/sample-data-note.rst
+
+For more information on the methods, interfaces, structs, and functions
+mentioned on this page, see the following API documentation:
+
+- :go-api:`Collection.FindOne() <mongo#Collection.FindOne>`
+- `Context <https://pkg.go.dev/context#Context>`__
+- :go-api:`FindOneOptions <mongo/options#FindOneOptions>`
+- :go-api:`FindOneOptions.SetProjection() <mongo/options#FindOneOptions.SetProjection>`
+- :go-api:`options.FindOne() <mongo/options#FindOne>`
+- :go-api:`SingleResult <mongo#SingleResult>`
+- :go-api:`SingleResult.Decode() <mongo#SingleResult.Decode>`
+- `context.TODO() <https://pkg.go.dev/context#TODO>`__
+- :go-api:`bson.D <bson#D>`
+- :go-api:`bson.MarshalExtJSON() <bson#MarshalExtJSON>`