MONGOID-5408 .evolve should support wrapper class (#5448)

Co-authored-by: shields <[email protected]>

Author: johnnyshields

source/reference/queries.txt

@@ -168,58 +168,45 @@ name, as follows:
   #   class:    Band
   #   embedded: false>
 
-Embedded Documents
-==================
-
-To match values of fields of embedded documents, use the dot notation:
-
-.. code-block:: ruby
-
-  Band.where('manager.name' => 'Smith')
-  # => #<Mongoid::Criteria
-  #   selector: {"manager.name"=>"Smith"}
-  #   options:  {}
-  #   class:    Band
-  #   embedded: false>
-
-  Band.where(:'manager.name'.ne => 'Smith')
-  # => #<Mongoid::Criteria
-  #   selector: {"manager.name"=>{"$ne"=>"Smith"}}
-  #   options:  {}
-  #   class:    Band
-  #   embedded: false>
 
-.. note::
+Fields
+======
 
-  Queries always return top-level model instances, even if all of the
-  conditions are referencing embedded documents.
-
-Field Types
-===========
+Querying on Defined Fields
+--------------------------
 
 In order to query on a field, it is not necessary to add the field to
 :ref:`the model class definition <fields>`. However, if a field is defined in
-the model class, the type of the field is taken into account when constructing
-the query:
+the model class, Mongoid will coerce query values to match defined field types
+when constructing the query:
 
 .. code-block:: ruby
 
-  Band.where(name: 2020)
+  Band.where(name: 2020, founded: "2020")
   #   => #<Mongoid::Criteria
-  #   selector: {"name"=>"2020"}
+  #   selector: {"name"=>"2020", "founded"=>2020}
   #   options:  {}
   #   class:    Band
   #   embedded: false>
 
-  Band.where(founded: 2020)
+Querying for Raw Values
+-----------------------
+
+If you'd like to bypass Mongoid's query type coercion behavior and query
+directly for the raw-typed value in the database, wrap the query value in
+``Mongoid::RawValue`` class. This can be useful when working with legacy data.
+
+.. code-block:: ruby
+
+  Band.where(founded: Mongoid::RawValue("2020"))
   # => #<Mongoid::Criteria
-  #   selector: {"founded"=>2020}
+  #   selector: {"founded"=>"2020"}
   #   options:  {}
   #   class:    Band
   #   embedded: false>
 
-Aliases
-=======
+Field Aliases
+-------------
 
 Queries take into account :ref:`storage field names <storage-field-names>`
 and :ref:`field aliases <field-aliases>`:
@@ -245,6 +232,33 @@ Since ``id`` and ``_id`` fields are aliases, either one can be used for queries:
   #   embedded: false>
 
 
+Embedded Documents
+==================
+
+To match values of fields of embedded documents, use the dot notation:
+
+.. code-block:: ruby
+
+  Band.where('manager.name' => 'Smith')
+  # => #<Mongoid::Criteria
+  #   selector: {"manager.name"=>"Smith"}
+  #   options:  {}
+  #   class:    Band
+  #   embedded: false>
+
+  Band.where(:'manager.name'.ne => 'Smith')
+  # => #<Mongoid::Criteria
+  #   selector: {"manager.name"=>{"$ne"=>"Smith"}}
+  #   options:  {}
+  #   class:    Band
+  #   embedded: false>
+
+.. note::
+
+  Queries always return top-level model instances, even if all of the
+  conditions are referencing embedded documents.
+
+
 .. _logical-operations:
 
 Logical Operations

source/release-notes/mongoid-9.0.txt

@@ -82,6 +82,24 @@ ignored for embedded documents; an embedded document now always uses the persist
 context of its parent.
 
 
+Support for Passing Raw Values into Queries
+-------------------------------------------
+
+When performing queries, it is now possible skip Mongoid's type coercion logic
+using the ``Mongoid::RawValue`` wrapper class. This can be useful when legacy
+data in the database is of a different type than the field definition.
+
+.. code-block:: ruby
+
+   class Person
+     include Mongoid::Document
+     field :age, type: Integer
+   end
+
+   # Query for the string "42", not the integer 42
+   Person.where(age: Mongoid::RawValue("42"))
+
+
 Raise AttributeNotLoaded error when accessing fields omitted from query projection
 ----------------------------------------------------------------------------------