Specify Fields To Return
On this page
Overview
In this guide, you can learn how to use the Ruby 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 Ruby application, create a Mongo::Client object that connects to
an Atlas cluster and assign the following values to your database and collection
variables:
database = client.use('sample_restaurants') collection = database[: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 or exclude in
a return Document. You cannot combine inclusion and exclusion statements in
a single projection, unless you are excluding the _id field.
Specify Fields to Include
To include specific fields in a read operation result, specify the projection
option in a parameter to the find method. To set this option, use the following syntax:
{ projection: { <field_name>: 1 } }
The following example uses the find method to find all restaurants in which the name
field value is 'Emerald Pub'. Then, the code specifies the projection option
to instruct the find operation to return only the name, cuisine, and borough fields
of matching documents:
opts = { projection: { name: 1, cuisine: 1, borough: 1 } } collection.find({ name: 'Emerald Pub' }, opts).each do |doc| puts doc end
{"_id"=>BSON::ObjectId('...'), "borough"=>"Manhattan", "cuisine"=>"American", "name"=>"Emerald Pub"} {"_id"=>BSON::ObjectId('...'), "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:
opts = { projection: { name: 1, cuisine: 1, borough: 1, _id: 0 } } collection.find({ name: 'Emerald Pub' }, opts).each do |doc| puts doc end
{"borough"=>"Manhattan", "cuisine"=>"American", "name"=>"Emerald Pub"} {"borough"=>"Queens", "cuisine"=>"American", "name"=>"Emerald Pub"}
Specify Fields to Exclude
To exclude specific fields from a read operation result, specify the projection
option in a parameter to the find method. To set this option, use the
following syntax:
{ projection: { <field_name>: 0 } }
The following example uses the find method to find all restaurants in which the name
field value is 'Emerald Pub'. Then, the code uses the projection option
to instruct the find operation to omit the grades and address fields
in the result:
opts = { projection: { grades: 0, address: 0 } } collection.find({ name: 'Emerald Pub' }, opts).each do |doc| puts doc end
{"_id"=>BSON::ObjectId('...'), "borough"=>"Manhattan", "cuisine"=>"American", "name"=>"Emerald Pub", "restaurant_id"=>"40367329"} {"_id"=>BSON::ObjectId('...'), "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 the find method, see the
API documentation.