DOCSP-51815 Move and standardize find usage exs

source/crud/query/retrieve.txt

@@ -62,8 +62,8 @@ consist of the ``Find()`` and ``FindOne()`` methods.
 
 .. _golang-find-example:
 
-Find All Documents
-~~~~~~~~~~~~~~~~~~
+Find Multiple Documents
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``Find()`` method expects you to pass a ``Context`` type and a
 query filter. The method returns *all* documents that match the filter
@@ -94,6 +94,67 @@ the ``Find()`` method, which performs the following actions:
 
 To learn how to access data by using a cursor, see the :ref:`golang-cursor` guide.
 
+Find Multiple Documents Example: Full File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/usage-examples/example-intro.rst
+
+The following example finds documents in the ``restaurants`` collection
+in which the ``cuisine`` is ``"Italian"``, returns a cursor that
+references the matched documents, then unpacks the documents into a slice.
+Select the **Struct** or **bson.D** tab to see the corresponding code:
+
+.. tabs::
+
+  .. tab :: Struct
+    :tabid: structExample
+
+    The following code uses structs to find documents in the ``restaurants`` collection
+    in which the ``cuisine`` is "Italian", returning all documents that match:
+
+    .. io-code-block::
+      :copyable: true
+
+      .. input:: /includes/usage-examples/code-snippets/find.go
+        :language: go
+        :dedent:
+
+      .. output::
+        :language: none
+        :visible: false
+
+        // results truncated
+        ...
+        { ... , "Name" : "Epistrophy Cafe", "RestaurantId": "41117553", "Cuisine" : "Italian", ... },
+        { ... , "Name" : "Remi", "RestaurantId": "41118090", "Cuisine" : "Italian", ... },
+        { ... , "Name" : "Sant Ambroeus", "RestaurantId": "41120682", "Cuisine" : "Italian", ... },
+        ...
+
+  .. tab :: bson.D
+    :tabid: bsonDExample
+
+    The following code uses a bson.D type to find documents in the ``restaurants`` 
+    collection in which the ``cuisine`` is "Italian", returning all documents 
+    that match:
+
+    .. io-code-block::
+      :copyable: true
+
+      .. input:: /includes/usage-examples/code-snippets/findBsonD.go
+        :language: go
+        :dedent:
+
+      .. output::
+        :language: none
+        :visible: false
+
+        // results truncated
+        ...
+        { ... , "Name" : "Epistrophy Cafe", "RestaurantId": "41117553", "Cuisine" : "Italian", ... },
+        { ... , "Name" : "Remi", "RestaurantId": "41118090", "Cuisine" : "Italian", ... },
+        { ... , "Name" : "Sant Ambroeus", "RestaurantId": "41120682", "Cuisine" : "Italian", ... },
+        ...
+
 .. _golang-find-one-example:
 
 Find One Document
@@ -182,6 +243,75 @@ as parameters to the ``FindOne()`` method to perform the following actions:
    about the ``_id`` field, see the :ref:`_id Field <golang-insert-id>`
    section of the Insert a Document page.
 
