Docs Menu

Docs HomeMongoid

Mongoid 7.5

On this page

  • Ruby, JRuby and Rails Version Support
  • Feature Flags Summary
  • Implemented Criteria#take/take! Method
  • Force the attributes Method to Always Return a Hash
  • Deprecate :id_sort Option and Support limit on #first/last
  • Combine Chained Operators Using and Instead of override
  • pluck Usage of map Deprecated
  • Mongoid::Criteria cache deprecated
  • Array#update_values and Hash#update_values deprecated
  • Document#to_a deprecated
  • update_one Warnings in upsert

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.

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.

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 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.

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.

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

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.

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

Note

In Mongoid 7.5 with the Mongoid.overwrite_chained_operators option set to false, nested keys in the generated selector will always be strings, whereas in Mongoid 7.4 and earlier, and in 7.5 with the Mongoid.overwrite_chained_operators option set to true, nested keys in the selector can be strings or symbols, depending on what was passed to the operator.

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.

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 for more details.

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.

The Document#to_a method is deprecated in Mongoid 7.5.

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.

←  Mongoid 8.0Mongoid 7.4 →