MONGOID-4547 Implement #take / #take! for AR feature parity (#5354)

* MONGOID-4547 add new error

* MONGOID-4547 implement take/take!

* MONGOID-4547 some cleanup

* MONGOID-4547 don't use Mongo#first

* MONGOID-4547 memory implementation

* MONGOID-4547 add none implementation

* MONGOID-4547 fix non implementation

* MONGOID-4547 add documentation for take method

* MONGOID-4547 add take! method docs

* MONGOID-4547 docs changes

* Apply suggestions from code review

Co-authored-by: Oleg Pudeyev <[email protected]>

* MONGOID-4547 change param to limit

* Apply suggestions from code review

Co-authored-by: Oleg Pudeyev <[email protected]>

* MONGOID-4547 address comments

* MONGOID-4547 fix document_not_found tests

Co-authored-by: Oleg Pudeyev <[email protected]>

Author: neilshweky

source/reference/queries.txt

@@ -1390,6 +1390,32 @@ Mongoid also has some helpful methods on criteria.
           # expands out to "managers.name" in the query:
           Band.all.pluck('managers.n')
 
+   * - ``Criteria#take``
+
+       *Get a list of n documents from the database or just one if no parameter
+       is provided.*
+
+       *This method does not apply a sort to the documents, so it can return
+       different document(s) than #first and #last.*
+
+     -
+        .. code-block:: ruby
+
+          Band.take
+          Band.take(5)
+
+   * - ``Criteria#take!``
+
+       *Get a document from the database or raise an error if none exist.*
+
+       *This method does not apply a sort to the documents, so it can return
+       different document(s) than #first and #last.*
+
+     -
+        .. code-block:: ruby
+
+          Band.take!
+
    * - ``Criteria#tally``
 
        *Get a mapping of values to counts for the provided field.*

source/release-notes/mongoid-7.5.txt

@@ -147,3 +147,44 @@ return a ``Hash`` when instantiating a new document:
   band = Band.first
   p band.attributes.class
   # => BSON::Document
+
+
+Implemented ``Criteria#take/take!`` Method
+------------------------------------------
+
+Mongoid 7.5 introduces the ``#take`` method which returns a document
+or a set of documents from the database without ordering by ``_id``:
+
+.. code:: ruby
+
+  class Band
+    include Mongoid::Document
+  end
+
+  Band.create!
+  Band.create!
+
+  Band.take
+  # => #<Band _id: 62c835813282a4470c07d530, >
+  Band.take(2)
+  # => [ #<Band _id: 62c835813282a4470c07d530, >, #<Band _id: 62c835823282a4470c07d531, > ]
+
+If a parameter is given to ``#take``, an array of documents is returned. If no parameter is
+given, a singular document is returned.
+
+The ``#take!`` method functions the same as calling ``#take`` without arguments,
+but raises an DocumentNotFound error instead of returning nil if no documents
+are found.
+
+.. code:: ruby
+
+  Band.take!
+  # => #<Band _id: 62c835813282a4470c07d530, >
+
+Note that the ``#take/take!`` methods do not apply a sort to the view before
+retrieving the documents from the database, and therefore they may return different
+results than the ``#first`` and ``#last`` methods. ``#take`` is equivalent to
+calling ``#first`` or ``#last`` with the ``{ id_sort: :none }`` option. This
+option has been deprecated in Mongoid 7.5 and it is recommended to use ``#take``
+instead going forward. Support for the ``:id_sort`` option will be dropped in
+Mongoid 8.