From 26210c42db10318df9e6a49e00891981d7b8e483 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Dec 2024 11:13:52 -0500 Subject: [PATCH 1/5] DOCSP-45194: Retrieve data --- source/includes/read/retrieve.rb | 47 +++++++ source/index.txt | 2 +- source/read.txt | 25 ++++ source/read/retrieve.txt | 229 +++++++++++++++++++++++++++++++ 4 files changed, 302 insertions(+), 1 deletion(-) create mode 100644 source/includes/read/retrieve.rb create mode 100644 source/read.txt create mode 100644 source/read/retrieve.txt diff --git a/source/includes/read/retrieve.rb b/source/includes/read/retrieve.rb new file mode 100644 index 00000000..28c74ca1 --- /dev/null +++ b/source/includes/read/retrieve.rb @@ -0,0 +1,47 @@ +require 'bundler/inline' + +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = '' + +begin + client = Mongo::Client.new(uri) + + # start-db-coll + database = client.use('sample_training') + collection = database[:companies] + # end-db-coll + + # Finds one document with a "name" value of "LinkedIn" + # start-find-one + document = collection.find({ 'name' => 'LinkedIn' }).first + puts document + # end-find-one + + # Finds documents with a "founded_year" value of 1970 + # start-find-many + results = collection.find({ 'founded_year' => 1970 }) + # end-find-many + + # start-cursor + results.each do |doc| + puts doc + end + # end-cursor + + + # Finds and prints up to 5 documents with a "number_of_employees" value of 1000 + # start-modify + limit_results = collection.find({ 'number_of_employees' => 1000 }).limit(5) + + limit_results.each do |doc| + puts doc + end + # end-modify +ensure + client&.close +end + diff --git a/source/index.txt b/source/index.txt index c696db05..7f476e11 100644 --- a/source/index.txt +++ b/source/index.txt @@ -14,12 +14,12 @@ Get Started Connect + Read Data View the Source API Documentation <{+api-root+}> .. TODO: Databases & Collections - Read Data Write Data Operations on Replica Sets Indexes diff --git a/source/read.txt b/source/read.txt new file mode 100644 index 00000000..ca901ec8 --- /dev/null +++ b/source/read.txt @@ -0,0 +1,25 @@ +.. _ruby-read: + +====================== +Read Data from MongoDB +====================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use the Ruby driver to read data to MongoDB. + :keywords: usage examples, save, crud, read, code example + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Retrieve Data \ No newline at end of file diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt new file mode 100644 index 00000000..0fa572a2 --- /dev/null +++ b/source/read/retrieve.txt @@ -0,0 +1,229 @@ +.. _ruby-retrieve: + +============= +Retrieve Data +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code examples, read, query, cursor + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to retrieve +data from a MongoDB collection by using **read operations**. You can call the +``find`` method on a collection to retrieve documents that match a set of +criteria. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``companies`` collection in the ``sample_training`` +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/retrieve.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-retrieve-find: + +Find Documents +-------------- + +To retrieve documents from a collection, use the ``find`` method. This method +takes a **query filter** parameter and returns a ``Mongo::Collection::View`` object, +which represents the query. The driver defers the query execution until you +fetch the results by using methods like ``first`` or ``each``. After you request +the results, the driver sends the query to the server and returns a ``Mongo::Cursor`` +object from which you can access the results. + +You can chain option methods to the ``find`` method to refine the results of the operation. + +.. TODO: To learn more about query filters, see the :ref:`ruby-specify-query` guide. + +.. _ruby-retrieve-find-multiple: + +Find Multiple Documents +~~~~~~~~~~~~~~~~~~~~~~~ + +To find multiple documents in a collection, pass a query filter to the +``find`` method that specifies the criteria of the documents you want to retrieve. + +The following example uses the ``find`` method to find all documents in which +the ``founded_year`` field has the value ``1970``: + +.. literalinclude:: /includes/read/retrieve.rb + :language: ruby + :dedent: + :start-after: start-find-many + :end-before: end-find-many + +When you call the ``each`` method on the ``Mongo::Collection::View`` object representing +the query, the driver returns a ``Mongo::Cursor`` object. A cursor is a mechanism that allows an +application to iterate over database results while holding only a subset of them in +memory at a given time. Cursors are useful when your ``find`` method returns a large +amount of documents. + +The following code calls the ``each`` method to iterate over the query results: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/retrieve.rb + :start-after: start-cursor + :end-before: end-cursor + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"_id":{"$oid":"..."},"name":"Mitsubishi Motors","permalink":"mitsubishi-motors", + "crunchbase_url":"http:\/\/www.crunchbase.com\/company\/mitsubishi-motors", + ... } + + {"_id":{"$oid":"..."},"name":"Western Digital","permalink":"western-digital", + "crunchbase_url":"http:\/\/www.crunchbase.com\/company\/western-digital", + ... } + + {"_id":{"$oid":"..."},"name":"Celarayn","permalink":"celarayn","crunchbase_url": + "http:\/\/www.crunchbase.com\/company\/celarayn", + ... } + +.. note:: Find All Documents + + To find all documents in a collection, call the ``find`` method + without passing a query filter: + + .. code-block:: ruby + + results = collection.find + +.. _ruby-retrieve-find-one: + +Find One Document +~~~~~~~~~~~~~~~~~ + +To find a single document in a collection, call the ``find`` method and pass a query +filter that specifies the criteria of the document you want to find. Then, chain +the ``first`` method to ``find``. + +If the query filter matches more than one document, the ``first`` method retrieves the *first* +matching document from the operation results. + +The following example chains the ``first`` method to ``find`` to find the first +document in which the ``name`` field has the value ``'LinkedIn'``: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/retrieve.rb + :start-after: start-find-one + :end-before: end-find-one + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"_id"=>BSON::ObjectId('...'), "name"=>"LinkedIn", "permalink"=>"linkedin", + "crunchbase_url"=>"http://www.crunchbase.com/company/linkedin", + "homepage_url"=>"http://linkedin.com", "blog_url"=>"http://blog.linkedin.com", + ...} + +.. tip:: Sort Order + + The ``first`` method returns the first document in + :manual:`natural order ` + on disk if no sort criteria is specified. + +.. _ruby-retrieve-modify: + +Modify Find Behavior +~~~~~~~~~~~~~~~~~~~~ + +You can chain option methods to the ``find`` method to modify the operation +results. The following table describes some of these options: + +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Option + - Description + + * - ``batch_size`` + - | The number of documents to return per batch. The default value is ``101``. + | **Type**: ``Integer`` + + * - ``collation`` + - | The collation to use for the operation. The default value is the collation + specified for the collection. + | **Type**: ``Hash`` + + * - ``comment`` + - | The comment to attach to the operation. + | **Type**: ``Object`` + + * - ``limit`` + - | The maximum number of documents the operation can return. + | **Type**: ``Integer`` + + * - ``skip`` + - | The number of documents to skip before returning results. + | **Type**: ``Integer`` + + * - ``sort`` + - | The order in which the operation returns matching documents. + | **Type**: ``Hash`` + +The following example uses the ``find`` method to find all documents in which +the ``number_of_employees`` field has the value ``1000``. The example uses the +``limit`` option to return a maximum of ``5`` results: + +.. literalinclude:: /includes/read/retrieve.rb + :language: ruby + :emphasize-lines: 3 + :start-after: start-modify + :end-before: end-modify + +For a full list of options, see the API documentation for the +`find <{+api-root}/Mongo/Collection.html#find-instance_method>`__ +method. + +.. _ruby-retrieve-additional-information: + +Additional Information +---------------------- + +.. TODO: + To learn more about query filters, see the :ref:`ruby-specify-query` guide. + To view code examples of retrieving documents with the {+driver-short+}, see :ref:`ruby-read`. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `find <{+api-root}/Mongo/Collection.html#find-instance_method>`__ +- `Mongo::Collection::View <{+api-root}/Mongo/Collection/View.html>`__ +- `Mongo::Cursor <{+api-root}/Mongo/Cursor.html>`__ From 41191a64fffef67cf1d5aa91a3a848ef859fe89c Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Dec 2024 11:22:35 -0500 Subject: [PATCH 2/5] edits --- source/includes/read/retrieve.rb | 4 +-- source/read/retrieve.txt | 45 ++++++++++++++++++++------------ 2 files changed, 30 insertions(+), 19 deletions(-) diff --git a/source/includes/read/retrieve.rb b/source/includes/read/retrieve.rb index 28c74ca1..35355497 100644 --- a/source/includes/read/retrieve.rb +++ b/source/includes/read/retrieve.rb @@ -33,9 +33,9 @@ # end-cursor - # Finds and prints up to 5 documents with a "number_of_employees" value of 1000 + # Finds and prints up to 2 documents with a "number_of_employees" value of 1000 # start-modify - limit_results = collection.find({ 'number_of_employees' => 1000 }).limit(5) + limit_results = collection.find({ 'number_of_employees' => 1000 }).limit(2) limit_results.each do |doc| puts doc diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index 0fa572a2..e5077717 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -96,17 +96,15 @@ The following code calls the ``each`` method to iterate over the query results: .. output:: :visible: false - {"_id":{"$oid":"..."},"name":"Mitsubishi Motors","permalink":"mitsubishi-motors", - "crunchbase_url":"http:\/\/www.crunchbase.com\/company\/mitsubishi-motors", - ... } - - {"_id":{"$oid":"..."},"name":"Western Digital","permalink":"western-digital", - "crunchbase_url":"http:\/\/www.crunchbase.com\/company\/western-digital", - ... } - - {"_id":{"$oid":"..."},"name":"Celarayn","permalink":"celarayn","crunchbase_url": - "http:\/\/www.crunchbase.com\/company\/celarayn", - ... } + {"_id"=>BSON::ObjectId('...'), "name"=>"Mitsubishi Motors", "permalink"=>"mitsubishi-motors", + "crunchbase_url"=>"http://www.crunchbase.com/company/mitsubishi-motors", + "homepage_url"=>"http://www.mitsubishi-motors.com", ...} + {"_id"=>BSON::ObjectId('...'), "name"=>"Western Digital", "permalink"=>"western-digital", + "crunchbase_url"=>"http://www.crunchbase.com/company/western-digital", + "homepage_url"=>"http://www.wdc.com/en", ...} + {"_id"=>BSON::ObjectId('...'), "name"=>"Celarayn", "permalink"=>"celarayn", + "crunchbase_url"=>"http://www.crunchbase.com/company/celarayn", + "homepage_url"=>"http://www.celarayn.es", ...} .. note:: Find All Documents @@ -197,13 +195,26 @@ results. The following table describes some of these options: The following example uses the ``find`` method to find all documents in which the ``number_of_employees`` field has the value ``1000``. The example uses the -``limit`` option to return a maximum of ``5`` results: +``limit`` option to return a maximum of ``2`` results: -.. literalinclude:: /includes/read/retrieve.rb - :language: ruby - :emphasize-lines: 3 - :start-after: start-modify - :end-before: end-modify +.. io-code-block:: + :copyable: + + .. input:: /includes/read/retrieve.rb + :start-after: start-modify + :end-before: end-modify + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"_id"=>BSON::ObjectId('...'), "name"=>"Akamai Technologies", "permalink"=>"akamai-technologies", + "crunchbase_url"=>"http://www.crunchbase.com/company/akamai-technologies", + "homepage_url"=>"http://www.akamai.com", ...} + {"_id"=>BSON::ObjectId('...'), "name"=>"Yodle", "permalink"=>"yodle", + "crunchbase_url"=>"http://www.crunchbase.com/company/yodle", + "homepage_url"=>"http://www.yodle.com", ...} For a full list of options, see the API documentation for the `find <{+api-root}/Mongo/Collection.html#find-instance_method>`__ From 2bb58f23f248fdc880186ac5839a4de040f7c93f Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Dec 2024 11:24:17 -0500 Subject: [PATCH 3/5] build errors --- source/get-started/create-a-connection-string.txt | 2 +- source/get-started/create-a-deployment.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/get-started/create-a-connection-string.txt b/source/get-started/create-a-connection-string.txt index 92d15da9..8c5871c2 100644 --- a/source/get-started/create-a-connection-string.txt +++ b/source/get-started/create-a-connection-string.txt @@ -55,4 +55,4 @@ when applicable, and connection options. After completing these steps, you have a connection string that contains your database username and password. -.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file +.. include:: /includes/get-started/troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/create-a-deployment.txt b/source/get-started/create-a-deployment.txt index 21925b7f..e19b53c1 100644 --- a/source/get-started/create-a-deployment.txt +++ b/source/get-started/create-a-deployment.txt @@ -26,4 +26,4 @@ After you complete these steps, you have a new free tier MongoDB deployment on Atlas, database user credentials, and sample data loaded in your database. -.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file +.. include:: /includes/get-started/troubleshoot.rst \ No newline at end of file From f73eaf64c033a8151962c4d1183c5708f9853e35 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 11 Dec 2024 11:29:12 -0500 Subject: [PATCH 4/5] api links --- source/read/retrieve.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index e5077717..fb1aa094 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -217,7 +217,7 @@ the ``number_of_employees`` field has the value ``1000``. The example uses the "homepage_url"=>"http://www.yodle.com", ...} For a full list of options, see the API documentation for the -`find <{+api-root}/Mongo/Collection.html#find-instance_method>`__ +`find <{+api-root+}/Mongo/Collection.html#find-instance_method>`__ method. .. _ruby-retrieve-additional-information: @@ -235,6 +235,6 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `find <{+api-root}/Mongo/Collection.html#find-instance_method>`__ -- `Mongo::Collection::View <{+api-root}/Mongo/Collection/View.html>`__ -- `Mongo::Cursor <{+api-root}/Mongo/Cursor.html>`__ +- `find <{+api-root+}/Mongo/Collection.html#find-instance_method>`__ +- `Mongo::Collection::View <{+api-root+}/Mongo/Collection/View.html>`__ +- `Mongo::Cursor <{+api-root+}/Mongo/Cursor.html>`__ From c05e8959b69c95a5c5448218d9acc1f9c2761893 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 12 Dec 2024 16:38:23 -0500 Subject: [PATCH 5/5] JB feedback --- source/includes/read/retrieve.rb | 12 ++++-------- source/read.txt | 2 +- 2 files changed, 5 insertions(+), 9 deletions(-) diff --git a/source/includes/read/retrieve.rb b/source/includes/read/retrieve.rb index 35355497..848e2a2e 100644 --- a/source/includes/read/retrieve.rb +++ b/source/includes/read/retrieve.rb @@ -7,9 +7,7 @@ uri = '' -begin - client = Mongo::Client.new(uri) - +Mongo::Client.new(uri) do |client| # start-db-coll database = client.use('sample_training') collection = database[:companies] @@ -17,13 +15,13 @@ # Finds one document with a "name" value of "LinkedIn" # start-find-one - document = collection.find({ 'name' => 'LinkedIn' }).first + document = collection.find(name: 'LinkedIn').first puts document # end-find-one # Finds documents with a "founded_year" value of 1970 # start-find-many - results = collection.find({ 'founded_year' => 1970 }) + results = collection.find(founded_year: 1970) # end-find-many # start-cursor @@ -35,13 +33,11 @@ # Finds and prints up to 2 documents with a "number_of_employees" value of 1000 # start-modify - limit_results = collection.find({ 'number_of_employees' => 1000 }).limit(2) + limit_results = collection.find(number_of_employees: 1000).limit(2) limit_results.each do |doc| puts doc end # end-modify -ensure - client&.close end diff --git a/source/read.txt b/source/read.txt index ca901ec8..e9822bf6 100644 --- a/source/read.txt +++ b/source/read.txt @@ -15,7 +15,7 @@ Read Data from MongoDB :values: reference .. meta:: - :description: Learn how to use the Ruby driver to read data to MongoDB. + :description: Learn how to use the Ruby driver to read data from MongoDB. :keywords: usage examples, save, crud, read, code example .. toctree::