Docs Menu

Docs HomeMongoid

Mongoid 7.2

On this page

  • Embedded Document Matching
  • $eq and Regular Expression Values
  • $ne and Regular Expression Values
  • $eq, $ne and Range Values
  • $elemMatch
  • $and, $nor, $or and Empty Argument Arrays
  • count and estimated_count Methods
  • any? on has_many Associations
  • StringifiedSymbol Field Type
  • Changing the Discriminator Key
  • Changing the Discriminator Value
  • Shard Key Used For Reloading
  • Query Cache Moved to Driver
  • Regexp Fields Store Assigned Strings As Regular Expressions

This page describes significant changes and improvements in Mongoid 7.2. 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.

Breaking change: In Mongoid 7.2 embedded matchers were largely rewritten. Most queries should produce the same results as in previous versions of Mongoid but a number of cases changed behavior to make Mongoid behave the same way MongoDB server behaves. Note that the changes, for the most part, affect queries using manually constructed MQL expressions; Mongoid query methods generate MQL that is generally not affected by the changes in embedded matching.

To illustrate the differences, the examples below use the following model definitions:

class Job
include Mongoid::Document
embeds_many :tasks
end
class Task
include Mongoid::Document
include Mongoid::Attributes::Dynamic
embedded_in :job
end
job = Job.new(tasks: [
Task.new(name: 'Clean house', pattern: /test/, hours: 12),
])

The changes in behavior are as follows:

$eq now performs exact matching when given regular a expression argument. Previously, both operators used regular expression matching, which caused Mongoid to not find documents where the field being matched was a regular expression itself:

job.tasks.where(name: {'$eq': /house/}).first
# Mongoid 7.2:
# => nil
# Mongoid 7.1:
# => #<Task _id: 5ef8dc3e2c97a645ec86bb33, name: "Clean house", pattern: /test/, hours: 12>
job.tasks.where(pattern: {'$eq': /test/}).first
# Mongoid 7.2:
# => #<Task _id: 5ef8dc3e2c97a645ec86bb33, name: "Clean house", pattern: /test/, hours: 12>
# Mongoid 7.1:
# => nil

To perform a regular expression match, provide the regular expression directly without an operator:

job.tasks.where(name: /house/).first
# Mongoid 7.2 and 7.1:
# => #<Task _id: 5ef8dc3e2c97a645ec86bb33, name: "Clean house", pattern: /test/, hours: 12>

$ne no longer accepts regular expression arguments, which is the behavior of MongoDB server:

job.tasks.where(name: {'$ne': /apartment/}).first
# Mongoid 7.2: raises Mongoid::Errors::InvalidQuery
# Mongoid 7.1:
# => #<Task _id: 5ef8dc3e2c97a645ec86bb33, name: "Clean house", pattern: /test/, hours: 12>

To perform a negated regular expression match, use the not method on a symbol key:

job.tasks.where(:name.not => /house/).first
# Mongoid 7.2 and 7.1:
# => nil
job.tasks.where(:name.not => /office/).first
# Mongoid 7.2 and 7.1:
# => #<Task _id: 5ef8dc3e2c97a645ec86bb33, name: "Clean house", pattern: /test/, hours: 12>

Range values are no longer accepted by $eq and $ne operators. This change should not be visible to applications since Mongoid generally expands Range values to a $gte/$lte pair before they get to the embedded matchers.

To query using a range, use the following syntax which works in Mongoid 7.2 as well as previous versions:

job.tasks.where(hours: 10..15)
# =>
# #<Mongoid::Criteria
# selector: {"hours"=>{"$gte"=>10, "$lte"=>15}}
# options: {}
# class: Task
# embedded: true>
job.tasks.where(hours: 10..15).first
# => #<Task _id: 5ef8dd4c2c97a6465e8a4ffa, name: "Clean house", pattern: /test/, hours: 12>

Mongoid 7.1 accepted Range values as operator arguments, but generated queries that would never match documents. For example, the following expression was accepted but never matched any documents:

job.tasks.where(hours: {'$in': 10..15})
# =>
# #<Mongoid::Criteria
# selector: {"hours"=>{:$in=>{"$gte"=>10, "$lte"=>15}}}
# options: {}
# class: Task
# embedded: true>

Mongoid 7.2 raises Mongoid::Errors::InvalidQuery in this case.

$elemMatch now supports specifying operators as top-level fields:

