quick-reference.txt

.. _golang-quick-reference:

===============
Quick Reference
===============

.. meta::
   :description: Explore with the MongoDB Go Driver syntax for various commands, including find, insert, update, delete, and more, with links to API documentation and usage examples.

.. default-domain:: mongodb

This page shows the driver syntax for several MongoDB commands and links to
their related reference and API documentation.

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Command
     - Syntax

   * - | **Find a Document**
       |
       | `API Documentation <{+api+}/mongo#Collection.FindOne>`__
       | :ref:`Usage Example <golang-find-one>`
       | :ref:`Fundamentals <golang-retrieve>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             err = coll.FindOne(context.TODO(), bson.D{{"firstName", Mike}}).Decode(&result)

          .. output::
             :language: go
             :visible: false 

             [{firstName Mike}, {lastName Smith} ...]

   * - | **Find Multiple Documents**
       |
       | `API Documentation <{+api+}/mongo#Collection.Find>`__
       | :ref:`Usage Example <golang-find-multiple>`
       | :ref:`Fundamentals <golang-retrieve>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             cursor, err := coll.Find(context.TODO(), bson.D{{"age", bson.D{{"$gte", 46}}}})

          .. output::
             :language: go
             :visible: false 

             [{firstName Kyle}, {age 51}, ... ]
             [{firstName Omar}, {age 47}, ... ]

   * - | **Insert a Document**
       |
       | `API Documentation <{+api+}/mongo#Collection.InsertOne>`__
       | :ref:`Usage Example <golang-insert-one>`
       | :ref:`Fundamentals <golang-insert-guide>`

     - .. code-block:: go
          :copyable: true

          result, err := coll.InsertOne(
              context.TODO(), 
              bson.D{
                  {"animal", "Dog"}, 
                  {"breed", "Beagle"} 
              }
          )

   * - | **Insert Multiple Documents**
       |
       | `API Documentation <{+api+}/mongo#Collection.InsertMany>`__
       | :ref:`Usage Example <golang-insert-many>`
       | :ref:`Fundamentals <golang-insert-guide>`

     - .. code-block:: go
          :copyable: true

          docs := []interface{} {
              bson.D{{"firstName", "Erik"}, {"age", 27}},
              bson.D{{"firstName", "Mohammad"}, {"lastName", "Ahmad"}, {"age", 10}},
              bson.D{{"firstName", "Todd"}},
              bson.D{{"firstName", "Juan"}, {"lastName", "Pablo"}}
           }

          result, err := coll.InsertMany(context.TODO(), docs)

   * - | **Update a Document**
       |
       | `API Documentation <{+api+}/mongo#Collection.UpdateOne>`__
       | :ref:`Usage Example <golang-update-one>`
       | :ref:`Fundamentals <golang-update-documents>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             result, err := coll.UpdateOne(
                 context.TODO(), 
                 bson.D{{"firstName", "Erik"}}, 
                 bson.D{{"$set", bson.D{{"age", 28}}}}
             )
             fmt.Printf("The number of modified documents: %d\n", result.ModifiedCount)
		
          .. output::
             :language: go
             :visible: false 

             The number of modified documents: 1

   * - | **Update Multiple Documents**
       |
       | `API Documentation <{+api+}/mongo#Collection.UpdateMany>`__
       | :ref:`Usage Example <golang-update-many>`
       | :ref:`Fundamentals <golang-update-documents>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             result, err := coll.UpdateMany(
                 context.TODO(), 
                 bson.D{{"age", bson.D{{"$gte", 58}}}}, 
                 bson.D{{"$set", bson.D{{"description", "Senior"}}}}
             )
             fmt.Printf("The number of modified documents: %d\n", result.ModifiedCount)

          .. output::
             :language: go
             :visible: false 

             The number of modified documents: 4

   * - | **Update Arrays in Documents**
       |
       | `API Documentation <{+api+}/mongo#Collection.UpdateMany>`__
       | :ref:`Fundamentals <golang-update-arrays>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             result, err := coll.UpdateMany(
                 context.TODO(), 
                 bson.D{}, 
                 bson.D{{"$push", bson.D{{family, "brother"}}}}
             )

          .. output::
             :language: go
             :visible: false 

             [{firstName Xiao}, {family ["brother"]}, ... ]
             [{firstName Omar}, {family ["brother", "mother"]}, ... ]
             ...

   * - | **Replace a Document**
       |
       | `API Documentation <{+api+}/mongo#Collection.ReplaceOne>`__
       | :ref:`Usage Example <golang-replace>`
       | :ref:`Fundamentals <golang-replacement-document>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             result, err := coll.ReplaceOne(
                 context.TODO(), 
                 bson.D{{"firstName", "Mick"}}, 
                 bson.D{{"firstName", "Mike"}, {"lastName", "Doe"}}
             )

          .. output::
             :language: go
             :visible: false 

             [{{firstName Mike}, {lastName Doe} }]

   * - | **Delete a Document**
       |
       | `API Documentation <{+api+}/mongo#Collection.DeleteOne>`__
       | :ref:`Usage Example <golang-delete-one>`
       | :ref:`Fundamentals <golang-delete-guide>`

     - .. code-block:: go
          :copyable: true

          result, err := coll.DeleteOne(
              context.TODO(), 
              bson.D{{"firstName", "Xiao"}}
          )

   * - | **Delete Multiple Documents**
       |
       | `API Documentation <{+api+}/mongo#Collection.DeleteMany>`__
       | :ref:`Usage Example <golang-delete-many>`
       | :ref:`Fundamentals <golang-delete-guide>`

     - .. code-block:: go
          :copyable: true

          results, err := coll.DeleteMany(
              context.TODO(), 
              bson.D{{"age", bson.D{{"$lte", 12}}}}
          )

   * - | **Bulk Write**
       |
       | `API Documentation <{+api+}/mongo#Collection.BulkWrite>`__
       | :ref:`Usage Example <golang-bulk-ops-usage-example>`
       | :ref:`Fundamentals <golang-bulk>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go 

             models := []mongo.WriteModel{
                 mongo.NewInsertOneModel().SetDocument(bson.D{{"firstName", "John"}, {"age", 5}}),
                 mongo.NewUpdateOneModel().SetFilter(bson.D{{"firstName", "Juan"}}).
                     SetUpdate(bson.D{{"$set", bson.D{{"age", 12}}}}),
             }
             opts := options.BulkWrite().SetOrdered(true)

             results, err := coll.BulkWrite(context.TODO(), models, opts)

          .. output::
             :language: go
             :visible: false

             [{firstName John}, {age 5} ... ]
             [{firstName Juan}, {age 12} ... ]

   * - | **Monitor Data Changes**
       |
       | `API Documentation <{+api+}/mongo#Collection.Watch>`__
       | :ref:`Usage Example <golang-usageex-monitor-changes>`

     - .. code-block:: go
          :copyable: true

          pipeline := mongo.Pipeline{bson.D{{"$match", bson.D{{"operationType", "insert"}}}}}
          cs, err := coll.Watch(context.TODO(), pipeline)

   * - | **Access Data from a Cursor Iteratively**
       |
       | `API Documentation <{+api+}/mongo#Cursor.Next>`__
       | :ref:`Fundamentals <golang-individual-documents>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             cursor, err := coll.Find(context.TODO(), bson.D{})

             for cursor.Next(context.TODO()) {
                 var result bson.D
                 if err := cursor.Decode(&result); err != nil {
                     log.Fatal(err)
                 }
                 fmt.Println(result)
             }

          .. output::
             :language: go
             :visible: false 

             [{firstName Doug} ... ]
             [{firstName Erik} ...]
             [{lastName Chang} ...]
             ...

   * - | **Access Data from a Cursor as an Array**
       |
       | `API Documentation <{+api+}/mongo#Cursor.All>`__
       | :ref:`Fundamentals <golang-all-documents>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             cursor, err := coll.Find(context.TODO(), bson.D{})

             var results []bson.D
             if err = cursor.All(context.TODO(), &results); err != nil {
                 panic(err)
             }

          .. output::
             :language: go
             :visible: false 

             [{name Mike} ... ]
             [{name Edgar} ...]
             [{name Freddie} ...]
             ...

   * - | **Count Documents**
       |
       | `API Documentation <{+api+}/mongo#Collection.CountDocuments>`__
       | :ref:`Usage Example <golang-count-usage-example>`
       | :ref:`Fundamentals <golang-count-documents>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             count, err := coll.CountDocuments(context.TODO(), bson.D{})

          .. output::
             :language: go
             :visible: false 

             6

   * - | **List the Distinct Documents or Field Values**
       | `API Documentation <{+api+}/mongo#Collection.Distinct>`__
       | :ref:`Usage Example <golang-distinct-usage-example>`
       | :ref:`Fundamentals <golang-retrieve-distinct>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             var results []string
             err = coll.Distinct(context.TODO(), "firstName", bson.D{}).Decode(&results)

          .. output::
             :language: go
             :visible: false 
             
             [Mike Xiao Sandy ...]

   * - | **Limit the Number of Documents Retrieved**
       |
       | `API Documentation <{+api+}/mongo/options#FindOptionsBuilder.SetLimit>`__
       | :ref:`Fundamentals <golang-limit>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             cursor, err := coll.Find(context.TODO(), bson.D{}, options.Find().SetLimit(2))

          .. output::
             :language: go
             :visible: false 

             [{breed Beagle} ... ]
             [{breed German Shepard} ...]

   * - | **Skip Retrieved Documents**
       |
       | `API Documentation <{+api+}/mongo/options#FindOptionsBuilder.SetSkip>`__
       | :ref:`Fundamentals <golang-skip>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go
             
             // the collection has 6 documents
             cursor, err := coll.Find(context.TODO(), bson.D{}, options.Find().SetSkip(4))

          .. output::
             :language: go
             :visible: false 

             [{item Pen} ... ]
             [{item Chair} ...]

   * - | **Sort the Documents When Retrieving Them**
       |
       | `API Documentation <{+api+}/mongo/options#FindOptionsBuilder.SetSort>`__
       | :ref:`Fundamentals <golang-sort-results>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             cursor, err := coll.Find(context.TODO(), bson.D{}, options.Find().SetSort(bson.D{{"age", 1}}))

          .. output::
             :language: go
             :visible: false 

             [{firstName Dev} {age 5} ... ]
             [{firstName Jose} {age 7} ... ]
             [{firstName Om} {age 8} ... ]

   * - | **Project Document Fields When Retrieving Them**
       |
       | `API Documentation <{+api+}/mongo/options#FindOptionsBuilder.SetProjection>`__
       | :ref:`Fundamentals <golang-project>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             cursor, err := coll.Find(
                 context.TODO(), 
                 bson.D{},
                 options.Find().SetProjection(
                     bson.D{{"age", 0}, {"_id",0}}
                 )
             )

          .. output::
             :language: go
             :visible: false 

             [{firstName Lester}]
             [{firstName Wendall} {lastName Griffin}]
             ...

   * - | **Create an Index**
       |
       | `API Documentation <{+api+}/mongo#IndexView.CreateOne>`__
       | :ref:`Fundamentals <golang-indexes>`

     - .. code-block:: go
          :copyable: true

          model := mongo.IndexModel{Keys: bson.D{{"firstName", 1}, {"lastName", -1}}}
          name, err := coll.Indexes().CreateOne(context.TODO(), model)

   * - | **Search Text**
       |
       | `API Documentation <{+api+}/mongo#Collection.Find>`__
       | :ref:`Fundamentals <golang-search-text>`

     - .. io-code-block::
          :copyable: true

          .. input::
             :language: go

             // only searches fields with text indexes
             cursor, err := coll.Find(context.TODO(), bson.D{{"$text", bson.D{{"$search", "beagle"}}}})

          .. output::
             :language: go
             :visible: false 

             [{"firstName": "Emily" , "Description": "I love to play sports and walk my beagle."} ... ]