Skip to content

Commit 71d723e

Browse files
jordan-smith721jordan-smith721
authored
1 parent 203730b commit 71d723e

File tree

1 file changed

+147
-173
lines changed

1 file changed

+147
-173
lines changed

‎source/fundamentals/crud/find.txt‎

Lines changed: 147 additions & 173 deletions
Original file line numberDiff line numberDiff line change
@@ -1,217 +1,191 @@
1-
.. uses tutorial.rst
2-
3-
Getting a Single Document With the ``~pymongo.collection.Collection.find_one`` method
4-
---------------------------------------------------------------------------------
5-
The most basic type of query that can be performed in MongoDB is
6-
the ``~pymongo.collection.Collection.find_one`` method. This method returns a
7-
single document matching a query (or ``None`` if there are no
8-
matches). It is useful when you know there is only one matching
9-
document, or are only interested in the first match. Here we use
10-
the ``~pymongo.collection.Collection.find_one`` method to get the first
11-
document from the posts collection:
1+
.. _pymongo-find:
122

13-
.. code-block:: python
3+
==================
4+
Retrieve Documents
5+
==================
146

15-
>>> import pprint
16-
>>> pprint.pprint(posts.find_one())
17-
{'_id': ObjectId('...'),
18-
'author': 'Mike',
19-
'date': datetime.datetime(...),
20-
'tags': ['mongodb', 'python', 'pymongo'],
21-
'text': 'My first blog post!'}
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
2212

23-
The result is a dictionary matching the one that we inserted previously.
13+
.. facet::
14+
:name: genre
15+
:values: reference
2416

25-
.. note:: The returned document contains an ``"_id"``, which was
26-
automatically added on insert.
17+
.. meta::
18+
:keywords: retrieve, query
2719

28-
the ``~pymongo.collection.Collection.find_one`` method also supports querying
29-
on specific elements that the resulting document must match. To limit
30-
our results to a document with author "Mike" we do:
20+
In this guide, you can learn how to use {+driver-short+} to retrieve data from a
21+
MongoDB collection.
3122

32-
.. code-block:: python
23+
Find a Single Document
24+
----------------------
3325

34-
>>> pprint.pprint(posts.find_one({"author": "Mike"}))
35-
{'_id': ObjectId('...'),
36-
'author': 'Mike',
37-
'date': datetime.datetime(...),
38-
'tags': ['mongodb', 'python', 'pymongo'],
39-
'text': 'My first blog post!'}
26+
The ``~pymongo.collection.Collection.find_one()`` method returns a
27+
single document matching a query, or ``None`` if there are no
28+
matches. Use this method when you know there is only one matching
29+
document, or to see only the first document that matches a query.
4030

41-
If we try with a different author, like "Eliot", we'll get no result:
31+
The following example uses the ``find_one()`` method to retrieve the first
32+
document from the ``posts`` collection:
4233

4334
.. code-block:: python
4435

45-
>>> posts.find_one({"author": "Eliot"})
46-
>>>
36+
>>> import pprint
37+
>>> pprint.pprint(posts.find_one())
38+
{'_id': ObjectId('...'),
39+
'author': 'Mike',
40+
'date': datetime.datetime(...),
41+
'tags': ['mongodb', 'python', 'pymongo'],
42+
'text': 'My first blog post!'}
4743

48-
.. _querying-by-objectid:
44+
The ``find_one()`` method also supports querying
45+
with specific elements that the resulting document must match.
4946

50-
Querying By ObjectId
51-
--------------------
52-
We can also find a post by its ``_id``, which in our example is an ObjectId:
47+
The following example retrieves a document with a value of "Mike" in the
48+
``author`` field:
5349

5450
.. code-block:: python
5551

56-
>>> post_id
57-
ObjectId(...)
58-
>>> pprint.pprint(posts.find_one({"_id": post_id}))
59-
{'_id': ObjectId('...'),
60-
'author': 'Mike',
61-
'date': datetime.datetime(...),
62-
'tags': ['mongodb', 'python', 'pymongo'],
63-
'text': 'My first blog post!'}
52+
>>> pprint.pprint(posts.find_one({"author": "Mike"}))
53+
{'_id': ObjectId('...'),
54+
'author': 'Mike',
55+
'date': datetime.datetime(...),
56+
'tags': ['mongodb', 'python', 'pymongo'],
57+
'text': 'My first blog post!'}
6458

65-
Note that an ObjectId is not the same as its string representation:
59+
If the search query doesn't find a matching document, the ``find_one()`` method returns nothing:
6660

6761
.. code-block:: python
6862

69-
>>> post_id_as_str = str(post_id)
70-
>>> posts.find_one({"_id": post_id_as_str}) # No result
71-
>>>
63+
>>> posts.find_one({"author": "Eliot"})
64+
>>>
65+
66+
.. _querying-by-objectid:
67+
68+
Querying By ObjectId
69+
~~~~~~~~~~~~~~~~~~~~
70+
71+
You can also find a document by its ``_id``.
7272

