Specify Fields To Return

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.

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.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

• find()

• mongocxx::options::find

• projection