mongoid 7.1.0 → 7.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8352346c7b47e2323d4afee8968a5581b091735a11d3aacaf9a1c73197d511db
-  data.tar.gz: 4780a1d8ec316330301e933a145957e48f4927c9fbcbe582404f062179280947
+  metadata.gz: b90b3442fbb22055d692fca89eb33e90868e45588812f1975926dee5a85d8b10
+  data.tar.gz: d9c2a5eaf30d5ca34a365be11b648efc8932a7cda1b29fd8982847cf9cb528cd
 SHA512:
-  metadata.gz: 870e9d5aff9bd06217cea69dd7b86b15ea9ec89464a8e6f579e24e58789a1e5612256026927e6cdd0e17cb39340cf4ef7758bc75fc1b5176939f8b11968bd76c
-  data.tar.gz: fc095139739ed83771b35d9f2c91b2a0e33bb99125df7622fe0f8f24bf971c6d0cabcd5ac507d4bb72e8a178bc988661197258f20f0193b7e72c8d7a219d2459
+  metadata.gz: ca1480e9cbd438a8905ef4d8f1e9ac59e66ee6436b0017f40c350de6421dd5f99a8a96c1bfa31bb0291738ad97bdad5ce18ee2ccc60a0cea2d91f1795abd5a8c
+  data.tar.gz: a3f7da9b676f022dc9bf48199eeb34f68fc14e2c076b539a81149401a6b1b81914f96ba21daca7a392b40a5bf5ed8ef9b76d7499033b786b530d161a1e3bb29b

data/CHANGELOG.md

@@ -1848,18 +1848,18 @@ child elements.
   set a child on a relation without the proper inverse_of definitions
   due to Mongoid not being able to determine it.
 
-        class Lush
+        class Car
           include Mongoid::Document
-          embeds_one :whiskey, class_name: "Drink"
+          embeds_one :engine, class_name: "Motor"
         end
 
-        class Drink
+        class Motor
           include Mongoid::Document
-          embedded_in :alcoholic, class_name: "Lush"
+          embedded_in :machine, class_name: "Car"
         end
 
-        lush = Lush.new
-        lush.whiskey = Drink.new # raises an InverseNotFound error.
+        car = Car.new
+        car.engine = Motor.new # raises an InverseNotFound error.
 
 * \#1680 Polymorphic relations now use `*_type` keys in lookup queries.
 

data/README.md