73-
A common task in web applications is to get an ObjectId from the
74-
request URL and find the matching document. It's necessary in this
75-
case to **convert the ObjectId from a string** before passing it to
76-
``find_one``:
73+
The following example retrieves a document based on the ``_id``, which is an
74+
``ObjectId``:
7775

7876
.. code-block:: python
7977

80-
from bson.objectid import ObjectId
78+
>>> post_id
79+
ObjectId(...)
80+
>>> pprint.pprint(posts.find_one({"_id": post_id}))
81+
{'_id': ObjectId('...'),
82+
'author': 'Mike',
83+
'date': datetime.datetime(...),
84+
'tags': ['mongodb', 'python', 'pymongo'],
85+
'text': 'My first blog post!'}
8186

82-
# The web framework gets post_id from the URL and passes it as a string
83-
def get(post_id):
84-
# Convert from string to ObjectId:
85-
document = client.db.collection.find_one({'_id': ObjectId(post_id)})
87+
.. note::
88+
89+
An ``ObjectId`` is not the same as its string representation.
8690

87-
.. seealso:: :ref:`web-application-querying-by-objectid`
91+
.. code-block:: python
8892

89-
Querying for More Than One Document
90-
-----------------------------------
91-
To get more than a single document as the result of a query we use the
92-
the ``~pymongo.collection.Collection.find`` method
93-
method. the ``~pymongo.collection.Collection.find`` method returns a
94-
``~pymongo.cursor.Cursor`` instance, which allows us to iterate
95-
over all matching documents. For example, we can iterate over every
96-
document in the ``posts`` collection:
93+
>>> post_id_as_str = str(post_id)
94+
>>> posts.find_one({"_id": post_id_as_str}) # No result
95+
>>>
96+
97+
A common task in web applications is to get an ``ObjectId`` from the
98+
request URL and find the matching document. To do this, you must convert the
99+
``ObjectId`` from a string before passing it to ``find_one()``:
97100

98101
.. code-block:: python
99102

100-
>>> for post in posts.find():
101-
... pprint.pprint(post)
102-
...
103-
{'_id': ObjectId('...'),
104-
'author': 'Mike',
105-
'date': datetime.datetime(...),
106-
'tags': ['mongodb', 'python', 'pymongo'],
107-
'text': 'My first blog post!'}
108-
{'_id': ObjectId('...'),
109-
'author': 'Mike',
110-
'date': datetime.datetime(...),
111-
'tags': ['bulk', 'insert'],
112-
'text': 'Another post!'}
113-
{'_id': ObjectId('...'),
114-
'author': 'Eliot',
115-
'date': datetime.datetime(...),
116-
'text': 'and pretty easy too!',
117-
'title': 'MongoDB is fun'}
118-
119-
Just like we did with the ``~pymongo.collection.Collection.find_one`` method,
120-
we can pass a document to the ``~pymongo.collection.Collection.find`` method
121-
to limit the returned results. Here, we get only those documents whose
122-
author is "Mike":
103+
from bson.objectid import ObjectId
123104

124-
.. code-block:: python
105+
# The web framework gets post_id from the URL and passes it as a string
106+
def get(post_id):
107+
# Convert from string to ObjectId:
108+
document = client.db.collection.find_one({'_id': ObjectId(post_id)})
109+
110+
For more information about querying by ``ObjectId``, see :ref:`web-application-querying-by-objectid`.
111+
112+
Find Multiple Documents
113+
-----------------------
114+
115+
To retrieve more than a single document as the result of a query, use the
116+
the ``~pymongo.collection.Collection.find()`` method. The
117+
``find()`` method returns a ``~pymongo.cursor.Cursor`` instance, which allows you to iterate
118+
over all matching documents.
125119

126-
>>> for post in posts.find({"author": "Mike"}):
127-
... pprint.pprint(post)
128-
...
129-
{'_id': ObjectId('...'),
130-
'author': 'Mike',
131-
'date': datetime.datetime(...),
132-
'tags': ['mongodb', 'python', 'pymongo'],
133-
'text': 'My first blog post!'}
134-
{'_id': ObjectId('...'),
135-
'author': 'Mike',
136-
'date': datetime.datetime(...),
137-
'tags': ['bulk', 'insert'],
138-
'text': 'Another post!'}
139-
140-
Querying for More Than One Document
141-
-----------------------------------
142-
To get more than a single document as the result of a query we use the
143-
the ``~pymongo.collection.Collection.find`` method
144-
method. the ``~pymongo.collection.Collection.find`` method returns a
145-
``~pymongo.cursor.Cursor`` instance, which allows us to iterate
146-
over all matching documents. For example, we can iterate over every
147-
document in the ``posts`` collection:
120+
The following example retrieves and iterates over every document in the
121+
``posts`` collection:
148122

149123
.. code-block:: python
150124

