- Release Notes >
- Mongoid 7.4
Mongoid 7.4¶
On this page
- Ruby Version Support
- Support for MongoDB 3.4 and Earlier Servers Deprecated
- Feature Flags Summary
- Change
===
Operator To Match Ruby Semantics - Return String
_id
Value (Hexadecimal) 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
update_one
Warnings inupsert
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.
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.
Feature Flags Summary¶
To ensure a stable upgrade path from Mongoid 7.3, Mongoid 7.4 introduces feature flags which are further explained in the sections below.
To enable all new behavior in Mongoid 7.4, please use the following configuration options in your mongoid.yml file. We recommend newly created apps to do this as well.
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
In Mongoid 8.0, the default value of the Mongoid.legacy_triple_equals
option will
change to false
.
Return String _id
Value (Hexadecimal) 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" |
Note
In Mongoid 8.0, the default value of the Mongoid.object_id_as_json_oid
option will
change to false
.
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.
Note
In Mongoid 8.0, the default value of the Mongoid.compare_time_by_ms
option 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
In Mongoid 8.0, the default value of the Mongoid.broken_aggregables
option will
change to false
.
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
In Mongoid 8.0, the default value of the Mongoid.broken_updates
option will
change to false
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
In Mongoid 8.0, the default value of the Mongoid.broken_and
option will
change to false
.
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
In Mongoid 8.0, the default value of the Mongoid.broken_scoping
option will
change to false
.
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
In Mongoid 8.0, the default value of the Mongoid.broken_alias_handling
option will
change to false
.
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
In Mongoid 8.0, the default value of the Mongoid.legacy_pluck_distinct
option will
change to false
.
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
In Mongoid 8.0, the default value of the Mongoid.legacy_pluck_distinct
option will
change to false
.
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
In Mongoid 8.0, the default value of the Mongoid.legacy_pluck_distinct
option will
change to false
.
update_one
Warnings in upsert
¶
Mongoid 7.4.1 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.4.1 and later correctly call replace_one
.