@@ -31,7 +31,7 @@ Support
 -------
 
 * [Stack Overflow](http://stackoverflow.com/questions/tagged/mongoid)
-* [Mongoid Google Group](http://groups.google.com/group/mongoid)
+* [MongoDB Community Forum](https://developer.mongodb.com/community/forums/tags/c/drivers-odms-connectors/7/mongoid-odm)
 * [#mongoid](http://webchat.freenode.net/?channels=mongoid) on Freenode IRC
 
 License

data/lib/config/locales/en.yml

@@ -282,13 +282,13 @@ en:
             you will need to explicitly tell Mongoid on the association what
             the inverse is.\n\n
             Example:\n
-            \_\_class Lush\n
+            \_\_class Car\n
             \_\_\_\_include Mongoid::Document\n
-            \_\_\_\_has_one :whiskey, class_name: \"Drink\", inverse_of: :alcoholic\n
+            \_\_\_\_has_one :engine, class_name: \"Motor\", inverse_of: :machine\n
             \_\_end\n\n
-            \_\_class Drink\n
+            \_\_class Motor\n
             \_\_\_\_include Mongoid::Document\n
-            \_\_\_\_belongs_to :alcoholic, class_name: \"Lush\", inverse_of: :whiskey\n
+            \_\_\_\_belongs_to :machine, class_name: \"Car\", inverse_of: :engine\n
             \_\_end"
         invalid_set_polymorphic_relation:
           message: "The %{name} attribute can't be set to an instance of

data/lib/mongoid/association/referenced/belongs_to/eager.rb

@@ -12,8 +12,6 @@ module Mongoid
           private
 
           def preload
-            raise Errors::EagerLoad.new(@association.name) if @association.polymorphic?
-
             @docs.each do |d|
               set_relation(d, nil)
             end
@@ -24,6 +22,44 @@ module Mongoid
             end
           end
 
+          # Retrieves the documents referenced by the association, and
+          # yields each one sequentially to the provided block. If the
+          # association is not polymorphic, all documents are retrieved in
+          # a single query. If the association is polymorphic, one query is
+          # issued per association target class.
+          def each_loaded_document(&block)
+            if @association.polymorphic?
+              keys_by_type_from_docs.each do |type, keys|
+                each_loaded_document_of_class(Object.const_get(type), keys, &block)
+              end
+            else
+              super
+            end
+          end
+
+          # Returns a map from association target class name to foreign key
+          # values for the documents of that association target class,
+          # as referenced by this association.
+          def keys_by_type_from_docs
+            inverse_type_field = @association.inverse_type
+
+            @docs.each_with_object({}) do |doc, keys_by_type|
+              next unless doc.respond_to?(inverse_type_field) && doc.respond_to?(group_by_key)
+              inverse_type_name = doc.send(inverse_type_field)
+              # If a particular document does not have a value for this
+              # association, inverse_type_name will be nil.
+              next if inverse_type_name.nil?
+
+              key_value = doc.send(group_by_key)
+              # If a document has the *_type field set but the corresponding
+              # *_id field not set, the key value here will be nil.
+              next unless key_value
+
+              keys_by_type[inverse_type_name] ||= []
+              keys_by_type[inverse_type_name].push(key_value)
+            end
+          end
+
           def group_by_key
             @association.foreign_key
           end

data/lib/mongoid/association/referenced/eager.rb

@@ -59,17 +59,29 @@ module Mongoid
             raise NotImplementedError
           end
 
-          # Run the preloader.
-          #
-          # @example Iterate over the documents loaded for the current association
-          #   loader.each_loaded_document { |doc| }
+          # Retrieves the documents referenced by the association, and
+          # yields each one sequentially to the provided block. If the
+          # association is not polymorphic, all documents are retrieved in
+          # a single query. If the association is polymorphic, one query is
+          # issued per association target class.
           #
           # @since 4.0.0
-          def each_loaded_document
-            doc_keys = keys_from_docs
-            return @association.klass.none if doc_keys.all?(&:nil?)
+          def each_loaded_document(&block)
+            each_loaded_document_of_class(@association.klass, keys_from_docs, &block)
+          end
 
-            criteria = @association.klass.any_in(key => doc_keys)
+          # Retrieves the documents of the specified class, that have the
+          # foreign key included in the specified list of keys.
+          #
+          # When the documents are retrieved, the set of inclusions applied
+          # is the set of inclusions applied to the host document minus the
+          # association that is being eagerly loaded.
+          private def each_loaded_document_of_class(cls, keys)
+            # Note: keys should not include nil elements.
+            # Upstream code is responsible for eliminating nils from keys.
+            return cls.none if keys.empty?
+
+            criteria = cls.any_in(key => keys)
             criteria.inclusions = criteria.inclusions - [@association]
             criteria.each do |doc|
               yield doc
@@ -93,6 +105,9 @@ module Mongoid
 
           # Return a hash with the current documents grouped by key.
           #
+          # Documents that do not have a value for the association being loaded
+          # are not returned.
+          #
           # @example Return a hash with the current documents grouped by key.
           #   loader.grouped_docs
           #
@@ -102,10 +117,15 @@ module Mongoid
           def grouped_docs
             @grouped_docs[@association.name] ||= @docs.group_by do |doc|
               doc.send(group_by_key) if doc.respond_to?(group_by_key)
+            end.reject do |k, v|
+              k.nil?
             end
           end
 
-          # Group the documents and return the keys
+          # Group the documents and return the keys.
+          #
+          # This method omits nil keys (i.e. keys from documents that do not
+          # have a value for the association being loaded).
           #
           # @example
           #   loader.keys_from_docs

data/lib/mongoid/config.rb

@@ -18,14 +18,31 @@ module Mongoid
 
     LOCK = Mutex.new
 
+    # Application name that is printed to the mongodb logs upon establishing
+    # a connection in server versions >= 3.4. Note that the name cannot
+    # exceed 128 bytes. It is also used as the database name if the
+    # database name is not explicitly defined.
+    option :app_name, default: nil
+
+    # Create indexes in background by default.
+    option :background_indexing, default: false
+
+    # Mark belongs_to associations as required by default, so that saving a
+    # model with a missing belongs_to association will trigger a validation
+    # error.
+    option :belongs_to_required_by_default, default: true
+
+    # Raise an exception when a field is redefined.
+    option :duplicate_fields_exception, default: false
+
+    # Include the root model name in json serialization.
     option :include_root_in_json, default: false
+
+    # # Include the _type field in serialization.
     option :include_type_for_serialization, default: false
-    option :preload_models, default: false
-    option :raise_not_found_error, default: true
-    option :scope_overwrite_exception, default: false
-    option :duplicate_fields_exception, default: false
-    option :use_activesupport_time_zone, default: true
-    option :use_utc, default: false
+
+    # Whether to join nested persistence contexts for atomic operations
+    # to parent contexts by default.
     option :join_contexts, default: false
 
     # The log level.
@@ -38,9 +55,22 @@ module Mongoid
     # configuration file is the log level given by this option honored.
     option :log_level, default: :info
 
-    option :belongs_to_required_by_default, default: true
-    option :app_name, default: nil
-    option :background_indexing, default: false
+    # Preload all models in development, needed when models use inheritance.
+    option :preload_models, default: false
+
+    # Raise an error when performing a #find and the document is not found.
+    option :raise_not_found_error, default: true
+
+    # Raise an error when defining a scope with the same name as an
+    # existing method.
+    option :scope_overwrite_exception, default: false
+
+    # Use ActiveSupport's time zone in time operations instead of the
+    # Ruby default time zone.
+    option :use_activesupport_time_zone, default: true
+
+    # Return stored times as UTC.
+    option :use_utc, default: false
 
     # Has Mongoid been configured? This is checking that at least a valid
     # client config exists.

data/lib/mongoid/criteria.rb

@@ -400,9 +400,22 @@ module Mongoid
     # @return [ Criteria ] The cloned selectable.
     #
     # @since 1.0.0
-    def where(expression)
-      if expression.is_a?(::String) && embedded?
-        raise Errors::UnsupportedJavascript.new(klass, expression)
+    def where(*args)
+      # Historically this method required exactly one argument.
+      # As of https://jira.mongodb.org/browse/MONGOID-4804 it also accepts
+      # zero arguments.
+      # The underlying where implemetation that super invokes supports
+      # any number of arguments, but we don't presently allow mutiple
+      # arguments through this method. This API can be reconsidered in the
+      # future.
+      if args.length > 1
+        raise ArgumentError, "Criteria#where requires zero or one arguments (given #{args.length})"
+      end
+      if args.length == 1
+        expression = args.first
+        if expression.is_a?(::String) && embedded?
+          raise Errors::UnsupportedJavascript.new(klass, expression)
+        end
       end
       super
     end

data/lib/mongoid/criteria/queryable/pipeline.rb

@@ -33,7 +33,7 @@ module Mongoid
         # Add a group operation to the aggregation pipeline.
         #
         # @example Add a group operation.
-        #   pipeline.group(:count.sum => 1, :max.max => "likes")
+        #   pipeline.group(:_id => "foo", :count.sum => 1, :max.max => "likes")
         #
         # @param [ Hash ] entry The group entry.
         #
@@ -76,7 +76,8 @@ module Mongoid
         #   pipeline.unwind(:field)
         #   pipeline.unwind(document)
         #
-        # @param [ String, Symbol, Hash ] field_or_doc The name of the field or a document.
+        # @param [ String, Symbol, Hash ] field_or_doc A field name or a
+        #   document.
         #
         # @return [ Pipeline ] The pipeline.
         #

data/lib/mongoid/criteria/queryable/selectable.rb

@@ -92,8 +92,8 @@ module Mongoid
             normalized = _mongoid_normalize_expr(new_s)
             normalized.each do |k, v|
               k = k.to_s
-              if c.selector[k] || k[0] == ?$
-                c = c.send(:__multi__, [{k => v}], '$and')
+              if c.selector[k]
+                c = c.send(:__multi__, [k => v], '$and')
               else
                 c.selector.store(k, v)
               end
@@ -586,13 +586,34 @@ module Mongoid
         end
         key :not, :override, "$not"
 
-        # Adds $or selection to the selectable.
+        # Creates a disjunction using $or from the existing criteria in the
+        # receiver and the provided arguments.
         #
-        # @example Add the $or selection.
+        # This behavior (receiver becoming one of the disjunction operands)
+        # matches ActiveRecord's +or+ behavior.
+        #
+        # Use +any_of+ to add a disjunction of the arguments as an additional
+        # constraint to the criteria already existing in the receiver.
+        #
+        # Each argument can be a Hash, a Criteria object, an array of
+        # Hash or Criteria objects, or a nested array. Nested arrays will be
+        # flattened and can be of any depth. Passing arrays is deprecated.
+        #
+        # @example Add the $or selection where both fields must have the specified values.
         #   selectable.or(field: 1, field: 2)
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
-        #   matches or Criteria objects.
+        # @example Add the $or selection where either value match is sufficient.
+        #   selectable.or({field: 1}, {field: 2})
+        #
+        # @example Same as previous example but using the deprecated array wrap.
+        #   selectable.or([{field: 1}, {field: 2}])
+        #
+        # @example Same as previous example, also deprecated.
+        #   selectable.or([{field: 1}], [{field: 2}])
+        #
+        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        #   Multiple key/value pair matches or Criteria objects, or arrays
+        #   thereof. Passing arrays is deprecated.
         #
         # @return [ Selectable ] The new selectable.
         #
@@ -600,7 +621,73 @@ module Mongoid
         def or(*criteria)
           _mongoid_add_top_level_operation('$or', criteria)
         end
-        alias :any_of :or
+
+        # Adds a disjunction of the arguments as an additional constraint
+        # to the criteria already existing in the receiver.
+        #
+        # Use +or+ to make the receiver one of the disjunction operands.
+        #
+        # Each argument can be a Hash, a Criteria object, an array of
+        # Hash or Criteria objects, or a nested array. Nested arrays will be
+        # flattened and can be of any depth. Passing arrays is deprecated.
+        #
+        # @example Add the $or selection where both fields must have the specified values.
+        #   selectable.any_of(field: 1, field: 2)
+        #
+        # @example Add the $or selection where either value match is sufficient.
+        #   selectable.any_of({field: 1}, {field: 2})
+        #
+        # @example Same as previous example but using the deprecated array wrap.
+        #   selectable.any_of([{field: 1}, {field: 2}])
+        #
+        # @example Same as previous example, also deprecated.
+        #   selectable.any_of([{field: 1}], [{field: 2}])
+        #
+        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        #   Multiple key/value pair matches or Criteria objects, or arrays
+        #   thereof. Passing arrays is deprecated.
+        #
+        # @return [ Selectable ] The new selectable.
+        #
+        # @since 1.0.0
+        def any_of(*criteria)
+          criteria = _mongoid_flatten_arrays(criteria)
+          case criteria.length
+          when 0
+            clone
+          when 1
+            # When we have a single criteria, any_of behaves like and.
+            # Note: criteria can be a Query object, which #where method does
+            # not support.
+            self.and(*criteria)
+          else
+            # When we have multiple criteria, combine them all with $or
+            # and add the result to self.
+            exprs = criteria.map do |criterion|
+              if criterion.is_a?(Selectable)
+                _mongoid_normalize_expr(criterion.selector)
+              else
+                Hash[criterion.map do |k, v|
+                  if k.is_a?(Symbol)
+                    [k.to_s, v]
+                  else
+                    [k, v]
+                  end
+                end]
+              end
+            end
+            # Should be able to do:
+            #where('$or' => exprs)
+            # But since that is broken do instead:
+            clone.tap do |query|
+              if query.selector['$or']
+                query.selector.store('$or', query.selector['$or'] + exprs)
+              else
+                query.selector.store('$or', exprs)
+              end
+            end
+          end
+        end
 
         # Add a $size selection for array fields.
         #

data/lib/mongoid/criteria/queryable/storable.rb

@@ -17,67 +17,49 @@ module Mongoid
       # @api private
       module Storable
 
-        # Adds an operator expression to the selector.
-        #
-        # This method takes the operator and the operator value expression
-        # separately for callers' convenience. It can be considered to
-        # handle storing the hash `{operator => op_expr}`.
-        #
-        # If the selector already has the specified operator in it (on the
-        # top level), the new condition given in op_expr is added to the
-        # existing conditions for the specified operator. This is
-        # straightforward for $and; for other logical operators, the behavior
-        # of this method is to add the new conditions to the existing operator.
-        # For example, if the selector is currently:
-        #
-        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}]}
-        #
-        # ... and operator is '$or' and op_expr is `{'test' => 123'}`,
-        # the resulting selector will be:
-        #
-        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}, {'test' => 123}]}
+        # Adds a field expression to the query.
         #
