DOCSP-44648: return raw results (#118)

* DOCSP-44648: return raw results

* small fix

Author: rustagir

source/includes/interact-data/modify-results.rb

@@ -38,3 +38,21 @@
 # start-batch
 Band.batch_size(500)
 # end-batch
+
+# start-raw
+Band.where(country: 'Argentina').raw
+# end-raw
+
+# start-raw-typed
+Band.where(country: 'Argentina').raw(typed: true)
+# end-raw-typed
+
+# start-raw-false
+# Retrieves raw results
+results = Band.where(members: 4).raw
+
+# ... Perform actions on results
+
+# Returns instantiated model objects from raw results
+bands = results.raw(false).to_a
+# end-raw-false

source/interact-data/modify-results.txt

@@ -30,6 +30,8 @@ following actions to modify the way that results appear:
 
 - :ref:`mongoid-data-skip-limit`
 
+- :ref:`mongoid-raw-results`
+
 Sample Data
 ~~~~~~~~~~~
 
@@ -306,6 +308,43 @@ The following code sets the batch size to ``500``:
    :language: ruby
    :dedent:
 
+.. _mongoid-raw-results:
+
+Return Raw Data
+---------------
+
+You can return results as raw hashes without creating model instances by
+chaining the ``raw`` method to your query.
+
+The following code retrieves the query results as raw hashes:
+
+.. literalinclude:: /includes/interact-data/modify-results.rb
+   :start-after: start-raw
+   :end-before: end-raw
+   :language: ruby
+   :dedent:
+
+By default, the ``raw`` method returns documents exactly as {+odm+}
+receives them from the database. You can optionally cast fields in your
+result hashes to the types from your model field declarations by setting
+the ``typed`` option to ``true`` in the ``raw`` method:
+
+.. literalinclude:: /includes/interact-data/modify-results.rb
+   :start-after: start-raw-typed
+   :end-before: end-raw-typed
+   :language: ruby
+   :dedent:
+
+If you perform a query that returns raw results and later want to
+convert these results into models, you can call ``raw(false)`` on the
+results:
+
+.. literalinclude:: /includes/interact-data/modify-results.rb
+   :start-after: start-raw-false
+   :end-before: end-raw-false
+   :language: ruby
+   :dedent:
+
 Additional Information
 ----------------------
 

source/whats-new.txt

@@ -12,11 +12,24 @@ What's New
 
 Learn what's new in:
 
+* :ref:`Version 9.1 <mongoid-version-9.1>`
 * :ref:`Version 9.0 <mongoid-version-9.0>`
 
 To view a list of releases and detailed release notes, see {+odm+}
 :github:`Releases <mongodb/mongoid/releases>` on GitHub.
 
+.. _mongoid-version-9.1:
+
+What's New in 9.1
+-----------------
+
+The 9.1 release includes the following new features, improvements, and
+fixes:
+
+- Adds the ``Criteria#raw`` method that allows you to retrieve results
+  as raw hashes. To learn more, see the :ref:`mongoid-raw-results`
+  section of the Modify Query Results guide.
+
 .. _mongoid-version-9.0:
 
 What's New in 9.0