Skip to content

Commit 920c193

Browse files
mongoKartmongoKart
authored
DOCSP-37543 - Retrieve Data (#37)
1 parent f7c47c2 commit 920c193

File tree

4 files changed

+255
-5
lines changed

4 files changed

+255
-5
lines changed

‎snooty.toml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
name = "pymongo"
22
title = "PyMongo"
3-
toc_landing_pages = [
4-
]
3+
toc_landing_pages = ["/read"]
54

65
intersphinx = [
76
"https://www.mongodb.com/docs/manual/objects.inv",
@@ -12,13 +11,14 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
1211

1312
[constants]
1413
driver-short = "PyMongo"
14+
driver-long = "PyMongo, the MongoDB synchronous Python driver,"
1515
language = "Python"
1616
mongo-community = "MongoDB Community Edition"
1717
mongo-enterprise = "MongoDB Enterprise Edition"
18-
docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
18+
docs-branch = "master" # always set this to the docs branch (i.e. master, 1.7, 1.8, etc.)
1919
version-number = "4.6"
20-
patch-version-number = "{+version-number+}.1" # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
20+
patch-version-number = "{+version-number+}.1" # always set this to the driver branch (i.e. 1.7.0, 1.8.0, etc.)
2121
version = "v{+version-number+}"
2222
example = "https://raw.githubusercontent.com/mongodb/docs-pymongo/{+docs-branch+}/source/includes/code-examples"
2323
stable-api = "Stable API"
24-
api-root = "https://pymongo.readthedocs.io/en/{+patch-version-number+}/api/index.html"
24+
api-root = "https://pymongo.readthedocs.io/en/{+patch-version-number+}/api/"

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ MongoDB PyMongo Documentation
1616
/quick-start
1717
/whats-new
1818
/fundamentals
19+
/read
1920
/tools
2021
API Documentation <{+api-root+}>
2122
/faq

‎source/read.txt

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. _pymongo-read:
2+
3+
======================
4+
Read Data from MongoDB
5+
======================
6+
7+
.. meta::
8+
:description: Learn how to use (+driver-short+} to read data from MongoDB.
9+
10+
.. toctree::
11+
:titlesonly:
12+
:maxdepth: 1
13+
14+
/read/retrieve
15+
16+
- :ref:`pymongo-retrieve`

‎source/read/retrieve.txt

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
.. _pymongo-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, search, cursor
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use {+driver-long+} to retrieve
24+
data from a MongoDB collection by using read operations. You can call the
25+
``find()`` or ``find_one()`` method to retrieve documents that match a set of criteria.
26+
27+
.. TODO: .. tip:: Interactive Lab
28+
You can complete a short interactive lesson that demonstrates how to
29+
retrieve data by using the ``Find()`` method in an in-browser coding
30+
experience. To learn more, see the :ref:`pymongo-retrieve-instruqt-lab`
31+
section of this guide.
32+
33+
Sample Data
34+
~~~~~~~~~~~
35+
36+
The examples in this guide use the ``sample_restaurants.restaurants`` collection
37+
from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
38+
free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<pymongo-get-started>`.
39+
40+
.. _pymongo-retrieve-find:
41+
42+
Find Documents
43+
--------------
44+
45+
{+driver-short+} includes two methods for retrieving documents from a collection:
46+
``find_one()`` and ``find()``.
47+
These methods take a **query filter** and return one or more matching documents.
48+
A query filter is an object that specifies the documents you want to retrieve in
49+
your query.
50+
51+
.. TODO: To learn more about query filters, see :ref:`pymongo-specify-query`.
52+
53+
.. _pymongo-retrieve-find-one:
54+
55+
Find One Document
56+
~~~~~~~~~~~~~~~~~
57+
58+
To find a single document in a collection, call the ``find_one()`` method and pass a query
59+
filter that specifies the criteria of the document you want to find.
60+
If more than one document matches the query
61+
filter, this method returns the *first* matching document from the retrieved
62+
results as a Python dictionary. If no documents match the query filter, the method returns
63+
``None``.
64+
65+
.. tip::
66+
67+
The ``find_one()`` method is useful when you know there's only one matching document,
68+
or you're only interested in the first match.
69+
70+
The following examples use the ``find_one()`` method to find the first document where
71+
the ``"cuisine"`` field has the value ``"Bakery"``. Select the corresponding tab to see
72+
an example in a ``.py`` file or the Python shell.
73+
74+
.. tabs::
75+
76+
.. tab:: File
77+
:tabid: find-one-file
78+
79+
.. code-block:: python
80+
:copyable: true
81+
82+
restaurant = sample_restaurants.restaurants.find_one({"cuisine": "Bakery"})
83+
84+
.. tab:: Shell
85+
:tabid: find-one-shell
86+
87+
.. code-block:: python
88+
:copyable: true
89+
90+
>>> sample_restaurants.restaurants.find_one({"cuisine": "Bakery"})
91+
92+
.. tip:: Sort Order
93+
94+
The ``find_one()`` method returns the first document in
95+
:manual:`natural order </reference/glossary/#std-term-natural-order>`
96+
on disk if no sort criteria is specified.
97+
98+
.. To learn more about sorting, see the TODO: sorting page.
99+
100+
.. TODO: To see a full example of using the ``find_one()`` method to find a single document, see
101+
:ref:`pymongo-retrieve-additional-information`.
102+
103+
.. _pymongo-retrieve-find-multiple:
104+
105+
Find Multiple Documents
106+
~~~~~~~~~~~~~~~~~~~~~~~
107+
108+
To find multiple documents in a collection, pass a query filter to the ``find()``
109+
method that specifies the criteria of the documents you want to retrieve.
110+
111+
The following examples use the ``find()`` method to find all documents where
112+
the ``"cuisine"`` field has the value ``"Spanish"``. Select the corresponding tab to see
113+
an example in a ``.py`` file or the Python shell.
114+
115+
.. tabs::
116+
117+
.. tab:: File
118+
:tabid: find-multiple-file
119+
120+
.. code-block:: python
121+
:copyable: true
122+
123+
cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"})
124+
125+
.. tab:: Shell
126+
:tabid: find-multiple-shell
127+
128+
.. code-block:: python
129+
:copyable: true
130+
131+
>>> sample_restaurants.restaurants.find({"cuisine": "Spanish"})
132+
133+
You can use a **cursor** to iterate over the documents returned by the ``find()``
134+
method. A cursor is a mechanism that allows an application to iterate over database
135+
results while holding only a subset of them in memory at a given time. Cursors
136+
are useful when your ``find()`` method returns a large amount of documents.
137+
138+
You can iterate over the documents in a cursor by using a ``for-in`` loop, as shown in
139+
the following examples:
140+
141+
.. tabs::
142+
143+
.. tab:: File
144+
:tabid: iterate-file
145+
146+
.. code-block:: python
147+
:copyable: true
148+
149+
cursor = sample_restaurants.restaurants.find({"cuisine": "Spanish"})
150+
for restaurant in cursor:
151+
...
152+
153+
.. tab:: Shell
154+
:tabid: iterate-shell
155+
156+
.. code-block:: python
157+
:copyable: true
158+
159+
>>> for restaurant in sample_restaurants.restaurants.find({"cuisine": "Spanish"}):
160+
...
161+
162+
.. TODO: To see a full example of using the ``Find()`` method to find multiple documents,
163+
see :ref:`pymongo-retrieve-additional-information`.
164+
165+
.. note:: Find All Documents
166+
167+
To find all documents in a collection, pass an empty filter
168+
to the ``find()`` method:
169+
170+
.. code-block:: python
171+
172+
all_restaurants = sample_restaurants.restaurants.find()
173+
174+
.. TODO: To see a fully runnable example of using the ``find()`` method to find all documents, see
175+
:ref:`pymongo-retrieve-additional-information`.
176+
177+
Modify Find Behavior
178+
~~~~~~~~~~~~~~~~~~~~
179+
180+
You can modify the behavior of the ``find()`` and ``find_one()`` methods by passing
181+
named arguments to them. The following table describes the commonly used arguments:
182+
183+
.. list-table::
184+
:widths: 30 70
185+
:header-rows: 1
186+
187+
* - Argument
188+
- Description
189+
190+
* - ``batch_size``
191+
- | Limits the number of documents to hold in a cursor at a given time.
192+
193+
* - ``collation``
194+
- | An instance of the ``Collation`` class that sets the collation options.
195+
196+
* - ``comment``
197+
- | A string to attach to the query. This can help you trace and interpret the
198+
operation in the server logs and in profile data. To learn more about query comments,
199+
see the :manual:`$comment </reference/operator/query/comment/>` page.
200+
201+
* - ``hint``
202+
- | The index to use for the query.
203+
204+
* - ``max_time_ms``
205+
- | The maximum execution time on the server for this operation. If this time is
206+
exceeded, {+driver-short+} aborts the operation and raises an ``ExecutionTimeout``.
207+
208+
.. TODO: code examples of using these options
209+
210+
For a full list of available arguments, see the
211+
`API documentation <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.find>`__
212+
for the ``find() method``.
213+
214+
.. _pymongo-retrieve-additional-information:
215+
216+
Additional Information
217+
----------------------
218+
219+
.. TODO: To learn more about query filters, see :ref:`pymongo-specify-query`.
220+
221+
.. TODO: To view runnable examples of the ``find()`` and ``find_one()`` methods, see the
222+
:ref:`pymongo-find-one` page.
223+
224+
API Documentation
225+
~~~~~~~~~~~~~~~~~
226+
227+
To learn more about any of the methods or types discussed in this
228+
guide, see the following API documentation:
229+
230+
- `find() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.find>`__
231+
- `find_one() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.find_one>`__
232+
- `Collation <{+api-root+}pymongo/collation.html#pymongo.collation.Collation>`__
233+
- `Cursor <{+api-root+}pymongo/cursor.html#pymongo.cursor.Cursor>`__

0 commit comments

Comments
 (0)