Skip to content

Commit 8899aef

Browse files
norareidynorareidy
authored
DOCSP-45194: Retrieve data (#96)
* DOCSP-45194: Retrieve data * edits * build errors * api links * JB feedback
1 parent 1dc855c commit 8899aef

File tree

6 files changed

+311
-3
lines changed

6 files changed

+311
-3
lines changed

‎source/get-started/create-a-connection-string.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,4 +55,4 @@ when applicable, and connection options.
5555
After completing these steps, you have a connection string that
5656
contains your database username and password.
5757

58-
.. include:: /includes/get-started/quickstart-troubleshoot.rst
58+
.. include:: /includes/get-started/troubleshoot.rst

‎source/get-started/create-a-deployment.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,4 @@ After you complete these steps, you have a new free tier MongoDB
2626
deployment on Atlas, database user credentials, and sample data loaded
2727
in your database.
2828

29-
.. include:: /includes/get-started/quickstart-troubleshoot.rst
29+
.. include:: /includes/get-started/troubleshoot.rst

‎source/includes/read/retrieve.rb

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
require 'bundler/inline'
2+
3+
gemfile do
4+
source 'https://rubygems.org'
5+
gem 'mongo'
6+
end
7+
8+
uri = '<connection string>'
9+
10+
Mongo::Client.new(uri) do |client|
11+
# start-db-coll
12+
database = client.use('sample_training')
13+
collection = database[:companies]
14+
# end-db-coll
15+
16+
# Finds one document with a "name" value of "LinkedIn"
17+
# start-find-one
18+
document = collection.find(name: 'LinkedIn').first
19+
puts document
20+
# end-find-one
21+
22+
# Finds documents with a "founded_year" value of 1970
23+
# start-find-many
24+
results = collection.find(founded_year: 1970)
25+
# end-find-many
26+
27+
# start-cursor
28+
results.each do |doc|
29+
puts doc
30+
end
31+
# end-cursor
32+
33+
34+
# Finds and prints up to 2 documents with a "number_of_employees" value of 1000
35+
# start-modify
36+
limit_results = collection.find(number_of_employees: 1000).limit(2)
37+
38+
limit_results.each do |doc|
39+
puts doc
40+
end
41+
# end-modify
42+
end
43+

‎source/index.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,12 @@
1414

1515
Get Started </get-started>
1616
Connect </connect>
17+
Read Data </read>
1718
View the Source <https://github.com/mongodb/mongo-ruby-driver>
1819
API Documentation <{+api-root+}>
1920

2021
.. TODO:
2122
Databases & Collections </databases-collections>
22-
Read Data </read>
2323
Write Data </write>
2424
Operations on Replica Sets </read-write-pref>
2525
Indexes </indexes>

‎source/read.txt

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
.. _ruby-read:
2+
3+
======================
4+
Read Data from MongoDB
5+
======================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:description: Learn how to use the Ruby driver to read data from MongoDB.
19+
:keywords: usage examples, save, crud, read, code example
20+
21+
.. toctree::
22+
:titlesonly:
23+
:maxdepth: 1
24+
25+
Retrieve Data </read/retrieve>

‎source/read/retrieve.txt

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
.. _ruby-retrieve:
2+
3+
=============
4+
Retrieve Data
5+
=============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: code examples, read, query, cursor
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to retrieve
24+
data from a MongoDB collection by using **read operations**. You can call the
25+
``find`` method on a collection to retrieve documents that match a set of
26+
criteria.
27+
28+
Sample Data
29+
~~~~~~~~~~~
30+
31+
The examples in this guide use the ``companies`` collection in the ``sample_training``
32+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
33+
from your {+language+} application, create a ``Mongo::Client`` object that connects to
34+
an Atlas cluster and assign the following values to your ``database`` and ``collection``
35+
variables:
36+
37+
.. literalinclude:: /includes/read/retrieve.rb
38+
:language: ruby
39+
:dedent:
40+
:start-after: start-db-coll
41+
:end-before: end-db-coll
42+
43+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
44+
:atlas:`Get Started with Atlas </getting-started>` guide.
45+
46+
.. _ruby-retrieve-find:
47+
48+
Find Documents
49+
--------------
50+
51+
To retrieve documents from a collection, use the ``find`` method. This method
52+
takes a **query filter** parameter and returns a ``Mongo::Collection::View`` object,
53+
which represents the query. The driver defers the query execution until you
54+
fetch the results by using methods like ``first`` or ``each``. After you request
55+
the results, the driver sends the query to the server and returns a ``Mongo::Cursor``
56+
object from which you can access the results.
57+
58+
You can chain option methods to the ``find`` method to refine the results of the operation.
59+
60+
.. TODO: To learn more about query filters, see the :ref:`ruby-specify-query` guide.
61+
62+
.. _ruby-retrieve-find-multiple:
63+
64+
Find Multiple Documents
65+
~~~~~~~~~~~~~~~~~~~~~~~
66+
67+
To find multiple documents in a collection, pass a query filter to the
68+
``find`` method that specifies the criteria of the documents you want to retrieve.
69+
70+
The following example uses the ``find`` method to find all documents in which
71+
the ``founded_year`` field has the value ``1970``:
72+
73+
.. literalinclude:: /includes/read/retrieve.rb
74+
:language: ruby
75+
:dedent:
76+
:start-after: start-find-many
77+
:end-before: end-find-many
78+
79+
When you call the ``each`` method on the ``Mongo::Collection::View`` object representing
80+
the query, the driver returns a ``Mongo::Cursor`` object. A cursor is a mechanism that allows an
81+
application to iterate over database results while holding only a subset of them in
82+
memory at a given time. Cursors are useful when your ``find`` method returns a large
83+
amount of documents.
84+
85+
The following code calls the ``each`` method to iterate over the query results:
86+
87+
.. io-code-block::
88+
:copyable:
89+
90+
.. input:: /includes/read/retrieve.rb
91+
:start-after: start-cursor
92+
:end-before: end-cursor
93+
:language: ruby
94+
:dedent:
95+
96+
.. output::
97+
:visible: false
98+
99+
{"_id"=>BSON::ObjectId('...'), "name"=>"Mitsubishi Motors", "permalink"=>"mitsubishi-motors",
100+
"crunchbase_url"=>"http://www.crunchbase.com/company/mitsubishi-motors",
101+
"homepage_url"=>"http://www.mitsubishi-motors.com", ...}
102+
{"_id"=>BSON::ObjectId('...'), "name"=>"Western Digital", "permalink"=>"western-digital",
103+
"crunchbase_url"=>"http://www.crunchbase.com/company/western-digital",
104+
"homepage_url"=>"http://www.wdc.com/en", ...}
105+
{"_id"=>BSON::ObjectId('...'), "name"=>"Celarayn", "permalink"=>"celarayn",
106+
"crunchbase_url"=>"http://www.crunchbase.com/company/celarayn",
107+
"homepage_url"=>"http://www.celarayn.es", ...}
108+
109+
.. note:: Find All Documents
110+
111+
To find all documents in a collection, call the ``find`` method
112+
without passing a query filter:
113+
114+
.. code-block:: ruby
115+
116+
results = collection.find
117+
118+
.. _ruby-retrieve-find-one:
119+
120+
Find One Document
121+
~~~~~~~~~~~~~~~~~
122+
123+
To find a single document in a collection, call the ``find`` method and pass a query
124+
filter that specifies the criteria of the document you want to find. Then, chain
125+
the ``first`` method to ``find``.
126+
127+
If the query filter matches more than one document, the ``first`` method retrieves the *first*
128+
matching document from the operation results.
129+
130+
The following example chains the ``first`` method to ``find`` to find the first
131+
document in which the ``name`` field has the value ``'LinkedIn'``:
132+
133+
.. io-code-block::
134+
:copyable:
135+
136+
.. input:: /includes/read/retrieve.rb
137+
:start-after: start-find-one
138+
:end-before: end-find-one
139+
:language: ruby
140+
:dedent:
141+
142+
.. output::
143+
:visible: false
144+
145+
{"_id"=>BSON::ObjectId('...'), "name"=>"LinkedIn", "permalink"=>"linkedin",
146+
"crunchbase_url"=>"http://www.crunchbase.com/company/linkedin",
147+
"homepage_url"=>"http://linkedin.com", "blog_url"=>"http://blog.linkedin.com",
148+
...}
149+
150+
.. tip:: Sort Order
151+
152+
The ``first`` method returns the first document in
153+
:manual:`natural order </reference/glossary/#std-term-natural-order>`
154+
on disk if no sort criteria is specified.
155+
156+
.. _ruby-retrieve-modify:
157+
158+
Modify Find Behavior
159+
~~~~~~~~~~~~~~~~~~~~
160+
161+
You can chain option methods to the ``find`` method to modify the operation
162+
results. The following table describes some of these options:
163+
164+
.. list-table::
165+
:widths: 30 70
166+
:header-rows: 1
167+
168+
* - Option
169+
- Description
170+
171+
* - ``batch_size``
172+
- | The number of documents to return per batch. The default value is ``101``.
173+
| **Type**: ``Integer``
174+
175+
* - ``collation``
176+
- | The collation to use for the operation. The default value is the collation
177+
specified for the collection.
178+
| **Type**: ``Hash``
179+
180+
* - ``comment``
181+
- | The comment to attach to the operation.
182+
| **Type**: ``Object``
183+
184+
* - ``limit``
185+
- | The maximum number of documents the operation can return.
186+
| **Type**: ``Integer``
187+
188+
* - ``skip``
189+
- | The number of documents to skip before returning results.
190+
| **Type**: ``Integer``
191+
192+
* - ``sort``
193+
- | The order in which the operation returns matching documents.
194+
| **Type**: ``Hash``
195+
196+
The following example uses the ``find`` method to find all documents in which
197+
the ``number_of_employees`` field has the value ``1000``. The example uses the
198+
``limit`` option to return a maximum of ``2`` results:
199+
200+
.. io-code-block::
201+
:copyable:
202+
203+
.. input:: /includes/read/retrieve.rb
204+
:start-after: start-modify
205+
:end-before: end-modify
206+
:language: ruby
207+
:dedent:
208+
209+
.. output::
210+
:visible: false
211+
212+
{"_id"=>BSON::ObjectId('...'), "name"=>"Akamai Technologies", "permalink"=>"akamai-technologies",
213+
"crunchbase_url"=>"http://www.crunchbase.com/company/akamai-technologies",
214+
"homepage_url"=>"http://www.akamai.com", ...}
215+
{"_id"=>BSON::ObjectId('...'), "name"=>"Yodle", "permalink"=>"yodle",
216+
"crunchbase_url"=>"http://www.crunchbase.com/company/yodle",
217+
"homepage_url"=>"http://www.yodle.com", ...}
218+
219+
For a full list of options, see the API documentation for the
220+
`find <{+api-root+}/Mongo/Collection.html#find-instance_method>`__
221+
method.
222+
223+
.. _ruby-retrieve-additional-information:
224+
225+
Additional Information
226+
----------------------
227+
228+
.. TODO:
229+
To learn more about query filters, see the :ref:`ruby-specify-query` guide.
230+
To view code examples of retrieving documents with the {+driver-short+}, see :ref:`ruby-read`.
231+
232+
API Documentation
233+
~~~~~~~~~~~~~~~~~
234+
235+
To learn more about any of the methods or types discussed in this
236+
guide, see the following API documentation:
237+
238+
- `find <{+api-root+}/Mongo/Collection.html#find-instance_method>`__
239+
- `Mongo::Collection::View <{+api-root+}/Mongo/Collection/View.html>`__
240+
- `Mongo::Cursor <{+api-root+}/Mongo/Cursor.html>`__

0 commit comments

Comments
 (0)