151-
>>> for post in posts.find():
152-
... pprint.pprint(post)
153-
...
154-
{'_id': ObjectId('...'),
155-
'author': 'Mike',
156-
'date': datetime.datetime(...),
157-
'tags': ['mongodb', 'python', 'pymongo'],
158-
'text': 'My first blog post!'}
159-
{'_id': ObjectId('...'),
160-
'author': 'Mike',
161-
'date': datetime.datetime(...),
162-
'tags': ['bulk', 'insert'],
163-
'text': 'Another post!'}
164-
{'_id': ObjectId('...'),
165-
'author': 'Eliot',
166-
'date': datetime.datetime(...),
167-
'text': 'and pretty easy too!',
168-
'title': 'MongoDB is fun'}
169-
170-
Just like we did with the ``~pymongo.collection.Collection.find_one`` method,
171-
we can pass a document to the ``~pymongo.collection.Collection.find`` method
172-
to limit the returned results. Here, we get only those documents whose
173-
author is "Mike":
125+
>>> for post in posts.find():
126+
... pprint.pprint(post)
127+
...
128+
{'_id': ObjectId('...'),
129+
'author': 'Mike',
130+
'date': datetime.datetime(...),
131+
'tags': ['mongodb', 'python', 'pymongo'],
132+
'text': 'My first blog post!'}
133+
{'_id': ObjectId('...'),
134+
'author': 'Mike',
135+
'date': datetime.datetime(...),
136+
'tags': ['bulk', 'insert'],
137+
'text': 'Another post!'}
138+
{'_id': ObjectId('...'),
139+
'author': 'Eliot',
140+
'date': datetime.datetime(...),
141+
'text': 'and pretty easy too!',
142+
'title': 'MongoDB is fun'}
143+
144+
You can pass a document to the ``find()`` method
145+
to limit the returned results.
146+
147+
The following example finds only documents with a value of "Mike" in the
148+
``author`` field:
174149

175150
.. code-block:: python
176151

177-
>>> for post in posts.find({"author": "Mike"}):
178-
... pprint.pprint(post)
179-
...
180-
{'_id': ObjectId('...'),
181-
'author': 'Mike',
182-
'date': datetime.datetime(...),
183-
'tags': ['mongodb', 'python', 'pymongo'],
184-
'text': 'My first blog post!'}
185-
{'_id': ObjectId('...'),
186-
'author': 'Mike',
187-
'date': datetime.datetime(...),
188-
'tags': ['bulk', 'insert'],
189-
'text': 'Another post!'}
152+
>>> for post in posts.find({"author": "Mike"}):
153+
... pprint.pprint(post)
154+
...
155+
{'_id': ObjectId('...'),
156+
'author': 'Mike',
157+
'date': datetime.datetime(...),
158+
'tags': ['mongodb', 'python', 'pymongo'],
159+
'text': 'My first blog post!'}
160+
{'_id': ObjectId('...'),
161+
'author': 'Mike',
162+
'date': datetime.datetime(...),
163+
'tags': ['bulk', 'insert'],
164+
'text': 'Another post!'}
190165

191166
Range Queries
192167
-------------
193-
MongoDB supports many different types of `advanced queries
194-
<https://www.mongodb.com/docs/manual/reference/operator/>`_. As an
195-
example, lets perform a query where we limit results to posts older
196-
than a certain date, but also sort the results by author:
168+
MongoDB supports many different types of :manual:`advanced queries </reference/operator/>`.
169+
For example, you can perform a query that limits results to posts older
170+
than a certain date, and also sorts the results by the ``author`` field:
197171

198172
.. code-block:: python
199173

200-
>>> d = datetime.datetime(2009, 11, 12, 12)
201-
>>> for post in posts.find({"date": {"$lt": d}}).sort("author"):
202-
... pprint.pprint(post)
203-
...
204-
{'_id': ObjectId('...'),
205-
'author': 'Eliot',
206-
'date': datetime.datetime(...),
207-
'text': 'and pretty easy too!',
208-
'title': 'MongoDB is fun'}
209-
{'_id': ObjectId('...'),
210-
'author': 'Mike',
211-
'date': datetime.datetime(...),
212-
'tags': ['bulk', 'insert'],
213-
'text': 'Another post!'}
214-
215-
Here we use the special ``"$lt"`` operator to do a range query, and
216-
also call the ``~pymongo.cursor.Cursor.sort`` method to sort the results
217-
by author.
174+
>>> d = datetime.datetime(2009, 11, 12, 12)
175+
>>> for post in posts.find({"date": {"$lt": d}}).sort("author"):
176+
... pprint.pprint(post)
177+
...
178+
{'_id': ObjectId('...'),
179+
'author': 'Eliot',
180+
'date': datetime.datetime(...),
181+
'text': 'and pretty easy too!',
182+
'title': 'MongoDB is fun'}
183+
{'_id': ObjectId('...'),
184+
'author': 'Mike',
185+
'date': datetime.datetime(...),
186+
'tags': ['bulk', 'insert'],
187+
'text': 'Another post!'}
188+
189+
The preceding example uses the ``"$lt"`` operator to perform a range query. It
190+
also calls the ``~pymongo.cursor.Cursor.sort()`` method to sort the results
191+
by the ``author`` field.

0 commit comments

Comments
 (0)