- Release Notes >
- Mongoid 7.4
Mongoid 7.4¶
On this page
- Ruby Version Support
- Support for MongoDB 3.4 and Earlier Servers Deprecated
- Change
===
Operator To Match Ruby Semantics - Return Hexadecimal
_id
Value fromBSON::ObjectId#as_json
- Scoped Associations
- Compare Times With Millisecond Precision When Embedded Matching
count
,sum
,avg
,min
,max
Ignore Sort If Not Limiting/Skipping- Return
0
When Aggregating Empty Result Sets - Correct Update Behavior When Replacing Association
- Correct Logical
and
Query Generation - Restore Parent Scope When Exiting
with_scope
Block - Changes to
distinct
andpluck
This page describes significant changes and improvements in Mongoid 7.4. 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.
All behavior changes in Mongoid 7.4 must be explicitly requested by changing the value of configuration options as detailed below. By default, Mongoid 7.4 behaves the same as Mongoid 7.3.
Ruby Version Support¶
As of version 7.4, Mongoid supports Ruby 2.5+. Support for Ruby 2.4 and earlier has been dropped.
As of Mongoid 7.4, JRuby support is deprecated. Mongoid 8 will not support JRuby.
Support for MongoDB 3.4 and Earlier Servers Deprecated¶
Mongoid 7.4 deprecates support for MongoDB 3.4 and earlier. Mongoid 8 will require MongoDB 3.6 or newer.
Change ===
Operator To Match Ruby Semantics¶
In Mongoid 7.4, the ===
operator on Mongoid::Document
classes and
instances can be configured to behave the same way as it does in Ruby,
and is equivalent to calling is_a?
on the right hand
side with the left hand side as the argument:
In order to get this functionality, the Mongoid.legacy_triple_equals
option must be set to false. If it is set to true, which is the default for
Mongoid 7.4, the ===
operator will function as it did in Mongoid 7.3:
===
returned true
for some cases when the equivalent Ruby
===
implementation returned false, as per the examples below.
Mongoid 7.4 with Mongoid.legacy_triple_equals
set to false
behavior:
Mongoid 7.3 and 7.4 with Mongoid.legacy_triple_equals
set to true
behavior:
The standard invocation of ===
, that is having the class on the left and
the instance on the right, works the same in Mongoid 7.4 as it did previously
and matches the core Ruby behavior:
Note
The value of Mongoid.legacy_triple_equals
option will change to false
by default in Mongoid 8.0.
Return Hexadecimal _id
Value from BSON::ObjectId#as_json
¶
Mongoid 7.4 permits configuring the BSON::ObjectId#as_json
method
to return the _id
value as a hexadecimal string instead of the
{"$oid" => "..."}
hash it has returned in Mongoid 7.3 and previous
versions.
When Mongoid.object_id_as_json_oid
is set to false
, Mongoid will
delegate to bson-ruby
implementation of BSON::ObjectId#as_json
.
In bson-ruby
4 the BSON::ObjectId#as_json
method will continue
to return the hash {"$oid" => "..."}
for backwards compatibility, but
in bson-ruby
5 the BSON::ObjectId#as_json
method will return only
the hexadecimal ObjectId string.
When Mongoid.object_id_as_json_oid
is set to true
, Mongoid will
install an implementation of BSON::ObjectId#as_json
which returns
the hash {"$oid" => "..."}
as it did in Mongoid 7.3 and earlier.
The behavior of as_json
is summarized in the following table:
Mongoid.object_id_as_json_oid value |
true | false |
---|---|---|
bson-ruby 4 |
{"$oid"=>"621ed7fda15d5d231594627c"} |
{"$oid"=>"621ed7fda15d5d231594627c"} |
bson-ruby 5 |
{"$oid"=>"621ed7fda15d5d231594627c"} |
"621ed7fda15d5d231594627c" |
Scoped Associations¶
Associations now support the :scope
argument, yielding
scoped associations.
Compare Times With Millisecond Precision When Embedded Matching¶
Mongoid 7.4 with the Mongoid.compare_time_by_ms
option set to true
will truncate the times to millisecond precision when comparing them while
performing embedded matching.
Time objects in Ruby have nanosecond precision, whereas MongoDB server
can only store times with millisecond precision. Set the
Mongoid.compare_time_by_ms
option to true
to truncate times to
millisecond precision when performing queries on already loaded embedded
associations (this is also called “embedded matching” and is done completely
in Ruby), to obtain the same query results when performing time comparisons
regardless of which documents are being queried. Setting this option to
false
will produce different results for queries on embedded associations
that are already loaded into memory vs queries on unloaded associations and
top-level models.
The Mongoid.compare_time_by_ms
option is set to false
by default
in Mongoid 7.4 for backwards compatibility. In Mongoid 8 the default value
will change to true
.
count
, sum
, avg
, min
, max
Ignore Sort If Not Limiting/Skipping¶
The count
, sum
, avg
, min
and max
methods now omit the
sort stage from the generated aggregation pipeline if no skip or limit
is specified, because the results aren’t affected by the sort order.
Example call that will now omit the sort stage and would potentially use
an index where it wouldn’t before:
Return 0
When Aggregating Empty Result Sets¶
Mongoid 7.4 with the Mongoid.broken_aggregables
option set to false
will return 0
from the sum
method over an empty result set, for example:
Mongoid 7.3 and Mongoid 7.4 with the Mongoid.broken_aggregables
option
set to true
(the default) returns nil
in this case.
Note
The value of Mongoid.broken_aggregables
option will change to false
by default in Mongoid 8.0.
Correct Update Behavior When Replacing Association¶
Mongoid 7.4 with the Mongoid.broken_updates
option set to false
will correctly persist an embeds_one
association target that is set to nil
and then to a non-nil value, for example:
In Mongoid 7.3 and earlier, and in 7.4 with the Mongoid.broken_aggregables
option set to true
(the default), canvas.palette
would be nil
when
we would expect it to be palette
.
Note
The value of Mongoid.broken_update
option will change to false
by default in Mongoid 8.0.
Correct Logical and
Query Generation¶
Mongoid 7.4 with the Mongoid.broken_and
option set to false
will preserve existing conditions when using and
to add new conditions
to a query when the same operator is used on the same field multiple times.
For example, in the following query:
Mongoid 7.4 with the Mongoid.broken_and
option set to false
will
generate the following criteria:
In Mongoid 7.3 and earlier, and in 7.4 with the Mongoid.broken_and
option set to true
(the default), the following criteria would be
generated instead which omit the {“$in” => [2021]} condition:
Note
The value of Mongoid.broken_and
option will change to false
by default in Mongoid 8.0.
Restore Parent Scope When Exiting with_scope
Block¶
Mongoid 7.4 with the Mongoid.broken_scoping
option set to false
will restore the parent scope when exiting a with_scope
block.
For example:
In Mongoid 7.3 and earlier, and in 7.4 with the Mongoid.broken_scoping
option set to true
(the default), once any with_scope
block finishes,
all scopes are cleared:
Note
The value of Mongoid.broken_scoping
option will change to false
by default in Mongoid 8.0.
Changes to distinct
and pluck
¶
Respect Field Aliases In Embedded Documents When Using distinct
and pluck
¶
When distinct
and pluck
are used with aliased fields in embedded
documents, the aliases can be expanded if the Mongoid.broken_alias_handling
option is set to false
. By default, for backwards compatibility, in
Mongoid 7.4 this option is set to true, yielding Mongoid 7.3 and earlier
behavior. Given the following definitions:
Mongoid 7.4 behavior with Mongoid.broken_alias_handling
set to false
:
Mongoid 7.3 and 7.4 with Mongoid.broken_alias_handling
set to true
behavior:
Note
The alias expansion for top-level fields has already been done by Mongoid 7.3.
Note
The value of Mongoid.broken_alias_handling
option will change to false
by default in Mongoid 8.0.
Demongoize Values Returned from pluck
and distinct
¶
Mongoid 7.4 with the Mongoid.legacy_pluck_distinct
option set to false
will demongoize values returned from the pluck
and distinct
methods.
Given the following definitions:
Mongoid 7.4 behavior with Mongoid.legacy_pluck_distinct
set to false
:
In Mongoid 7.3 and earlier, and in 7.4 with the Mongoid.legacy_pluck_distinct
option set to true
(the default), the value returned from the pluck and
distinct methods will not be demongoized. For example:
Note
The value of Mongoid.legacy_pluck_distinct
option will change to false
by default in Mongoid 8.0.
Localized Fields with pluck
and distinct
¶
Mongoid 7.4 with the Mongoid.legacy_pluck_distinct
option set to false
changes the behavior of using pluck
and distinct
with localized fields.
Now, when retrieving a localized field using these methods, the translation for
the current locale will be returned. To get the full translations hash the
_translations
field can be used. Given the following definitions:
Mongoid 7.4 behavior with Mongoid.legacy_pluck_distinct
set to false
:
In Mongoid 7.3 and earlier, and in 7.4 with the Mongoid.legacy_pluck_distinct
option set to true
(the default), inputting a localized field returns the
full translations hash. Inputting the _translations
field will return nil
.
For example:
Note
The value of Mongoid.legacy_pluck_distinct
option will change to false
by default in Mongoid 8.0.
Embedded Fields with pluck
¶
Mongoid 7.4 with the Mongoid.legacy_pluck_distinct
option set to false
returns the embedded values themselves, i.e. not inside a hash. Given the
following definitions:
Mongoid 7.4 behavior with Mongoid.legacy_pluck_distinct
set to false
:
In Mongoid 7.3 and earlier, and in 7.4 with the Mongoid.legacy_pluck_distinct
option set to true
(the default), plucking embedded attributes returns them
inside a hash. For example:
Note
The value of Mongoid.legacy_pluck_distinct
option will change to false
by default in Mongoid 8.0.