From 6c392fc46334e415af91df6498cc9ad270facc3d Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 17 Dec 2024 11:58:16 -0500 Subject: [PATCH 1/3] DOCSP-45196: Limit, skip, and sort --- source/includes/read/limit-skip-sort.rb | 51 +++++ source/read.txt | 3 +- source/read/specify-documents-to-return.txt | 201 ++++++++++++++++++++ 3 files changed, 254 insertions(+), 1 deletion(-) create mode 100644 source/includes/read/limit-skip-sort.rb create mode 100644 source/read/specify-documents-to-return.txt 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 e9822bf6..dda3cbe8 100644 --- a/source/read.txt +++ b/source/read.txt @@ -22,4 +22,5 @@ Read Data from MongoDB :titlesonly: :maxdepth: 1 - Retrieve Data \ No newline at end of file + Retrieve Data + Specify Documents to Return \ No newline at end of file diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt new file mode 100644 index 00000000..222f620e --- /dev/null +++ b/source/read/specify-documents-to-return.txt @@ -0,0 +1,201 @@ +.. _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": {"$oid": "..."}, ... , "name": "Isle Of Capri Resturant", "restaurant_id": "40364373"} + {"_id": {"$oid": "..."}, ... , "name": "Marchis Restaurant", "restaurant_id": "40364668"} + {"_id": {"$oid": "..."}, ... , "name": "Crystal Room", "restaurant_id": "40365013"} + {"_id": {"$oid": "..."}, ... , "name": "Forlinis Restaurant", "restaurant_id": "40365098"} + {"_id": {"$oid": "..."}, ... , "name": "Angelo Of Mulberry St.", "restaurant_id": "40365293"} + +.. 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": {"$oid": "..."}, ... , "name": "44 Sw Ristorante & Bar", "restaurant_id": "40698807"} + {"_id": {"$oid": "..."}, ... , "name": "900 Park", "restaurant_id": "41707964"} + {"_id": {"$oid": "..."}, ... , "name": "A Voce", "restaurant_id": "41434084"} + ... + {"_id": {"$oid": "..."}, ... , "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": {"$oid": "..."}, ... , "name": "Cafe Metro", "restaurant_id": "40363298"} + {"_id": {"$oid": "..."}, ... , "name": "Lexler Deli", "restaurant_id": "40363426"} + {"_id": {"$oid": "..."}, ... , "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": {"$oid": "..."}, ... , "name": "Acqua", "restaurant_id": "40871070"} + {"_id": {"$oid": "..."}, ... , "name": "Acqua Restaurant", "restaurant_id": "41591488"} + {"_id": {"$oid": "..."}, ... , "name": "Acqua Santa", "restaurant_id": "40735858"} + {"_id": {"$oid": "..."}, ... , "name": "Acquista Trattoria", "restaurant_id": "40813992"} + {"_id": {"$oid": "..."}, ... , "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 From 1f295e05cae9bf37efe727ae7c5d6b8d6c5b03fc Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 17 Dec 2024 13:37:26 -0500 Subject: [PATCH 2/3] code output --- source/read/specify-documents-to-return.txt | 43 +++++++++++++-------- 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt index 222f620e..8e18d12f 100644 --- a/source/read/specify-documents-to-return.txt +++ b/source/read/specify-documents-to-return.txt @@ -72,11 +72,16 @@ of ``'Italian'`` and limits the results to ``5`` documents: .. output:: :visible: false - {"_id": {"$oid": "..."}, ... , "name": "Isle Of Capri Resturant", "restaurant_id": "40364373"} - {"_id": {"$oid": "..."}, ... , "name": "Marchis Restaurant", "restaurant_id": "40364668"} - {"_id": {"$oid": "..."}, ... , "name": "Crystal Room", "restaurant_id": "40365013"} - {"_id": {"$oid": "..."}, ... , "name": "Forlinis Restaurant", "restaurant_id": "40365098"} - {"_id": {"$oid": "..."}, ... , "name": "Angelo Of Mulberry St.", "restaurant_id": "40365293"} + {"_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:: @@ -113,11 +118,13 @@ of ``'Italian'``, sorted in ascending order of ``name`` field values: .. output:: :visible: false - {"_id": {"$oid": "..."}, ... , "name": "44 Sw Ristorante & Bar", "restaurant_id": "40698807"} - {"_id": {"$oid": "..."}, ... , "name": "900 Park", "restaurant_id": "41707964"} - {"_id": {"$oid": "..."}, ... , "name": "A Voce", "restaurant_id": "41434084"} + {"_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": {"$oid": "..."}, ... , "name": "Zucchero E Pomodori", "restaurant_id": "41189590"} + {"_id"=>BSON::ObjectId('...'), ", "name"=>"Zucchero E Pomodori", + "restaurant_id"=>"41189590"} .. _ruby-return-documents-skip: @@ -143,9 +150,9 @@ of ``'Manhattan'`` and skips the first ``10`` documents: .. output:: :visible: false - {"_id": {"$oid": "..."}, ... , "name": "Cafe Metro", "restaurant_id": "40363298"} - {"_id": {"$oid": "..."}, ... , "name": "Lexler Deli", "restaurant_id": "40363426"} - {"_id": {"$oid": "..."}, ... , "name": "Domino'S Pizza", "restaurant_id": "40363644"} + {"_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: @@ -174,11 +181,13 @@ skipping the first ``10`` documents: .. output:: :visible: false - {"_id": {"$oid": "..."}, ... , "name": "Acqua", "restaurant_id": "40871070"} - {"_id": {"$oid": "..."}, ... , "name": "Acqua Restaurant", "restaurant_id": "41591488"} - {"_id": {"$oid": "..."}, ... , "name": "Acqua Santa", "restaurant_id": "40735858"} - {"_id": {"$oid": "..."}, ... , "name": "Acquista Trattoria", "restaurant_id": "40813992"} - {"_id": {"$oid": "..."}, ... , "name": "Acquolina Catering", "restaurant_id": "41381423"} + {"_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:: From 6e2f6f2f4ee00fec949216c0a1497daa3f779b5c Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 17 Dec 2024 13:47:40 -0500 Subject: [PATCH 3/3] fixes --- source/read/specify-documents-to-return.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/read/specify-documents-to-return.txt b/source/read/specify-documents-to-return.txt index 8e18d12f..fc80bac6 100644 --- a/source/read/specify-documents-to-return.txt +++ b/source/read/specify-documents-to-return.txt @@ -123,7 +123,7 @@ of ``'Italian'``, sorted in ascending order of ``name`` field values: {"_id"=>BSON::ObjectId('...'), ... , "name"=>"101 Restaurant And Bar", "restaurant_id"=>"40560108"} ... - {"_id"=>BSON::ObjectId('...'), ", "name"=>"Zucchero E Pomodori", + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Zucchero E Pomodori", "restaurant_id"=>"41189590"} .. _ruby-return-documents-skip: @@ -150,9 +150,9 @@ of ``'Manhattan'`` and skips the first ``10`` documents: .. 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"} + {"_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: @@ -187,7 +187,7 @@ skipping the first ``10`` documents: {"_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"} + {"_id"=>BSON::ObjectId('...'), ... , "name"=>"Acquolina Catering", "restaurant_id"=>"41381423"} .. note::