-        # This does not implement an OR between the existing selector and the
-        # new operator expression - handling this is the job of upstream
-        # methods. This method simply stores op_expr into the selector on the
-        # assumption that the existing selector is the correct left hand side
-        # of the operation already.
+        # +field+ must be a field name, and it must be a string. The upstream
+        # code must have converted other field/key types to the simple string
+        # form by the time this method is invoked.
         #
-        # For non-logical query-level operators like $where and $text, if
-        # there already is a top-level operator with the same name, the
-        # op_expr is added to the selector via a top-level $and operator,
-        # thus producing a selector having both operator values.
+        # +value+ can be of any type, it is written into the selector unchanged.
         #
-        # This method does not simplify values (i.e. if the selector is
-        # currently empty and operator is $and, op_expr is written to the
-        # selector with $and even if the $and can in principle be elided).
+        # This method performs no processing on the provided field value.
         #
-        # This method mutates the receiver.
+        # Mutates the receiver.
         #
-        # @param [ String ] operator The operator to add.
-        # @param [ Hash ] op_expr Operator value to add.
+        # @param [ String ] field The field name.
+        # @param [ Object ] value The field value.
         #
         # @return [ Storable ] self.
-        def add_operator_expression(operator, op_expr)
-          unless operator.is_a?(String)
-            raise ArgumentError, "Operator must be a string: #{operator}"
-          end
-
-          unless operator[0] == ?$
-            raise ArgumentError, "Operator must begin with $: #{operator}"
+        def add_field_expression(field, value)
+          unless field.is_a?(String)
+            raise ArgumentError, "Field must be a string: #{field}"
           end
 
