DOCSP-13838 crud projection (#66)

* added CRUD Pojection page

Author: kyuan-mongodb

source/fundamentals/crud/read-operations.txt

@@ -8,10 +8,10 @@ Read Operations
 - :doc:`/fundamentals/crud/read-operations/sort`
 - :doc:`/fundamentals/crud/read-operations/skip`
 - :doc:`/fundamentals/crud/read-operations/limit`
+- :doc:`/fundamentals/crud/read-operations/project`
 
 ..
   - :doc:`/fundamentals/crud/read-operations/cursor`
-  - :doc:`/fundamentals/crud/read-operations/project`
   - :doc:`/fundamentals/crud/read-operations/geo`
   - :doc:`/fundamentals/crud/read-operations/text`
 
@@ -22,8 +22,8 @@ Read Operations
    /fundamentals/crud/read-operations/sort
    /fundamentals/crud/read-operations/skip
    /fundamentals/crud/read-operations/limit
+   /fundamentals/crud/read-operations/project
 ..
   /fundamentals/crud/read-operations/cursor
-  /fundamentals/crud/read-operations/project
   /fundamentals/crud/read-operations/geo
   /fundamentals/crud/read-operations/text

source/fundamentals/crud/read-operations/limit.txt

@@ -19,8 +19,9 @@ returned from a read operation.
 Sample Data
 ~~~~~~~~~~~
 
-Run the following snippet to load the documents into the ``ratings``
-collection of the ``tea`` database:
+To run the examples in this guide, load these documents into the
+``ratings`` collection of the ``tea`` database with the following
+snippet:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/limit.go
    :language: go
@@ -142,14 +143,14 @@ After running this example, the output resembles the following:
 Additional Information
 ----------------------
 
-For more information on performing read operations, see our guide on
-:doc:`retrieving data </fundamentals/crud/read-operations/retrieve>`.
+For more information on the read operations used, see the following guides:
 
-For information on specifying a sort, see our guide on :doc:`sorting
-results </fundamentals/crud/read-operations/sort>`. 
+- :doc:`Retrieve Data </fundamentals/crud/read-operations/retrieve>`
+- :doc:`Sort Results </fundamentals/crud/read-operations/sort>`
+- :doc:`Skip Returned Results </fundamentals/crud/read-operations/skip>`
 
-.. For information on skipping results, see our guide on :doc:`skipping
-.. returned results </fundamentals/crud/read-operations/skip>`. 
+.. For more information on aggregation, see the
+.. :doc:`Aggregation </fundamentals/aggregation>` guide.
 
 API Documentation
 ~~~~~~~~~~~~~~~~~

source/fundamentals/crud/read-operations/project.txt

@@ -0,0 +1,181 @@
+==============================
+Specify Which Fields to Return
+==============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to specify which fields to return in a
+document from read operations.
+
+Sample Data
+~~~~~~~~~~~
+
+To run the examples in this guide, load these documents into the
+``ratings`` collection of the ``tea`` database with the following
+snippet:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/projection.go 
+   :language: go
+   :dedent:
+   :start-after: begin insertDocs
+   :end-before: end insertDocs
+
+.. include:: /includes/fundamentals/tea-sample-data-ending.rst
+
+Projection
+----------
+
+A projection specifies which fields to return in matched documents. It
+contains field names followed by a ``1`` (to include) or ``0`` (to
+exclude). Projections can only include or exclude fields.
+
+You can specify a projection by passing one to the ``SetProjection()``
+function in the options of the following read operation functions:
+
+- ``Find()``
+- ``FindOne()``
+- ``FindOneAndDelete()``
+- ``FindOneAndReplace()``
+- ``FindOneAndUpdate()``
+
+.. tip::
+
+   If you don't specify a projection, the read operation returns all
+   the fields in matched documents.
+
+Exclude a Field
+~~~~~~~~~~~~~~~
+
+To exclude a field, pass the field you want to exclude and a ``0`` to
+the ``SetProjection()`` function. For all fields you don't explicitly
+list in the projection, the driver includes them.
+
+Example
+```````
+
+The following example excludes the ``rating`` from the matched documents
+from the ``Find()`` function:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/projection.go
+   :language: go
+   :dedent:
+   :start-after: begin exclude projection
+   :end-before: end exclude projection
+
+After running this example, the output resembles the following:
+
+.. code-block:: none
+   :copyable: false
+
+   //results truncated
+   [{_id ObjectID("...")} {type Masala}]
+   [{_id ObjectID("...")} {type Assam}]
+   [{_id ObjectID("...")} {type Oolong}]
+   [{_id ObjectID("...")} {type Earl Grey}]
+   [{_id ObjectID("...")} {type English Breakfast}]
+
+Include a Field
+~~~~~~~~~~~~~~~
+
+To include a field, pass the field you want to include and a ``1`` to
+the ``SetProjection()`` function. For all fields you don't explicitly
+list in the projection, the driver excludes them.
+
+.. important::
+
+    You can exclude the ``_id`` field even if you specified to include
+    certain fields. By default, the driver includes the ``_id`` field.
+    You must explicitly exclude the ``_id`` field if you do not want it
+    returned.
+
+.. _go-include-projection:
+
+Example
+```````
+
+The following example performs the following projection on the matched
+documents from the ``Find()`` function:
+
+- Include the ``type`` and ``rating`` field
+- Exclude the ``_id`` field
+
+.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/projection.go
+   :language: go
+   :dedent:
+   :start-after: begin include projection
+   :end-before: end include projection
+
+After running this example, the output resembles the following:
+
+.. code-block:: none
+   :copyable: false
+
+   [{type Masala} {rating 10}]
+   [{type Assam} {rating 5}]
+   [{type Oolong} {rating 7}]
+   [{type Earl Grey} {rating 8}]
+   [{type English Breakfast} {rating 5}]
+
+Aggregation
+~~~~~~~~~~~
+
+You can also include the :manual:`$project </reference/operator/aggregation/project/>`
+stage to specify a projection in an aggregation pipeline.
+
+Example
+```````
+
+The following example performs the following projection on the matched
+documents from the ``Aggregate()`` function:
+
+- Include the ``type`` and ``rating`` field
+- Exclude the ``_id`` field
+
+.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/projection.go
+   :language: go
+   :dedent:
+   :start-after: begin aggregate projection
+   :end-before: end aggregate projection
+
+After running this example, the output resembles the following:
+
+.. code-block:: none
+   :copyable: false
+
+   [{type Masala} {rating 10}]
+   [{type Assam} {rating 5}]
+   [{type Oolong} {rating 7}]
+   [{type Earl Grey} {rating 8}]
+   [{type English Breakfast} {rating 5}]
+
+Additional Information
+----------------------
+
+For more information on performing read operations, see our guide on
+:doc:`retrieving data </fundamentals/crud/read-operations/retrieve>`.
+
+.. For more information on aggregation, see the
+.. :doc:`Aggregation </fundamentals/aggregation>` guide.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+For more information on any of the functions or types discussed in this
+guide, see the following API Documentation:
+
+- `Find() <{+api+}/mongo#Collection.Find>`__
+- `FindOptions.SetProjection() <{+api+}/mongo/options#FindOptions.SetProjection>`__
+- `FindOne() <{+api+}/mongo#Collection.FindOne>`__
+- `FindOneAndDelete() <{+api+}/mongo#Collection.FindOneAndDelete>`__
+- `FindOneAndReplace() <{+api+}/mongo#Collection.FindOneAndReplace>`__
+- `FindOneAndUpdate() <{+api+}/mongo#Collection.FindOneAndUpdate>`__
+- `Aggregate() <{+api+}/mongo#Collection.Aggregate>`__

source/fundamentals/crud/read-operations/retrieve.txt

@@ -24,8 +24,9 @@ Read operations allow you to do the following:
 Sample Data
 ~~~~~~~~~~~
 
-Run the following snippet to load the documents into the ``ratings``
-collection of the ``tea`` database:
+To run the examples in this guide, load these documents into the
+``ratings`` collection of the ``tea`` database with the following
+snippet:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/retrieve.go
    :language: go

source/fundamentals/crud/read-operations/skip.txt

@@ -19,8 +19,9 @@ results from read operations.
 Sample Data
 ~~~~~~~~~~~
 
-Run the following snippet to load the documents into the ``ratings``
-collection of the ``tea`` database:
+To run the example in this guide, load these documents into the
+``ratings`` collection of the ``tea`` database with the following
+snippet:
 
 .. literalinclude:: /includes/fundamentals/code-snippets/CRUD/skip.go
    :language: go
@@ -113,11 +114,13 @@ After running this example, the output resembles the following:
 Additional Information
 ----------------------
 
-For more information on performing read operations, see our guide on
-:doc:`retrieving data </fundamentals/crud/read-operations/retrieve>`.
+For more information on the read operations used, see the following guides:
 
-For information on specifying a sort, see our guide on :doc:`sorting
-results </fundamentals/crud/read-operations/sort>`. 
+- :doc:`Retrieve Data </fundamentals/crud/read-operations/retrieve>`
+- :doc:`Sort Results </fundamentals/crud/read-operations/sort>`
+
+.. For more information on aggregation, see the
+.. :doc:`Aggregation </fundamentals/aggregation>` guide.
 
 API Documentation
 ~~~~~~~~~~~~~~~~~

source/fundamentals/crud/read-operations/sort.txt

@@ -202,6 +202,9 @@ For more information on performing read operations, see our guide on
 .. For information about sorting text, see our
 .. guide on :doc:`Text Search </fundamentals/crud/write-operations/text>`.
 
+.. For more information on aggregation, see the
+.. :doc:`Aggregation </fundamentals/aggregation>` guide.
+
 API Documentation
 ~~~~~~~~~~~~~~~~~
 

source/includes/fundamentals/code-snippets/CRUD/projection.go

@@ -0,0 +1,109 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"go.mongodb.org/mongo-driver/bson"
+	"go.mongodb.org/mongo-driver/mongo"
+	"go.mongodb.org/mongo-driver/mongo/options"
+)
+
+func main() {
+	var uri string
+	if uri = os.Getenv("MONGODB_URI"); uri == "" {
+		log.Fatal("You must set your 'MONGODB_URI' environmental variable. See\n\t https://docs.mongodb.com/drivers/go/current/usage-examples/")
+	}
+
+	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)
+		}
+	}()
+
+	client.Database("tea").Collection("ratings").Drop(context.TODO())
+
+	// begin insertDocs
+	coll := client.Database("tea").Collection("ratings")
+	docs := []interface{}{
+		bson.D{{"type", "Masala"}, {"rating", 10}},
+		bson.D{{"type", "Assam"}, {"rating", 5}},
+		bson.D{{"type", "Oolong"}, {"rating", 7}},
+		bson.D{{"type", "Earl Grey"}, {"rating", 8}},
+		bson.D{{"type", "English Breakfast"}, {"rating", 5}},
+	}
+
+	result, err := coll.InsertMany(context.TODO(), docs)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("Number of documents inserted: %d\n", len(result.InsertedIDs))
+	//end insertDocs
+
+	fmt.Println("Exclude Projection:")
+	{
+		//begin exclude projection
+		opts := options.Find().SetProjection(bson.D{{"rating", 0}})
+
+		cursor, err := coll.Find(context.TODO(), bson.D{}, opts)
+		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)
+		}
+		//end exclude projection
+	}
+
+	fmt.Println("Include Projection:")
+	{
+		//begin include projection
+		opts := options.Find().SetProjection(bson.D{{"type", 1}, {"rating", 1}, {"_id", 0}})
+
+		cursor, err := coll.Find(context.TODO(), bson.D{}, opts)
+		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)
+		}
+		//end include projection
+	}
+
+	fmt.Println("Aggregation Projection:")
+	{
+		// begin aggregate projection
+		projectStage := bson.D{{"$project", bson.D{{"type", 1}, {"rating", 1}, {"_id", 0}}}}
+
+		cursor, err := coll.Aggregate(context.TODO(), mongo.Pipeline{projectStage})
+		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)
+		}
+		// end aggregate projection
+	}
+}