Specify Fields To Return

On this page

Overview

Sample Data
Projection Types
Specify Fields to Include
Exclude the _id Field
Additional Information
API Documentation

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 restaurants collection in the sample_restaurants database from the Atlas sample datasets. 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.

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 explicitly exclude it.

Specify Fields to Include

The following example uses the mongoc_collection_find_with_opts() function to find all restaurants with the name field value of "Emerald Pub". It specifies a projection to return only the name, cuisine, and borough fields of the returned documents by using the options parameter of mongoc_collection_find_with_opts().

const bson_t *doc;
bson_t *filter = BCON_NEW ("name", BCON_UTF8 ("Emerald Pub"));
bson_t *opts = BCON_NEW ("projection", "{",
                    "name", BCON_BOOL (true),
                    "cuisine", BCON_BOOL (true),
                    "borough", BCON_BOOL (true),
                    "}");
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, opts, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
bson_destroy (filter);
bson_destroy (opts);
mongoc_cursor_destroy (results);

{ "_id" : { "$oid" : "..." }, "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" }
{ "_id" : { "$oid" : "..." }, "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" }

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:

const bson_t *doc;
bson_t *filter = BCON_NEW ("name", BCON_UTF8 ("Emerald Pub"));
bson_t *opts = BCON_NEW ("projection", "{",
                    "name", BCON_BOOL (true),
                    "cuisine", BCON_BOOL (true),
                    "borough", BCON_BOOL (true),
                    "_id", BCON_BOOL (false),
                    "}");
mongoc_cursor_t *results = 
    mongoc_collection_find_with_opts (collection, filter, opts, NULL);
while (mongoc_cursor_next (results, &doc)) {
    char *str = bson_as_canonical_extended_json (doc, NULL);
    printf ("%s\n", str);
    bson_free (str);
}
bson_destroy (filter);
bson_destroy (opts);
mongoc_cursor_destroy (results);

{ "borough" : "Manhattan", "cuisine" : "American", "name" : "Emerald Pub" }
{ "borough" : "Queens", "cuisine" : "American", "name" : "Emerald Pub" }

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 functions or types discussed in this guide, see the following API Documentation:

mongoc_collection_find_with_opts()

Back

Retrieve Data

Specify Documents to Return