-          if %w($and $nor $or).include?(operator)
-            return add_logical_operator_expression(operator, op_expr)
+          if field[0] == ?$
+            raise ArgumentError, "Field cannot be an operator (i.e. begin with $): #{field}"
           end
 
-          # For other operators, if the operator already exists in the
-          # query, add the new condition with $and, otherwise add the
-          # new condition to the top level.
-          if selector[operator]
-            add_logical_operator_expression('$and', [{operator => op_expr}])
+          if selector[field]
+            # We already have a restriction by the field we are trying
+            # to restrict, combine the restrictions.
+            if value.is_a?(Hash) && selector[field].is_a?(Hash) &&
+              value.keys.all? { |key|
+                key_s = key.to_s
+                key_s[0] == ?$ && !selector[field].key?(key_s)
+              }
+            then
+              # Multiple operators can be combined on the same field by
+              # adding them to the existing hash.
+              new_value = selector[field].merge(value)
+              selector.store(field, new_value)
+            else
+              add_operator_expression('$and', [{field => value}])
+            end
           else
-            selector.store(operator, op_expr)
+            selector.store(field, value)
           end
 
           self
@@ -87,41 +69,40 @@ module Mongoid
         #
         # This method only handles logical operators ($and, $nor and $or).
         # It raises ArgumentError if called with another operator. Note that
-        # in MongoDB, $not is a field-level operator and not a query-level one
-        # $not is not handled by this method as a result.
+        # in MQL, $not is a field-level operator and not a query-level one,
+        # and therefore $not is not handled by this method.
         #
         # This method takes the operator and the operator value expression
         # separately for callers' convenience. It can be considered to
         # handle storing the hash `{operator => op_expr}`.
         #
-        # If the selector already has the specified operator in it (on the
-        # top level), the new condition given in op_expr is added to the
-        # existing conditions for the specified operator. This is
-        # straightforward for $and; for other logical operators, the behavior
-        # of this method is to add the new conditions to the existing operator.
+        # If the selector consists of a single condition which is the specified
+        # operator (on the top level), the new condition given in op_expr is
+        # added to the existing conditions for the specified operator.
         # For example, if the selector is currently:
         #
-        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}]}
+        #     {'$or' => [{'hello' => 'world'}]}
         #
-        # ... and operator is '$or' and op_expr is `{'test' => 123'}`,
+        # ... and operator is '$or' and op_expr is `[{'test' => 123'}]`,
         # the resulting selector will be:
         #
-        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}, {'test' => 123}]}
+        #     {'$or' => [{'hello' => 'world'}, {'test' => 123}]}
         #
-        # This does not implement an OR between the existing selector and the
-        # new operator expression - handling this is the job of upstream
-        # methods. This method simply stores op_expr into the selector on the
-        # assumption that the existing selector is the correct left hand side
-        # of the operation already.
+        # This method always adds the new conditions as additional requirements;
+        # in other words, it does not implement the ActiveRecord or/nor behavior
+        # where the receiver becomes one of the operands. It is expected that
+        # code upstream of this method implements such behavior.
         #
         # This method does not simplify values (i.e. if the selector is
         # currently empty and operator is $and, op_expr is written to the
         # selector with $and even if the $and can in principle be elided).
