diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt index ae6603f3..5d1cb4ae 100644 --- a/source/crud/query/retrieve.txt +++ b/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,33 @@ 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 all documents in the ``restaurants`` collection +in which the value of ``cuisine`` is ``"Italian"``. The example returns a cursor that +references the matched documents and unpacks the documents into a slice: + +.. 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", ... }, + ... + .. _golang-find-one-example: Find One Document @@ -182,6 +209,36 @@ as parameters to the ``FindOne()`` method to perform the following actions: about the ``_id`` field, see the :ref:`_id Field ` section of the Insert a Document page. +Find One Document Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/usage-examples/example-intro.rst + +The following example finds and returns the first document in the +``restaurants`` collection in which the value of ``name`` is ``"Bagels N Buns"``: + +.. 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": [...] + } + .. _golang-retrieve-options: Modify Behavior @@ -330,20 +387,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 ` - :ref:`golang-project` - :ref:`golang-aggregation` - :ref:`golang-collations` diff --git a/source/includes/usage-examples/code-snippets/find.go b/source/includes/usage-examples/code-snippets/find.go index a70573c8..97ad4833 100644 --- a/source/includes/usage-examples/code-snippets/find.go +++ b/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,8 +25,6 @@ type Restaurant struct { Grades interface{} } -// end-restaurant-struct - func main() { if err := godotenv.Load(); err != nil { log.Println("No .env file found") @@ -47,7 +45,6 @@ func main() { } }() - // begin find coll := client.Database("sample_restaurants").Collection("restaurants") // Creates a query filter to match documents in which the "cuisine" @@ -65,11 +62,9 @@ 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 { - cursor.Decode(&result) output, err := json.MarshalIndent(result, "", " ") if err != nil { panic(err) diff --git a/source/includes/usage-examples/code-snippets/findOne.go b/source/includes/usage-examples/code-snippets/findOne.go index e3ba4447..4483e7ba 100644 --- a/source/includes/usage-examples/code-snippets/findOne.go +++ b/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,8 +25,6 @@ type Restaurant struct { Grades []interface{} } -// end-restaurant-struct - func main() { if err := godotenv.Load(); err != nil { log.Println("No .env file found") @@ -47,7 +45,6 @@ func main() { } }() - // begin findOne coll := client.Database("sample_restaurants").Collection("restaurants") // Creates a query filter to match documents in which the "name" is @@ -66,7 +63,6 @@ func main() { } panic(err) } - // end findOne output, err := json.MarshalIndent(result, "", " ") if err != nil {