Specify Fields To Return
On this page
Overview
In this guide, you can learn how to use the C++ driver 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 restaurants
collection in the sample_restaurants
database from the Atlas sample datasets. To access this collection
from your C++ application, instantiate a mongocxx::client
that connects to an Atlas cluster
and assign the following values to your db
and collection
variables:
auto db = client["sample_restaurants"]; auto collection = db["restaurants"];
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.
Projection Types
You can use a projection to specify which fields to include in a return
document, or to specify which fields to exclude. You cannot combine inclusion and
exclusion statements in a single projection, unless you are excluding the
_id
field.
Specify Fields to Include
To specify the fields to include in the result, create an instance of the
mongocxx::options::find
class and set its projection
field. To set
this field, use the following syntax:
<options instance>.projection(make_document(kvp("<field name>", 1)));
The following example sets the projection
field of a mongocxx::options::find
object to return only the name
, cuisine
, and borough
fields of matching
documents. It then calls the find()
method to find all restaurants in which
the name
field value is "Emerald Pub"
, passing the mongocxx::options::find
object as a parameter to find()
:
mongocxx::options::find opts{}; opts.projection(make_document(kvp("name", 1), kvp("cuisine", 1), kvp("borough", 1))); auto cursor = collection.find(make_document(kvp("name", "Emerald Pub")), opts); for(auto&& doc : cursor) { std::cout << bsoncxx::to_json(doc) << std::endl; }
{ "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" } { "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" }
When you use a projection to specify fields to include in the return
document, the _id
field is also included by default. All other fields are
implicitly excluded. To remove the _id
field from the return
document, you must explicitly exclude it.
Exclude the _id
Field
When specifying fields to include, you can also exclude the _id
field from
the returned document.
The following example performs the same query as the preceding example but
excludes the _id
field from the projection:
mongocxx::options::find opts{}; opts.projection(make_document(kvp("_id", 0), kvp("name", 1), kvp("cuisine", 1), kvp("borough", 1))); auto cursor = collection.find(make_document(kvp("name", "Emerald Pub")), opts); for(auto&& doc : cursor) { std::cout << bsoncxx::to_json(doc) << std::endl; }
{ "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" } { "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" }
Specify Fields to Exclude
To specify the fields to exclude in the result, create an instance of the
mongocxx::options::find
class and set its projection
field. To set
this field, use the following syntax:
<options instance>.projection(make_document(kvp("<field name>", 0)));
The following example sets the projection
field of a mongocxx::options::find
object to exclude the grades
and address
fields of matching documents.
It then calls the find()
method to find all restaurants in which the name
field value is "Emerald Pub"
, passing the mongocxx::options::find
object
as a parameter to find()
:
mongocxx::options::find opts{}; opts.projection(make_document(kvp("grades", 0), kvp("address", 0))); auto cursor = collection.find(make_document(kvp("name", "Emerald Pub")), opts); for(auto&& doc : cursor) { std::cout << bsoncxx::to_json(doc) << std::endl; }
{ "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40367329" } { "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub", "restaurant_id" : "40668598" }
When you use a projection to specify which fields to exclude, any unspecified fields are implicitly included in the return document.
Additional Information
To learn more about projections, see the Project Fields guide in the MongoDB Server manual.
API Documentation
To learn more about any of the methods or types discussed in this guide, see the following API documentation: