Modify Query Results

Sample Data

The examples in this guide use the Band model, which represents a band or musical group. The definition of the Band model might be different for each section to demonstrate different query functionalities. Some sections also use the Manager model, which represents a person who manages a given band, or the Tour model, which represents live performances by a given band.

Include Fields

The only method retrieves only the specified fields from the database.

The following code returns only the name field from documents in which the value of the members field is 4:

Band.where(members: 4).only(:name)

If you attempt to reference attributes that have not been loaded, Mongoid raises a Mongoid::Errors::AttributeNotLoaded error.

You can also use the only method to include fields from embedded documents.

Consider that the Band model embeds multiple Tour objects. You can project fields from the Tour model such as year, as shown in the following code:

bands = Band.only(:name, 'tours.year')

Then, you can access the embedded fields from the returned documents:

# Returns the first Tour object from
# the first Band in the results
bands.first.tours.first

You can pass fields of referenced associations to the only method, but the projection is ignored when loading the embedded objects. Mongoid loads all fields of the referenced associations. For example, when you access the embedded Tour object as shown in the preceding code, Mongoid returns the complete object, not just the year field.

If a document contains has_one or has_and_belongs_to_many associations, and you want Mongoid to load those associations when you call the only method, you must include the fields with foreign keys in the list of attributes.

In the following example, the Band and Manager models have a has_and_belongs_to_many association:

class Band
  include Mongoid::Document
  field :name, type: String
  has_and_belongs_to_many :managers
end
class Manager
  include Mongoid::Document
  has_and_belongs_to_many :bands
end

The following code demonstrates how Mongoid can load the associated Manager objects if you include the manager_ids field:

# Returns null
Band.where(name: 'Astral Projection').only(:name).first.managers
# Returns the first Manager object
Band.where(name: 'Astral Projection').only(:name, :manager_ids).first.managers

Exclude Fields

You can explicitly exclude fields from results by using the without method.

The following code excludes the year field from returned Band objects:

Band.where(members: 4).without(:year)

Limit Number of Results

You can use the limit method to limit the number of results that Mongoid returns.

The following code retrieves a maximum of 5 documents:

Band.limit(5)

Band.take(5)

Skip Results

You can skip a specified number of results by using the skip method, or its alias offset.

If you chain a limit call to skip, the limit is applied after documents are skipped, as demonstrated in the following example:

Band.skip(2).limit(5)
# Skips the first two results and returns
# the following five results

The following code skips the first 3 documents when returning results:

Band.skip(3)
# Equivalent
Band.offset(3)

Generate Batches of Results

When executing large queries and when iterating over query results by using an enumerator method such as Criteria#each, Mongoid automatically uses the MongoDB getMore command to load results in batches. The default batch size is 1000, but you can set a different value by using the batch_size method.

The following code sets the batch size to 500:

Band.batch_size(500)