Mongoid 7.5

This page describes significant changes and improvements in Mongoid 7.5. The complete list of releases is available on GitHub and in JIRA; please consult GitHub releases for detailed release notes and JIRA for the complete list of issues fixed in each release, including bug fixes.

Ruby, JRuby and Rails Version Support

Mongoid 7.5 deprecates support for Ruby 2.5, JRuby 9.2 and Rails 5.1. Mongoid 8 will require Ruby 2.6 or newer, JRuby 9.3 or newer and Rails 5.2 or newer.

Feature Flags Summary

To ensure a stable upgrade path from Mongoid 7.4, Mongoid 7.5 introduces feature flags which are further explained in the sections below.

To enable all new behavior in Mongoid 7.5, please use the following configuration options <configuration-options> in your mongoid.yml file. We recommend newly created apps to do this as well.

development:
  ...
  options:
    # Enable all new behavior in Mongoid 7.5
    legacy_attributes: false
    overwrite_chained_operators: false

In addition, please refer to the release notes of earlier 7.x versions for feature flags introduced in each version. For clarity, Mongoid 7.5 does not switch the behavior of any previously introduced feature flag.

Implemented Criteria#take/take! Method

Mongoid 7.5 introduces the #take method which returns a document or a set of documents from the database without ordering by _id:

class Band
  include Mongoid::Document
end

Band.create!
Band.create!

Band.take
# => #<Band _id: 62c835813282a4470c07d530, >
Band.take(2)
# => [ #<Band _id: 62c835813282a4470c07d530, >, #<Band _id: 62c835823282a4470c07d531, > ]

If a parameter is given to #take, an array of documents is returned. If no parameter is given, a singular document is returned.

The #take! method functions the same as calling #take without arguments, but raises an DocumentNotFound error instead of returning nil if no documents are found.

Band.take!
# => #<Band _id: 62c835813282a4470c07d530, >

Note that the #take/take! methods do not apply a sort to the view before retrieving the documents from the database, and therefore they may return different results than the #first and #last methods. #take is equivalent to calling #first or #last with the { id_sort: :none } option. This option has been deprecated in Mongoid 7.5 and it is recommended to use #take instead going forward. Support for the :id_sort option will be dropped in Mongoid 8.

Force the attributes Method to Always Return a Hash

Mongoid 7.5 with the Mongoid.legacy_attributes option set to false will always return a Hash when calling the attributes method. For example:

class Band
  include Mongoid::Document

  field :name
end

band = Band.create!(name: "The Rolling Stones")
p band.attributes.class
# => Hash

band = Band.first
p band.attributes.class
# => Hash

In Mongoid 7.4 and earlier, and in 7.5 with the Mongoid.legacy_attributes option set to true, the attributes method on a document will return a BSON::Document when retrieving that document from the database, but will return a Hash when instantiating a new document:

band = Band.create!(name: "The Rolling Stones")
p band.attributes.class
# => Hash

band = Band.first
p band.attributes.class
# => BSON::Document

Deprecate :id_sort Option and Support limit on #first/last

Mongoid 7.5 deprecates the :id_sort keyword argument for the Criteria#first and Criteria#last methods. Please use Criteria#take to retrieve documents without sorting by id.

The first and last methods now take the number of documents to return as a positional argument, mirroring the functionality of Ruby's Enumerable method and ActiveRecord's first and last methods. Both invocations (with limit as a positional arguments and with the :id_sort option) remain supported in Mongoid 7.x, but the :id_sort invocation will be removed in Mongoid 8.

Band.first
# => #<Band _id: 62c835813282a4470c07d530, >
Band.first(2)
# => [ #<Band _id: 62c835813282a4470c07d530, >, #<Band _id: 62c835823282a4470c07d531, > ]
Band.last
# => #<Band _id: 62c835823282a4470c07d531, >
Band.last(2)
# => [#<Band _id: 62c835813282a4470c07d530, >, #<Band _id: 62c835823282a4470c07d531, >]

When providing a limit, #first/last will return a list of documents, and when not providing a limit (or providing nil), a single document will be returned.

Note that the #first/last methods apply a sort on _id, which can cause performance issues. To get a document without sorting first, use the Critera#take method.

Combine Chained Operators Using and Instead of override

Mongoid 7.5 with the Mongoid.overwrite_chained_operators option set to false will combine conditions that use the same operator and field using an and. For example, in the following query:

Band.ne(name: "The Rolling Stones").ne(name: "The Beatles")

Mongoid 7.5 with the Mongoid.overwrite_chained_operators option set to false will generate the following criteria:

#<Mongoid::Criteria
  selector: {"name"=>{"$ne"=>"The Rolling Stones"}, "$and"=>[{"name"=>{"$ne"=>"The Beatles"}}]}
  options:  {}
  class:    Band
  embedded: false>

In Mongoid 7.4 and earlier, and in 7.5 with the Mongoid.overwrite_chained_operators option set to true, the following criteria would be generated instead which overwrites the first condition:

#<Mongoid::Criteria
  selector: {"name"=>{"$ne"=>"The Beatles"}}
  options:  {}
  class:    Band
  embedded: false>

The following functions are affected by this change:

• eq
• elem_match
• gt
• gte
• lt
• lte
• mod
• ne
• near
• near_sphere

pluck Usage of map Deprecated

Mongoid 7.5 deprecates the usage of map as pluck, as in the following example:

Band.all.map(:name)

# Equivalent to:
Band.pluck(:name)

This usage will no longer be supported in Mongoid 8, which will not accept arguments to map.

::Mongoid::Criteria cache deprecated

The ability to cache individual criteria objects has been deprecated in Mongoid 7.5 and will be dropped in Mongoid 8.

In order to get caching functionality, enable the Mongoid QueryCache. See the section on QueryCache <query-cache> for more details.

Array#update_values and Hash#update_values deprecated

The Array#update_values and Hash#update_values methods are deprecated in Mongoid 7.5. It is recommended to use ActiveSupport's transform_values! method instead.

Document#to_a deprecated

The Document#to_a method is deprecated in Mongoid 7.5.

update_one Warnings in upsert

Mongoid 7.5 fixes incorrect usage of the driver's update_one method from Mongoid's upsert method. Mongoid's upsert actually performs a replacing upsert, and Mongoid 7.5 correctly calls replace_one.