From 7ec8f221ada2f70387f00c2f74c3ca4b4f6eaf81 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 15 Jul 2025 12:01:49 -0700 Subject: [PATCH 1/5] move usag examples and add bsond --- source/crud/insert.txt | 55 ++++++++++++++++ .../code-snippets/insertMany.go | 8 +-- .../code-snippets/insertManyBsonD.go | 64 +++++++++++++++++++ .../usage-examples/code-snippets/insertOne.go | 8 +-- .../code-snippets/insertOneBsonD.go | 53 +++++++++++++++ 5 files changed, 176 insertions(+), 12 deletions(-) create mode 100644 source/includes/usage-examples/code-snippets/insertManyBsonD.go create mode 100644 source/includes/usage-examples/code-snippets/insertOneBsonD.go diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 6ce815b7..76092bd3 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -133,6 +133,36 @@ Construct an ``InsertOneOptions`` as follows: :copyable: :dedent: +Insert a Document Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/usage-examples/example-intro.rst + +The following example inserts a new document into the ``restaurants`` collection. +Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Struct + :tabid: structExample + + The following code uses a struct to insert a new document into the + ``restaurants`` collection: + + .. literalinclude:: /includes/usage-examples/code-snippets/insertOne.go + :language: go + :dedent: + + .. tab:: bson.D + :tabid: bsonDExample + + The following code uses a ``bson.D`` type to insert a new document into the + ``restaurants`` collection: + + .. literalinclude:: /includes/usage-examples/code-snippets/insertOneBsonD.go + :language: go + :dedent: + Insert Multiple Documents ------------------------- @@ -280,6 +310,31 @@ inserted into your collection. { "_id": 1, "title": "Where the Wild Things Are" } { "_id": 2, "title": "The Very Hungry Caterpillar" } +Insert Many Example: Full File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/usage-examples/example-intro.rst + +The following example inserts multiple new documents into the ``restaurants`` collection. +Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Struct + :tabid: structExample + + The following code uses a struct to insert multiple new documents into the + ``restaurants`` collection: + + .. literalinclude:: /includes/usage-examples/code-snippets/insertMany.go + + .. tab:: bson.D + :tabid: bsonDExample + + The following code uses a ``bson.D`` type to insert multiple new documents into the + ``restaurants`` collection: + + .. literalinclude:: /includes/usage-examples/code-snippets/insertManyBsonD.go Additional Information ---------------------- diff --git a/source/includes/usage-examples/code-snippets/insertMany.go b/source/includes/usage-examples/code-snippets/insertMany.go index 577dab73..34a1b9d9 100644 --- a/source/includes/usage-examples/code-snippets/insertMany.go +++ b/source/includes/usage-examples/code-snippets/insertMany.go @@ -12,7 +12,7 @@ import ( "go.mongodb.org/mongo-driver/v2/mongo/options" ) -// start-restaurant-struct +// Defines the structure of a restaurant document type Restaurant struct { Name string RestaurantId string `bson:"restaurant_id,omitempty"` @@ -22,8 +22,6 @@ type Restaurant struct { Grades []interface{} `bson:"grades,omitempty"` } -// end-restaurant-struct - func main() { if err := godotenv.Load(); err != nil { log.Println("No .env file found") @@ -44,7 +42,6 @@ func main() { } }() - // begin insertMany coll := client.Database("sample_restaurants").Collection("restaurants") // Creates two sample documents describing restaurants @@ -58,7 +55,6 @@ func main() { if err != nil { panic(err) } - // end insertMany // Prints the IDs of the inserted documents fmt.Printf("%d documents inserted with IDs:\n", len(result.InsertedIDs)) @@ -66,6 +62,6 @@ func main() { fmt.Printf("\t%s\n", id) } - // When you run this file, it should print: + // When you run this file, the expected output is similar to: // 2 documents inserted with IDs: ObjectID("..."), ObjectID("...") } diff --git a/source/includes/usage-examples/code-snippets/insertManyBsonD.go b/source/includes/usage-examples/code-snippets/insertManyBsonD.go new file mode 100644 index 00000000..2be7a383 --- /dev/null +++ b/source/includes/usage-examples/code-snippets/insertManyBsonD.go @@ -0,0 +1,64 @@ +// Inserts sample documents describing restaurants by using the Go driver with bson.D +package main + +import ( + "context" + "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 two sample documents describing restaurants using bson.D + newRestaurants := []interface{}{ + bson.D{ + bson.E{Key: "name", Value: "Rule of Thirds"}, + bson.E{Key: "cuisine", Value: "Japanese"}, + }, + bson.D{ + bson.E{Key: "name", Value: "Madame Vo"}, + bson.E{Key: "cuisine", Value: "Vietnamese"}, + }, + } + + // Inserts sample documents into the collection + result, err := coll.InsertMany(context.TODO(), newRestaurants) + if err != nil { + panic(err) + } + + // Prints the IDs of the inserted documents + fmt.Printf("%d documents inserted with IDs:\n", len(result.InsertedIDs)) + for _, id := range result.InsertedIDs { + fmt.Printf("\t%s\n", id) + } + + // When you run this file, the expected output is similar to: + // 2 documents inserted with IDs: ObjectID("..."), ObjectID("...") +} diff --git a/source/includes/usage-examples/code-snippets/insertOne.go b/source/includes/usage-examples/code-snippets/insertOne.go index 41493f85..75f27958 100644 --- a/source/includes/usage-examples/code-snippets/insertOne.go +++ b/source/includes/usage-examples/code-snippets/insertOne.go @@ -12,7 +12,7 @@ import ( "go.mongodb.org/mongo-driver/v2/mongo/options" ) -// start-restaurant-struct +// Defines the structure of a restaurant documen type Restaurant struct { Name string RestaurantId string `bson:"restaurant_id,omitempty"` @@ -22,8 +22,6 @@ type Restaurant struct { Grades []interface{} `bson:"grades,omitempty"` } -// end-restaurant-struct - func main() { if err := godotenv.Load(); err != nil { log.Println("No .env file found") @@ -45,7 +43,6 @@ func main() { }() // Inserts a sample document describing a restaurant into the collection - // begin insertOne coll := client.Database("sample_restaurants").Collection("restaurants") newRestaurant := Restaurant{Name: "8282", Cuisine: "Korean"} @@ -53,11 +50,10 @@ func main() { if err != nil { panic(err) } - // end insertOne // Prints the ID of the inserted document fmt.Printf("Document inserted with ID: %s\n", result.InsertedID) - // When you run this file, it should print: + // When you run this file, the expected output is similar to: // Document inserted with ID: ObjectID("...") } diff --git a/source/includes/usage-examples/code-snippets/insertOneBsonD.go b/source/includes/usage-examples/code-snippets/insertOneBsonD.go new file mode 100644 index 00000000..53be818f --- /dev/null +++ b/source/includes/usage-examples/code-snippets/insertOneBsonD.go @@ -0,0 +1,53 @@ +// Inserts a single document describing a restaurant by using the Go driver with bson.D +package main + +import ( + "context" + "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) + } + }() + + // Inserts a sample document describing a restaurant into the collection using bson.D + coll := client.Database("sample_restaurants").Collection("restaurants") + newRestaurant := bson.D{ + bson.E{Key: "name", Value: "8282"}, + bson.E{Key: "cuisine", Value: "Korean"}, + } + + result, err := coll.InsertOne(context.TODO(), newRestaurant) + if err != nil { + panic(err) + } + + // Prints the ID of the inserted document + fmt.Printf("Document inserted with ID: %s\n", result.InsertedID) + + // When you run this file, the expected output is similar to: + // Document inserted with ID: ObjectID("...") +} From afa26b3e2486af6234bc3bcc73f19fee0ce34bd8 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 15 Jul 2025 12:50:54 -0700 Subject: [PATCH 2/5] fix formatting --- source/crud/insert.txt | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 76092bd3..8eaa732f 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -150,8 +150,8 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding ``restaurants`` collection: .. literalinclude:: /includes/usage-examples/code-snippets/insertOne.go - :language: go - :dedent: + :language: go + :dedent: .. tab:: bson.D :tabid: bsonDExample @@ -160,8 +160,8 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding ``restaurants`` collection: .. literalinclude:: /includes/usage-examples/code-snippets/insertOneBsonD.go - :language: go - :dedent: + :language: go + :dedent: Insert Multiple Documents ------------------------- @@ -327,6 +327,8 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding ``restaurants`` collection: .. literalinclude:: /includes/usage-examples/code-snippets/insertMany.go + :language: go + :dedent: .. tab:: bson.D :tabid: bsonDExample @@ -335,6 +337,8 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding ``restaurants`` collection: .. literalinclude:: /includes/usage-examples/code-snippets/insertManyBsonD.go + :language: go + :dedent: Additional Information ---------------------- From 5e800e17b8774c6b5886c4506f3768857e2e490b Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 15 Jul 2025 13:05:31 -0700 Subject: [PATCH 3/5] add expected output --- source/crud/insert.txt | 76 ++++++++++++++++--- .../code-snippets/insertMany.go | 2 - .../code-snippets/insertManyBsonD.go | 2 - .../usage-examples/code-snippets/insertOne.go | 2 - .../code-snippets/insertOneBsonD.go | 2 - 5 files changed, 64 insertions(+), 20 deletions(-) diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 8eaa732f..7b2dac49 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -149,9 +149,21 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding The following code uses a struct to insert a new document into the ``restaurants`` collection: - .. literalinclude:: /includes/usage-examples/code-snippets/insertOne.go - :language: go - :dedent: + .. io-code-block:: + :copyable: true + + .. input:: + :language: go + + .. literalinclude:: /includes/usage-examples/code-snippets/insertOne.go + :language: go + :dedent: + + .. output:: + :language: none + :visible: false + + Document inserted with ID: ObjectID("...") .. tab:: bson.D :tabid: bsonDExample @@ -159,9 +171,21 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding The following code uses a ``bson.D`` type to insert a new document into the ``restaurants`` collection: - .. literalinclude:: /includes/usage-examples/code-snippets/insertOneBsonD.go - :language: go - :dedent: + .. io-code-block:: + :copyable: true + + .. input:: + :language: go + + .. literalinclude:: /includes/usage-examples/code-snippets/insertOneBsonD.go + :language: go + :dedent: + + .. output:: + :language: none + :visible: false + + Document inserted with ID: ObjectID("...") Insert Multiple Documents ------------------------- @@ -326,9 +350,23 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding The following code uses a struct to insert multiple new documents into the ``restaurants`` collection: - .. literalinclude:: /includes/usage-examples/code-snippets/insertMany.go - :language: go - :dedent: + .. io-code-block:: + :copyable: true + + .. input:: + :language: go + + .. literalinclude:: /includes/usage-examples/code-snippets/insertMany.go + :language: go + :dedent: + + .. output:: + :language: none + :visible: false + + 2 documents inserted with IDs: + ObjectID("...") + ObjectID("...") .. tab:: bson.D :tabid: bsonDExample @@ -336,9 +374,23 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding The following code uses a ``bson.D`` type to insert multiple new documents into the ``restaurants`` collection: - .. literalinclude:: /includes/usage-examples/code-snippets/insertManyBsonD.go - :language: go - :dedent: + .. io-code-block:: + :copyable: true + + .. input:: + :language: go + + .. literalinclude:: /includes/usage-examples/code-snippets/insertManyBsonD.go + :language: go + :dedent: + + .. output:: + :language: none + :visible: false + + 2 documents inserted with IDs: + ObjectID("...") + ObjectID("...") Additional Information ---------------------- diff --git a/source/includes/usage-examples/code-snippets/insertMany.go b/source/includes/usage-examples/code-snippets/insertMany.go index 34a1b9d9..66693954 100644 --- a/source/includes/usage-examples/code-snippets/insertMany.go +++ b/source/includes/usage-examples/code-snippets/insertMany.go @@ -62,6 +62,4 @@ func main() { fmt.Printf("\t%s\n", id) } - // When you run this file, the expected output is similar to: - // 2 documents inserted with IDs: ObjectID("..."), ObjectID("...") } diff --git a/source/includes/usage-examples/code-snippets/insertManyBsonD.go b/source/includes/usage-examples/code-snippets/insertManyBsonD.go index 2be7a383..b29d5859 100644 --- a/source/includes/usage-examples/code-snippets/insertManyBsonD.go +++ b/source/includes/usage-examples/code-snippets/insertManyBsonD.go @@ -59,6 +59,4 @@ func main() { fmt.Printf("\t%s\n", id) } - // When you run this file, the expected output is similar to: - // 2 documents inserted with IDs: ObjectID("..."), ObjectID("...") } diff --git a/source/includes/usage-examples/code-snippets/insertOne.go b/source/includes/usage-examples/code-snippets/insertOne.go index 75f27958..a9d8deae 100644 --- a/source/includes/usage-examples/code-snippets/insertOne.go +++ b/source/includes/usage-examples/code-snippets/insertOne.go @@ -54,6 +54,4 @@ func main() { // Prints the ID of the inserted document fmt.Printf("Document inserted with ID: %s\n", result.InsertedID) - // When you run this file, the expected output is similar to: - // Document inserted with ID: ObjectID("...") } diff --git a/source/includes/usage-examples/code-snippets/insertOneBsonD.go b/source/includes/usage-examples/code-snippets/insertOneBsonD.go index 53be818f..ad96b869 100644 --- a/source/includes/usage-examples/code-snippets/insertOneBsonD.go +++ b/source/includes/usage-examples/code-snippets/insertOneBsonD.go @@ -48,6 +48,4 @@ func main() { // Prints the ID of the inserted document fmt.Printf("Document inserted with ID: %s\n", result.InsertedID) - // When you run this file, the expected output is similar to: - // Document inserted with ID: ObjectID("...") } From bd6295a893a88c0f28e87dba443d50fd5b394c92 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 15 Jul 2025 13:16:09 -0700 Subject: [PATCH 4/5] fix path --- source/crud/insert.txt | 28 ++++++++-------------------- 1 file changed, 8 insertions(+), 20 deletions(-) diff --git a/source/crud/insert.txt b/source/crud/insert.txt index 7b2dac49..b825eb36 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -152,12 +152,9 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding .. io-code-block:: :copyable: true - .. input:: + .. input:: /includes/usage-examples/code-snippets/insertOne.go :language: go - - .. literalinclude:: /includes/usage-examples/code-snippets/insertOne.go - :language: go - :dedent: + :dedent: .. output:: :language: none @@ -174,12 +171,9 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding .. io-code-block:: :copyable: true - .. input:: + .. input:: /includes/usage-examples/code-snippets/insertOneBsonD.go :language: go - - .. literalinclude:: /includes/usage-examples/code-snippets/insertOneBsonD.go - :language: go - :dedent: + :dedent: .. output:: :language: none @@ -353,12 +347,9 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding .. io-code-block:: :copyable: true - .. input:: + .. input:: /includes/usage-examples/code-snippets/insertMany.go :language: go - - .. literalinclude:: /includes/usage-examples/code-snippets/insertMany.go - :language: go - :dedent: + :dedent: .. output:: :language: none @@ -377,12 +368,9 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding .. io-code-block:: :copyable: true - .. input:: + .. input:: /includes/usage-examples/code-snippets/insertManyBsonD.go :language: go - - .. literalinclude:: /includes/usage-examples/code-snippets/insertManyBsonD.go - :language: go - :dedent: + :dedent: .. output:: :language: none From f99391903f529bcdf415632fe40faaf37d91397b Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Tue, 15 Jul 2025 16:28:19 -0700 Subject: [PATCH 5/5] lm feedback --- source/crud/insert.txt | 22 +++++++------------ .../usage-examples/code-snippets/insertOne.go | 2 +- 2 files changed, 9 insertions(+), 15 deletions(-) diff --git a/source/crud/insert.txt b/source/crud/insert.txt index b825eb36..df8e2a9f 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -36,8 +36,8 @@ To learn how to use the ``BulkWrite()`` method, see the .. _golang-insert-id: -The ``_id`` Field ------------------ +The _id Field +------------- In MongoDB, each document *must* contain a unique ``_id`` field. @@ -105,8 +105,8 @@ The following example creates and inserts a document into the Inserted document with _id: ObjectID("...") -Modify ``InsertOne`` Behavior -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modify InsertOne() Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can modify the behavior of ``InsertOne()`` by constructing and passing an optional ``InsertOneOptions`` struct. The available options to set with ``InsertOneOptions`` are: @@ -222,8 +222,8 @@ After running the preceding code, your output resembles the following: Inserted document with _id: ObjectID("...") Inserted document with _id: ObjectID("...") -Modify ``InsertMany`` Behavior -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modify InsertMany() Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can modify the behavior of ``InsertMany()`` by constructing and passing an optional ``InsertManyOptions`` struct. The available options @@ -260,8 +260,8 @@ Construct an ``InsertManyOptions`` as follows: .. _golang-ordered-behavior: -``Ordered`` Behavior -~~~~~~~~~~~~~~~~~~~~ +Ordered Behavior +~~~~~~~~~~~~~~~~ Assume you want to insert the following documents: @@ -383,12 +383,6 @@ Select the :guilabel:`Struct` or :guilabel:`bson.D` tab to see the corresponding Additional Information ---------------------- -For runnable examples of the insert operations, see the following usage -examples: - -- :ref:`golang-insert-one` -- :ref:`golang-insert-many` - To learn more about performing the operations mentioned, see the following guides: diff --git a/source/includes/usage-examples/code-snippets/insertOne.go b/source/includes/usage-examples/code-snippets/insertOne.go index a9d8deae..4232cb2d 100644 --- a/source/includes/usage-examples/code-snippets/insertOne.go +++ b/source/includes/usage-examples/code-snippets/insertOne.go @@ -12,7 +12,7 @@ import ( "go.mongodb.org/mongo-driver/v2/mongo/options" ) -// Defines the structure of a restaurant documen +// Defines the structure of a restaurant document type Restaurant struct { Name string RestaurantId string `bson:"restaurant_id,omitempty"`