mixed_tasks_job = Job.new(tasks: [
Task.new(name: 'Clean house', hours: 12, supplies: [{broom: 1}]),
Task.new(name: 'Clean office', hours: [8, 16]),
])
mixed_tasks_job.tasks.where(hours: {'$elemMatch': {'$lt': 20}}).first
# Mongoid 7.2:
# => #<Task _id: 5ef8c7202c97a6465e8a4ff3, name: "Clean office", hours: [8, 16]>
# Mongoid 7.1: error

Implicit matching under $elemMatch has been fixed and now works:

mixed_tasks_job.tasks.where(supplies: {'$elemMatch': {broom: 1}}).first
# Mongoid 7.2:
# => #<Task _id: 5ef8c9162c97a6465e8a4ff6, name: "Clean house", hours: 12, supplies: [{:broom=>1}]>
# Mongoid 7.1:
# => nil

For compatibility with MongoDB server, $elemMatch requires a Hash argument. Use $eq or $regex to perform equality comparisons or regular expression matches, respectively:

mixed_tasks_job.tasks.where(hours: {'$elemMatch': 8}).first
# Mongoid 7.2: raises Mongoid::Errors::InvalidQuery
# Mongoid 7.1:
# => nil
mixed_tasks_job.tasks.where(hours: {'$elemMatch': {'$eq': 8}}).first
# Mongoid 7.2:
# => #<Task _id: 5ef8ca0b2c97a6465e8a4ff9, name: "Clean office", hours: [8, 16]>
# Mongoid 7.1: error

$and, $nor and $or operators now raise an exception when given empty arrays as arguments. This only applies to raw MQL query expressions; the corresponding Mongoid query methods continue to permit being called without arguments. In previous versions of Mongoid, $and would match when given an empty array of conditions and $nor and $or would not match when given empty arrays of conditions.

job.tasks.where('$and': []).first
# Mongoid 7.2: raises Mongoid::Errors::InvalidQuery
# Mongoid 7.1:
# => #<Task _id: 5ef8dc3e2c97a645ec86bb33, name: "Clean house", pattern: /test/, hours: 12>
job.tasks.where('$nor': []).first
# Mongoid 7.2: raises Mongoid::Errors::InvalidQuery
# Mongoid 7.1:
# => nil
job.tasks.where('$or': []).first
# Mongoid 7.2: raises Mongoid::Errors::InvalidQuery
# Mongoid 7.1:
# => nil
job.tasks.and.first
# Mongoid 7.2 and 7.1:
# => #<Task _id: 5ef8dc3e2c97a645ec86bb33, name: "Clean house", pattern: /test/, hours: 12>
job.tasks.nor.first
# Mongoid 7.2 and 7.1:
# => #<Task _id: 5ef8dc3e2c97a645ec86bb33, name: "Clean house", pattern: /test/, hours: 12>
job.tasks.or.first
# Mongoid 7.2 and 7.1:
# => #<Task _id: 5ef8dc3e2c97a645ec86bb33, name: "Clean house", pattern: /test/, hours: 12>

Minor change: the count method on model classes and Criteria objects is now using the count_documents driver helper. This makes count seamlessly work in transactions.

Model classes now also have the estimated_count method to obtain an approximate number of documents in the collection. This method is roughly equivalent to the count method in Mongoid 7.1 and earlier, except estimated_count does not accept filter conditions.

The new behavior is further described in the Additional Query Methods section.

Minor change: the any? method on has_many associations was optimized to only retrieve the _id field when querying the database, instead of loading the entire association.

New feature: the StringifiedSymbol field type was added for storing Ruby symbol values in MongoDB in a manner interoperable with other programming languages.

New feature: Mongoid now supports changing the default discriminator key from the default _type when using inheritance. This can be done by setting the discriminator_key field on the parent class or globally. To set the discriminator key on the parent class:

class Shape
include Mongoid::Document
self.discriminator_key = "shape_type"
end
class Circle < Shape
end
class Rectangle < Shape
end

To set the discriminator key globally:

Mongoid.discriminator_key = "global_discriminator"
class Shape
include Mongoid::Document
end
class Circle < Shape
end
class Rectangle < Shape
end

New feature: Mongoid now also supports changing the discriminator value from the default value, which is the class name. The discriminator value can be changed by setting the discriminator_value on that class:

class Shape
include Mongoid::Document
end
class Circle < Shape
self.discriminator_value = "round thing"
end
class Rectangle < Shape
end

Minor change: When sharding is used, Mongoid 7.2 expects the shard key declared in models to match the shard key in the database for the respective collections. In Mongoid 7.2 model reloading (either explicit via the reload method or implicit as part of persistence operations) uses the shard key, if one is defined, in the find command in addition to the id field value. This improves the performance of document reloading, and consequently some persistence operations, in sharded clusters, especially those with geographically distributed shards.

