Add docs

Author: johnnyshields

docs/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)
+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
-=======
+-------
 
 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