+Find One Document Example: Full File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/usage-examples/example-intro.rst
+
+The following example finds a document that matches a query filter in the 
+``restaurants`` collection. Select the **Struct** or **bson.D** tab to see the 
+corresponding code:
+
+.. tabs::
+
+  .. tab :: Struct
+    :tabid: structExample
+
+    The following code uses structs to find documents in the ``restaurants`` collection
+    in which the ``name`` is "Bagels N Buns", returning the first document
+    matched:
+
+    .. io-code-block::
+      :copyable: true
+
+      .. input:: /includes/usage-examples/code-snippets/findOne.go
+        :language: go
+        :dedent:
+
+      .. output::
+        :language: none
+        :visible: false
+
+        // results truncated
+        {
+            "ID": "5eb3d668b31de5d588f42950",
+            "Name": "Bagels N Buns",
+            "RestaurantId": "40363427"
+            "Address": [...],
+            "Borough": "Staten Island",
+            "Cuisine": "Delicatessen",
+            "Grades": [...]
+        }
+
+  .. tab :: bson.D
+    :tabid: bsonDExample
+
+    The following code uses a bson.D type to find documents in the ``restaurants`` collection
+    in which the ``name`` is "Bagels N Buns", returning the first document
+    matched:
+
+    .. io-code-block::
+      :copyable: true
+
+      .. input:: /includes/usage-examples/code-snippets/findOneBsonD.go
+        :language: go
+        :dedent:
+
+      .. output::
+        :language: none
+        :visible: false
+
+        // results truncated
+        {
+            "ID": "5eb3d668b31de5d588f42950",
+            "Name": "Bagels N Buns",
+            "RestaurantId": "40363427"
+            "Address": [...],
+            "Borough": "Staten Island",
+            "Cuisine": "Delicatessen",
+            "Grades": [...]
+        }
+
 .. _golang-retrieve-options:
 
 Modify Behavior