+        # Such simplification is also expected to have already been performed
+        # by the upstream code.
         #
         # This method mutates the receiver.
         #
         # @param [ String ] operator The operator to add.
-        # @param [ Hash ] op_expr Operator value to add.
+        # @param [ Array<Hash> ] op_expr Operator value to add.
         #
         # @return [ Storable ] self.
         def add_logical_operator_expression(operator, op_expr)
@@ -145,56 +126,80 @@ module Mongoid
             # with whatever other conditions exist.
             selector.store(operator, op_expr)
           else
-            # Other operators need to operate explicitly on the previous
-            # conditions and the new condition.
-            new_value = [selector.to_hash.dup] + op_expr
-            selector.replace(operator => new_value)
+            # Other operators need to be added separately
+            if selector[operator]
+              add_logical_operator_expression('$and', [operator => op_expr])
+            else
+              selector.store(operator, op_expr)
+            end
           end
 
           self
         end
 
-        # Adds a field expression to the query.
+        # Adds an operator expression to the selector.
         #
-        # field must be a field name, and it must be a string. The upstream
-        # code must have converted other field/key types to the simple string
-        # form by the time this method is invoked.
+        # This method takes the operator and the operator value expression
+        # separately for callers' convenience. It can be considered to
+        # handle storing the hash `{operator => op_expr}`.
         #
-        # This method performs no processing on the provided field value.
+        # The operator value can be of any type.
         #
-        # Mutates the receiver.
+        # If the selector already has the specified operator in it (on the
+        # top level), the new condition given in op_expr is added to the
+        # existing conditions for the specified operator. This is
+        # straightforward for $and; for other logical operators, the behavior
+        # of this method is to add the new conditions to the existing operator.
+        # For example, if the selector is currently:
         #
-        # @param [ String ] field The field name.
-        # @param [ Object ] value The field value.
+        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}]}
+        #
+        # ... and operator is '$or' and op_expr is `{'test' => 123'}`,
+        # the resulting selector will be:
+        #
+        #     {'foo' => 'bar', '$or' => [{'hello' => 'world'}, {'test' => 123}]}
+        #
+        # This does not implement an OR between the existing selector and the
+        # new operator expression - handling this is the job of upstream
+        # methods. This method simply stores op_expr into the selector on the
+        # assumption that the existing selector is the correct left hand side
+        # of the operation already.
+        #
+        # For non-logical query-level operators like $where and $text, if
+        # there already is a top-level operator with the same name, the
+        # op_expr is added to the selector via a top-level $and operator,
+        # thus producing a selector having both operator values.
+        #
+        # This method does not simplify values (i.e. if the selector is
+        # currently empty and operator is $and, op_expr is written to the
+        # selector with $and even if the $and can in principle be elided).
+        #
+        # This method mutates the receiver.
+        #
+        # @param [ String ] operator The operator to add.
+        # @param [ Object ] op_expr Operator value to add.
         #
         # @return [ Storable ] self.
-        def add_field_expression(field, value)
-          unless field.is_a?(String)
-            raise ArgumentError, "Field must be a string: #{field}"
+        def add_operator_expression(operator, op_expr)
+          unless operator.is_a?(String)
+            raise ArgumentError, "Operator must be a string: #{operator}"
           end
 
-          if field[0] == ?$
-            raise ArgumentError, "Field cannot be an operator (i.e. begin with $): #{field}"
+          unless operator[0] == ?$
+            raise ArgumentError, "Operator must begin with $: #{operator}"
           end
 
-          if selector[field]
-            # We already have a restriction by the field we are trying
-            # to restrict, combine the restrictions.
-            if value.is_a?(Hash) && selector[field].is_a?(Hash) &&
-              value.keys.all? { |key|
-                key_s = key.to_s
-                key_s[0] == ?$ && !selector[field].key?(key_s)
-              }
-            then
-              # Multiple operators can be combined on the same field by
-              # adding them to the existing hash.
-              new_value = selector[field].merge(value)
-              selector.store(field, new_value)
-            else
-              add_operator_expression('$and', [{field => value}])
-            end
+          if %w($and $nor $or).include?(operator)
+            return add_logical_operator_expression(operator, op_expr)
+          end
+
+          # For other operators, if the operator already exists in the
+          # query, add the new condition with $and, otherwise add the
+          # new condition to the top level.
+          if selector[operator]
+            add_logical_operator_expression('$and', [{operator => op_expr}])
           else
-            selector.store(field, value)
+            selector.store(operator, op_expr)
           end
 
           self