Consider a class Band whose documents are sharded by the name key.

class Band
include Mongoid::Document
field :name, type: String
shard_key :name
end

Example Mongoid 7.2 behavior:

band = Band.create(name: "Destiny's Child")
band.reload
# Command logs: { "find"=>"bands", "filter"=>{ "_id"=>BSON::ObjectId('...') "name"=>"Destiny's Child" } }

Example Mongoid 7.1 behavior:

band = Band.create(name: "Destiny's Child")
band.reload
# Command logs: { "find"=>"bands", "filter"=>{"_id"=>BSON::ObjectId('...') } }

Mongoid provides sharding management Rake tasks to shard collections according to shard keys declared in models.

Minor change: Ruby driver version 2.14.0 implements a new and improved query cache. When using driver version 2.14.0 or newer, Mongoid will use the driver's query cache to cache query results.

The driver query cache introduces the following improvements:

  • Caching multi-batch query results

  • Taking a query's read concern and read preference into account when deciding when to return cached results

  • Invalidating the cache after bulk write operations and aggregation operations with $out and $merge pipeline stages

  • Invalidating the cache after transaction commit and abort operations

  • Improved performance of queries with limits

  • Caching aggregation results

  • More efficient query cache invalidation

Mongoid's query cache, which will now be referred to as the "legacy query cache," has been deprecated. Mongoid will retain the legacy query cache for use with older versions of the driver.

The interface for enabling and disabling the query cache in Mongoid has not changed. When using driver versions 2.14.0 and newer, this interface will enable or disable the query cache in the driver.

The driver query cache is more correct and more effective than the legacy Mongoid query cache. If you plan to use the query cache, it is recommended that you upgrade to driver version 2.14.

To read more about the query cache improvements made in the driver, see the Ruby driver documentation.

To read more about using the query cache with Mongoid and the limitations of the legacy query cache, see the query cache documentation.

Minor change: when a String value is written in a Regexp field, Mongoid 7.2 stores that value in MongoDB as a regular expression. Subsequently it would be retrieved as a BSON::Regexp::Raw instance. Previously the value would be stored as a string and would be retrieved as a string.

Example Mongoid 7.2 behavior:

class Offer
include Mongoid::Document
field :constraint, type: Regexp
end
offer = Offer.create!(constraint: /foo/)
# => #<Offer _id: 6082df412c97a66be6ba9970, constraint: /foo/>
Offer.collection.aggregate([
{'$match' => {_id: offer.id}},
{'$set' => {type: {'$type' => '$constraint'}}},
]).first
# => {"_id"=>BSON::ObjectId('6082df412c97a66be6ba9970'),
# "constraint"=>#<BSON::Regexp::Raw:0x000055b4ccdff738 @pattern="foo", @options="m">,
# "type"=>"regex"}
offer = Offer.create!(constraint: 'foo')
# => #<Offer _id: 6082df412c97a66be6ba9971, constraint: /foo/>
Offer.collection.aggregate([
{'$match' => {_id: offer.id}},
{'$set' => {type: {'$type' => '$constraint'}}},
]).first
# => {"_id"=>BSON::ObjectId('6082df412c97a66be6ba9971'),
# "constraint"=>#<BSON::Regexp::Raw:0x000055b4cce11320 @pattern="foo", @options="m">,
# "type"=>"regex"}

Mongoid 7.1 behavior with the same model class:

offer = Offer.create!(constraint: /foo/)
# => #<Offer _id: 6082e0182c97a66c21e3f721, constraint: /foo/>
Offer.collection.aggregate([
{'$match' => {_id: offer.id}},
{'$set' => {type: {'$type' => '$constraint'}}},
]).first
# => {"_id"=>BSON::ObjectId('6082e0182c97a66c21e3f721'),
# "constraint"=>#<BSON::Regexp::Raw:0x000055ecf43f4cb0 @pattern="foo", @options="m">,
# "type"=>"regex"}
offer = Offer.create!(constraint: 'foo')
# => #<Offer _id: 6082e05c2c97a66c21e3f723, constraint: "foo">
Offer.collection.aggregate([
{'$match' => {_id: offer.id}},
{'$set' => {type: {'$type' => '$constraint'}}},
]).first
# => {"_id"=>BSON::ObjectId('6082e05c2c97a66c21e3f723'),
# "constraint"=>"foo",
# "type"=>"string"}
←  Mongoid 7.3Mongoid 7.1 →
Share Feedback
© 2023 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.