diff --git a/source/fundamentals/crud/read-operations.txt b/source/fundamentals/crud/read-operations.txt index 60cf8425..329b1e40 100644 --- a/source/fundamentals/crud/read-operations.txt +++ b/source/fundamentals/crud/read-operations.txt @@ -11,9 +11,11 @@ Read Operations :caption: Read Operations Retrieve Data + /fundamentals/crud/read-operations/project Count Documents Monitor Data Changes - :ref:`csharp-retrieve` +- :ref:`csharp-project` - :ref:`csharp-count-documents` - :ref:`csharp-change-streams` diff --git a/source/fundamentals/crud/read-operations/project.txt b/source/fundamentals/crud/read-operations/project.txt new file mode 100644 index 00000000..fb64294e --- /dev/null +++ b/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 `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the :ref:``. + +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 `. + +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.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.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 +` 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>`_ \ No newline at end of file diff --git a/source/includes/fundamentals/code-examples/Project.cs b/source/includes/fundamentals/code-examples/Project.cs new file mode 100644 index 00000000..e2013e6a --- /dev/null +++ b/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 = ""; + + public static void Main(string[] args) + { + var mongoClient = new MongoClient(MongoConnectionString); + var database = mongoClient.GetDatabase("sample_restaurants"); + var collection = database.GetCollection("restaurants"); + + { + // start-project-include + var filter = Builders.Filter.Eq("name", "Emerald Pub"); + var projection = Builders.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.Filter.Eq("name", "Emerald Pub"); + var projection = Builders.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.Filter.Eq("name", "Emerald Pub"); + var projection = Builders.Projection + .Exclude("cuisine"); + + var results = collection.Find(filter).Project(projection).ToList(); + foreach (var result in results) + { + Console.WriteLine(result.ToJson()); + } + // end-project-exclude + } + + } +} \ No newline at end of file