DOCSP 13856: find usage example

source/code-snippets/find.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://<username>:<password>@<cluster-address>/test?w=majority"
+
+func main() {
+	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 find
+	myCollection := client.Database("sample_training").Collection("zips")
+	filter := bson.D{{"pop", bson.D{{"$lte", 500}}}}
+
+	cursor, err := myCollection.Find(context.TODO(), filter)
+	// end find
+
+	if err != nil {
+		panic(err)
+	}
+
+	var results []bson.D
+	if err = cursor.All(context.TODO(), &results); err != nil {
+		panic(err)
+	}
+	for _, result := range results {
+		fmt.Println(result)
+	}
+
+}

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/find.txt

@@ -3,3 +3,54 @@ Find Multiple Documents
 =======================
 
 .. default-domain:: mongodb
+
+You can find multiple documents in a collection by using the ``Find()``
+method.
+
+The following example passes a query filter to the ``Find()`` method,
+which matches documents in the ``zips`` collection where the value of the
+``pop`` field is less than or equal to *500*:
+
+.. include:: /includes/run-example-tip.rst
+
+.. literalinclude:: /code-snippets/find.go
+   :start-after: begin find
+   :end-before: end find
+   :emphasize-lines: 4
+   :language: go
+   :dedent:
+
+Click here **<TODO: github link to file>** to see a fully runnable example.
+
+Expected Result
+---------------
+
+This example creates a ``Cursor`` object that returns
+documents similar to these:
+
+.. code-block:: json
+   :copyable: false
+
+   // results truncated
+   ...
+   { ... , "city" : "SHAKTOOLIK", ... , "pop" : 183, "state" : "AK" },
+   { ... , "city" : "DARLINGTON", ... , "pop" : 12, "state" : "ID" },
+   { ... , "city" : "EAST BARRE", ... , "pop" : 381, "state" : "VT" },
+   ...
+
+Additional Information
+----------------------
+
+For more information on specifying query filters and
+handling potential errors, see our guide on **<TODO: retrieve data
+fundamental page>**.
+
+For more information on query operators,
+see the :manual:`MongoDB query operator reference documentation
+</reference/operator/query/>`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+- `Find() <https://pkg.go.dev/go.mongodb.org/[email protected]/mongo#Collection.Find>`_
+- `Cursor <https://pkg.go.dev/go.mongodb.org/[email protected]/mongo#Cursor>`_