@@ -330,20 +460,12 @@ the MongoDB server manual page on :manual:`Aggregation
 Additional Information
 ----------------------
 
-For runnable examples of the find operations, see the following usage
-examples:
-
-- :ref:`golang-find-one`
-- :ref:`golang-find-multiple`
-
 To learn more about the operations mentioned, see the following
 guides:
 
 - :ref:`golang-query-document`
 - :ref:`golang-cursor`
-- :ref:`golang-skip`
-- :ref:`golang-sort-results`
-- :ref:`golang-limit`
+- :ref:`Specify Documents to Return <golang-specify-documents-to-return>`
 - :ref:`golang-project`
 - :ref:`golang-aggregation`
 - :ref:`golang-collations`

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

@@ -14,7 +14,7 @@ import (
 	"go.mongodb.org/mongo-driver/v2/mongo/options"
 )
 
-// start-restaurant-struct
+// Creates a Restaurant struct as a model for documents in the restaurants collection
 type Restaurant struct {
 	ID           bson.ObjectID `bson:"_id"`
 	Name         string
@@ -25,7 +25,10 @@ type Restaurant struct {
 	Grades       interface{}
 }
 
-// end-restaurant-struct
+// Creates a filter struct to use for the query
+type RestaurantCuisineFilter struct {
+	Cuisine string
+}
 
 func main() {
 	if err := godotenv.Load(); err != nil {
@@ -47,12 +50,11 @@ func main() {
 		}
 	}()
 
-	// begin find
 	coll := client.Database("sample_restaurants").Collection("restaurants")
 
 	// Creates a query filter to match documents in which the "cuisine"
 	// is "Italian"
-	filter := bson.D{{"cuisine", "Italian"}}
+	filter := RestaurantCuisineFilter{Cuisine: "Italian"}
 
 	// Retrieves documents that match the query filter
 	cursor, err := coll.Find(context.TODO(), filter)
@@ -65,7 +67,6 @@ func main() {
 	if err = cursor.All(context.TODO(), &results); err != nil {
 		panic(err)
 	}
-	// end find
 
 	// Prints the results of the find operation as structs
 	for _, result := range results {

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

@@ -0,0 +1,64 @@
+// Retrieves documents that match a query filter by using the Go driver
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/joho/godotenv"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func main() {
+	if err := godotenv.Load(); err != nil {
+		log.Println("No .env file found")
+	}
+
+	var uri string
+	if uri = os.Getenv("MONGODB_URI"); uri == "" {
+		log.Fatal("You must set your 'MONGODB_URI' environment variable. See\n\t https://www.mongodb.com/docs/drivers/go/current/connect/mongoclient/#environment-variable")
+	}
+
+	client, err := mongo.Connect(options.Client().ApplyURI(uri))
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		if err = client.Disconnect(context.TODO()); err != nil {
+			panic(err)
+		}
+	}()
+
+	coll := client.Database("sample_restaurants").Collection("restaurants")
+
+	// Creates a query filter to match documents in which the "cuisine"
+	// is "Italian"
+	filter := bson.D{{"cuisine", "Italian"}}
+
+	// Retrieves documents that match the query filter
+	cursor, err := coll.Find(context.TODO(), filter)
+	if err != nil {
+		panic(err)
+	}
+
+	// Unpacks the cursor into a slice
+	var results []Restaurant
+	if err = cursor.All(context.TODO(), &results); err != nil {
+		panic(err)
+	}
+
+	// Prints the results of the find operation as structs
+	for _, result := range results {
+		cursor.Decode(&result)
+		output, err := json.MarshalIndent(result, "", "    ")
+		if err != nil {
+			panic(err)
+		}
+		fmt.Printf("%s\n", output)
+	}
+}

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

@@ -14,7 +14,7 @@ import (
 	"go.mongodb.org/mongo-driver/v2/mongo/options"
 )
 
-// start-restaurant-struct
+// Creates a Restaurant struct as a model for documents in the restaurants collection
 type Restaurant struct {
 	ID           bson.ObjectID `bson:"_id"`
 	Name         string
@@ -25,7 +25,10 @@ type Restaurant struct {
 	Grades       []interface{}
 }
 
-// end-restaurant-struct
+// Creates a filter struct to use for the query
+type RestaurantNameFilter struct {
+	Name string
+}
 
 func main() {
 	if err := godotenv.Load(); err != nil {
@@ -47,12 +50,11 @@ func main() {
 		}
 	}()
 
-	// begin findOne
 	coll := client.Database("sample_restaurants").Collection("restaurants")
 
 	// Creates a query filter to match documents in which the "name" is
 	// "Bagels N Buns"
-	filter := bson.D{{"name", "Bagels N Buns"}}
+	filter := RestaurantNameFilter{Name: "Bagels N Buns"}
 
 	// Retrieves the first matching document
 	var result Restaurant
@@ -66,7 +68,6 @@ func main() {
 		}
 		panic(err)
 	}
-	// end findOne
 
 	output, err := json.MarshalIndent(result, "", "    ")
 	if err != nil {

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

@@ -0,0 +1,61 @@
+// Retrieves a document that matches a query filter by using the Go driver
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/joho/godotenv"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.mongodb.org/mongo-driver/v2/mongo"
+	"go.mongodb.org/mongo-driver/v2/mongo/options"
+)
+
+func main() {
+	if err := godotenv.Load(); err != nil {
+		log.Println("No .env file found")
+	}
+
+	var uri string
+	if uri = os.Getenv("MONGODB_URI"); uri == "" {
+		log.Fatal("You must set your 'MONGODB_URI' environment variable. See\n\t https://www.mongodb.com/docs/drivers/go/current/connect/mongoclient/#environment-variable")
+	}
+
+	client, err := mongo.Connect(options.Client().ApplyURI(uri))
+	if err != nil {
+		panic(err)
+	}
+	defer func() {
+		if err = client.Disconnect(context.TODO()); err != nil {
+			panic(err)
+		}
+	}()
+
+	coll := client.Database("sample_restaurants").Collection("restaurants")
+
+	// Creates a query filter to match documents in which the "name" is
+	// "Bagels N Buns"
+	filter := bson.D{{"name", "Bagels N Buns"}}
+
+	// Retrieves the first matching document
+	var result Restaurant
+	err = coll.FindOne(context.TODO(), filter).Decode(&result)
+
+	// Prints a message if no documents are matched or if any
+	// other errors occur during the operation
+	if err != nil {
+		if err == mongo.ErrNoDocuments {
+			return
+		}
+		panic(err)
+	}
+
+	output, err := json.MarshalIndent(result, "", "    ")
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("%s\n", output)
+}