diff --git a/source/includes/read/limit-skip-sort.rb b/source/includes/read/limit-skip-sort.rb new file mode 100644 index 00000000..2efebd54 --- /dev/null +++ b/source/includes/read/limit-skip-sort.rb @@ -0,0 +1,51 @@ +require 'bundler/inline' + +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = '' + +Mongo::Client.new(uri) do |client| + # Access the database and collection + # start-db-coll + database = client.use('sample_restaurants') + collection = database[:restaurants] + # end-db-coll + + # Retrieves 5 documents that have a "cuisine" value of "Italian" + # start-limit + filter = { cuisine: 'Italian' } + collection.find(filter) + .limit(5) + .each { |doc| puts doc } + # end-limit + + # Retrieves documents with a "cuisine" value of "Italian" and sorts in ascending "name" order + # start-sort + filter = { cuisine: 'Italian' } + collection.find(filter) + .sort(name: 1) + .each { |doc| puts doc } + # end-sort + + # Retrieves documents with a "borough" value of "Manhattan" but skips the first 10 results + # start-skip + filter = { borough: 'Manhattan' } + collection.find(filter) + .skip(10) + .each { |doc| puts doc } + # end-skip + + # Retrieves 5 documents with a "cuisine" value of "Italian", skips the first 10 results, + # and sorts by ascending "name" order + # start-limit-sort-skip + filter = { cuisine: 'Italian' } + collection.find(filter) + .limit(5) + .skip(10) + .sort(name: 1) + .each { |doc| puts doc } + # end-limit-sort-skip +end diff --git a/source/read.txt b/source/read.txt index b9f5ba1a..316d2bce 100644 --- a/source/read.txt +++ b/source/read.txt @@ -23,4 +23,5 @@ Read Data from MongoDB :maxdepth: 1 Retrieve Data - Specify Fields to Return \ No newline at end of file + Specify Documents to Return + Specify Fields to Return diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt new file mode 100644 index 00000000..fc80bac6 --- /dev/null +++ b/source/read/specify-documents-to-return.txt @@ -0,0 +1,210 @@ +.. _ruby-specify-documents-to-return: + +=========================== +Specify Documents to Return +=========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: read, paginate, pagination, order, code example + +Overview +-------- + +In this guide, you can learn how to specify which documents to return +from a read operation by chaining the following methods to the ``find`` +method: + +- :ref:`limit `: Specifies the maximum number of documents + to return from a query +- :ref:`sort `: Specifies the sort order for the returned documents +- :ref:`skip `: Specifies the number of documents to skip before + returning query results + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your {+language+} application, create a ``Mongo::Client`` object that connects to +an Atlas cluster and assign the following values to your ``database`` and ``collection`` +variables: + +.. literalinclude:: /includes/read/limit-skip-sort.rb + :language: ruby + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +.. _ruby-return-documents-limit: + +Limit +----- + +To specify the maximum number of documents returned from a read operation, apply +the ``limit`` option to the operation. You can set this option by chaining the +``limit`` setter method to the ``find`` method. + +The following example finds all restaurants that have a ``cuisine`` field value +of ``'Italian'`` and limits the results to ``5`` documents: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/limit-skip-sort.rb + :start-after: start-limit + :end-before: end-limit + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Philadelhia Grille Express", + "restaurant_id"=>"40364305"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Isle Of Capri Restaurant", + "restaurant_id"=>"40364373"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Marchis Restaurant", + "restaurant_id"=>"40364668"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Crystal Room", + "restaurant_id"=>"40365013"} + {"_id"=>BSON::ObjectId('...'), ... , name"=>"Forlinis Restaurant", + "restaurant_id"=>"40365098"} + +.. tip:: + + The preceding example returns the first five documents matched by the query + according to their :manual:`natural order ` + in the database. The following section describes how to return the documents + in a specified order. + +.. _ruby-return-documents-sort: + +Sort +---- + +To return documents in a specified order, apply the ``sort`` option to +the read operation. You can set this option by chaining the ``sort`` +setter method to the ``find`` method. + +When calling ``sort``, pass the field to sort the results by and the +sort direction. A sort direction value of ``1`` sorts values from lowest +to highest, and a value of ``-1`` sorts them from highest to lowest. + +The following example returns all documents that have a ``cuisine`` field value +of ``'Italian'``, sorted in ascending order of ``name`` field values: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/limit-skip-sort.rb + :start-after: start-sort + :end-before: end-sort + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"(Lewis Drug Store) Locanda Vini E Olii", + "restaurant_id"=>"40804423"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"101 Restaurant And Bar", + "restaurant_id"=>"40560108"} + ... + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Zucchero E Pomodori", + "restaurant_id"=>"41189590"} + +.. _ruby-return-documents-skip: + +Skip +---- + +To skip a specified number of documents before returning your query results, apply +the ``skip`` option to the read operation. You can set this option by chaining the +``skip`` setter method to the ``find`` method. + +The following example returns all documents that have a ``borough`` field value +of ``'Manhattan'`` and skips the first ``10`` documents: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/limit-skip-sort.rb + :start-after: start-skip + :end-before: end-skip + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Cafe Metro", "restaurant_id"=>"40363298"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Lexler Deli", "restaurant_id"=>"40363426"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Domino'S Pizza", "restaurant_id"=>"40363644"} + ... + +.. _ruby-return-documents-combine: + +Combine Limit, Sort, and Skip +----------------------------- + +You can chain the ``limit``, ``sort``, and ``skip`` methods to a single +``find`` method call. This allows you to set a maximum number of sorted documents +to return from the read operation, skipping a specified number of documents before +returning. + +The following example returns ``5`` documents that have a ``cuisine`` value of +``'Italian'``. The results are sorted in ascending order by the ``name`` field value, +skipping the first ``10`` documents: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/limit-skip-sort.rb + :start-after: start-limit-sort-skip + :end-before: end-limit-sort-skip + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acqua", "restaurant_id"=>"40871070"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acqua Restaurant", + "restaurant_id"=>"41591488"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acqua Santa", "restaurant_id"=>"40735858"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acquista Trattoria", + "restaurant_id"=>"40813992"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acquolina Catering", "restaurant_id"=>"41381423"} + +.. note:: + + The order in which you call these methods doesn't change the documents + that are returned. The {+driver-short+} automatically reorders the calls to + perform the sort operation first, the skip operation next, and then the limit + operation. + +Additional Information +---------------------- + +For more information about retrieving documents, see the :ref:`ruby-retrieve` guide. + +.. TODO: For more information about specifying a query, see the :ref:`ruby-specify-query` guide. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the ``find`` method and its options, see the `API documentation. +<{+api-root+}/Mongo/Collection.html#find-instance_method>`__ \ No newline at end of file