DOCSP-45003: Specify Fields to Include

source/fundamentals/crud/read-operations.txt

@@ -11,9 +11,11 @@ Read Operations
    :caption: Read Operations
 
    Retrieve Data </fundamentals/crud/read-operations/retrieve>
+   /fundamentals/crud/read-operations/project
    Count Documents </fundamentals/crud/read-operations/count>
    Monitor Data Changes </fundamentals/crud/read-operations/change-streams>
 
 - :ref:`csharp-retrieve`
+- :ref:`csharp-project`
 - :ref:`csharp-count-documents`
 - :ref:`csharp-change-streams`

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

@@ -0,0 +1,145 @@
+.. _csharp-project:
+
+========================
+Specify Fields To Return
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: read, filter, project, select
+
+Overview
+--------
+
+In this guide, you can learn how to specify which fields to return from a read
+operation by using a **projection**. A projection is a document that specifies
+which fields MongoDB returns from a query.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``sample_restaurants.restaurants`` collection
+from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-quickstart>`.
+
+Projection Types
+----------------
+
+You can use a projection to specify which fields to include in a return
+document, or to specify which fields to exclude.
+
+When specifying certain fields to include in a projection, all other fields are implicitly
+excluded (except the ``_id`` field, which is included by default). You cannot combine
+inclusion and exclusion statements in a single projection, unless you are excluding the
+``_id`` field.
+
+To remove the ``_id`` field from the returned document, you must
+:ref:`explicitly exclude it <csharp-project-exclude-id>`.
+
+Specify Fields to Include
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To specify the fields to include from the result, chain the ``Project()`` method
+to the ``Find()`` method. When calling the ``Project()`` method, you must pass in the
+projection definition as a parameter. You can construct a projection definition by using
+the ``Builders<T>.Projection.Include()`` method and passing in the field name to include
+as a parameter. This method can be chained to include multiple fields in the projection.
+
+The following example uses the ``Find()`` method to find all restaurants in which the ``name``
+field value is ``"Emerald Pub"``. Then, the code calls the ``Project()``
+method to instruct the find operation to include the ``name`` and ``cuisine`` fields
+in the result:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/fundamentals/code-examples/Project.cs
+      :start-after: start-project-include
+      :end-before: end-project-include
+      :language: csharp
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      { "_id" : ObjectId("..."), "cuisine" : "American", "name" : "Emerald Pub" }
+      { "_id" : ObjectId("..."), "cuisine" : "American", "name" : "Emerald Pub" }
+
+.. _csharp-project-exclude-id:
+
+Exclude the ``_id`` Field
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When specifying fields to include, you can also exclude the ``_id`` field from
+the returned document.
+
+The following example runs the same query as the preceding example, but
+excludes the ``_id`` field from the projection:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/fundamentals/code-examples/Project.cs
+      :start-after: start-project-include-without-id
+      :end-before: end-project-include-without-id
+      :language: csharp
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      { "cuisine" : "American", "name" : "Emerald Pub" }
+      { "cuisine" : "American", "name" : "Emerald Pub" }
+
+Specify Fields to Exclude
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To specify the fields to exclude from the result, chain the ``Project()`` method
+to the ``Find()`` method. You can exclude fields in your projection by using
+the ``Builders<T>.Projection.Exclude()`` method and passing in the field name to exclude
+as a parameter. This method can be chained to exclude multiple fields in the projection.
+
+The following example uses the ``Find()`` method to find all restaurants in which the ``name``
+field value is ``"Emerald Pub"``. It then uses a projection to exclude the ``cuisine``
+field from the returned documents:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/fundamentals/code-examples/Project.cs
+      :start-after: start-project-exclude
+      :end-before: end-project-exclude
+      :language: csharp
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      { "_id" : ObjectId("..."), "address" : { "building" : "308", "coord" : [-74.008493599999994, 40.725807199999998], "street" : "Spring Street", "zipcode" : "10013" }, "borough" : "Manhattan", "grades" : [{ "date" : ISODate("2014-02-24T00:00:00Z"), "grade" : "A", "score" : 5 }, { "date" : ISODate("2013-08-26T00:00:00Z"), "grade" : "A", "score" : 13 }, { "date" : ISODate("2013-03-04T00:00:00Z"), "grade" : "A", "score" : 12 }, { "date" : ISODate("2012-06-25T00:00:00Z"), "grade" : "A", "score" : 10 }, { "date" : ISODate("2011-12-23T00:00:00Z"), "grade" : "A", "score" : 10 }, { "date" : ISODate("2011-07-26T00:00:00Z"), "grade" : "C", "score" : 32 }], "name" : "Emerald Pub", "restaurant_id" : "40367329" }
+      { "_id" : ObjectId("..."), "address" : { "building" : "18301", "coord" : [-73.791184999999999, 40.740119999999997], "street" : "Horace Harding Expressway", "zipcode" : "11365" }, "borough" : "Queens", "grades" : [{ "date" : ISODate("2014-05-07T00:00:00Z"), "grade" : "A", "score" : 12 }, { "date" : ISODate("2013-04-30T00:00:00Z"), "grade" : "A", "score" : 9 }, { "date" : ISODate("2012-03-01T00:00:00Z"), "grade" : "A", "score" : 13 }], "name" : "Emerald Pub", "restaurant_id" : "40668598" }
+
+Additional Information
+----------------------
+
+To learn more about projections, see the :manual:`Project Fields guide
+</tutorial/project-fields-from-query-results/>` in the {+mdb-server+} manual.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the functions or types discussed in this
+guide, see the following API Documentation:
+
+- `Find() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`_
+- `Projection <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Builders-1.Projection.html>`_
+- `Include() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Include.html>`_
+- `Exclude() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Exclude.html>`_

source/includes/fundamentals/code-examples/Project.cs

@@ -0,0 +1,61 @@
+using MongoDB.Bson;
+using MongoDB.Driver;
+
+public class Project
+{
+    // Replace with your connection string
+    private const string MongoConnectionString = "<connection string URI>";
+
+    public static void Main(string[] args)
+    {   
+        var mongoClient = new MongoClient(MongoConnectionString);
+        var database = mongoClient.GetDatabase("sample_restaurants");
+        var collection = database.GetCollection<BsonDocument>("restaurants");
+
+        {
+            // start-project-include
+            var filter = Builders<BsonDocument>.Filter.Eq("name", "Emerald Pub");
+            var projection = Builders<BsonDocument>.Projection
+                .Include("name")
+                .Include("cuisine");
+
+            var results = collection.Find(filter).Project(projection).ToList();
+            foreach (var result in results)
+            {
+                Console.WriteLine(result.ToJson());
+            }
+            // end-project-include
+        }
+
+        {
+            // start-project-include-without-id
+            var filter = Builders<BsonDocument>.Filter.Eq("name", "Emerald Pub");
+            var projection = Builders<BsonDocument>.Projection
+                .Include("name")
+                .Include("cuisine")
+                .Exclude("_id");
+
+            var results = collection.Find(filter).Project(projection).ToList();
+            foreach (var result in results)
+            {
+                Console.WriteLine(result.ToJson());
+            }
+            // end-project-include-without-id
+        }
+
+        {
+            // start-project-exclude
+            var filter = Builders<BsonDocument>.Filter.Eq("name", "Emerald Pub");
+            var projection = Builders<BsonDocument>.Projection
+                .Exclude("cuisine");
+
+            var results = collection.Find(filter).Project(projection).ToList();
+            foreach (var result in results)
+            {
+                Console.WriteLine(result.ToJson());
+            }
+            // end-project-exclude
+        }
+
+    }
+}