Skip to content

Commit 6113d11

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-37533 Update & Replace Documents (#42)
1 parent 905a56b commit 6113d11

File tree

5 files changed

+473
-1
lines changed

5 files changed

+473
-1
lines changed

‎source/includes/write/replace.py

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# start-replace-one
2+
restaurants = database["restaurants"]
3+
4+
query_filter = {"name" : "Pizza Town"}
5+
replace_document = { "name" : "Mongo's Pizza",
6+
"cuisine" : "Pizza",
7+
"address" : {
8+
"street" : "123 Pizza St",
9+
"zipCode" : "10003"
10+
},
11+
"borough" : "Manhattan"
12+
}
13+
14+
result = restaurants.replace_one(query_filter, replace_document)
15+
# end-replace-one
16+
17+
# start-replace-options
18+
restaurants = database["restaurants"]
19+
20+
query_filter = {"name" : "Food Town"}
21+
replace_document = { "name" : "Food World",
22+
"cuisine" : "Mixed",
23+
"address" : {
24+
"street" : "123 Food St",
25+
"zipCode" : "10003"
26+
},
27+
"borough" : "Manhattan"
28+
}
29+
30+
result = restaurants.replace_one(query_filter, replace_document, upsert = True)
31+
# end-replace-options

‎source/includes/write/update.py

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# start-update-one
2+
restaurants = database["restaurants"]
3+
4+
query_filter = {'name' : 'Bagels N Buns'}
5+
update_operation = { '$set' :
6+
{ 'name' : '2 Bagels 2 Buns' }
7+
}
8+
9+
result = restaurants.update_one(query_filter, update_operation)
10+
# end-update-one
11+
12+
# start-update-many
13+
restaurants = database["restaurants"]
14+
15+
query_filter = {'cuisine' : 'Pizza'}
16+
update_operation = { '$set' :
17+
{ 'cuisine' : 'Pasta' }
18+
}
19+
20+
result = restaurants.update_many(query_filter, update_operation)
21+
# end-update-many
22+
23+
# start-update-options
24+
restaurants = database["restaurants"]
25+
26+
query_filter = {'borough' : 'Manhattan'}
27+
update_operation = { '$set' :
28+
{ 'borough' : 'Manhattan (north)' }
29+
}
30+
31+
result = restaurants.update_many(query_filter, update_operation, upsert = True)
32+
# end-update-options

‎source/write-operations.txt

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,10 @@ Write Data to MongoDB
1212
:maxdepth: 1
1313

1414
/write/insert
15+
/write/update
16+
/write/replace
17+
18+
- :ref:`pymongo-write-insert`
19+
- :ref:`pymongo-write-update`
20+
- :ref:`pymongo-write-replace`
1521

16-
- :ref:`pymongo-write-insert`

‎source/write/replace.txt

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
.. _pymongo-write-replace:
2+
3+
=================
4+
Replace Documents
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: modify, change, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use {+driver-short+} to perform a replace
24+
operation on a document in a MongoDB collection. A replace operation performs
25+
differently than an update operation. An update operation
26+
modifies only the specified fields in a target document. A replace operation removes *all* fields
27+
in the target document and replaces them with new ones.
28+
29+
To learn more about update operations, see the :ref:`Update Documents guide.
30+
<pymongo-write-update>`
31+
32+
.. .. tip:: Interactive Lab
33+
34+
.. This page includes a short interactive lab that demonstrates how to
35+
.. replace data by using the ``replace_one()`` method. You can complete this
36+
.. lab directly in your browser window without installing MongoDB or a code editor.
37+
38+
.. To start the lab, click the :guilabel:`Open Interactive Tutorial` button at the
39+
.. top of the page. To expand the lab to a full-screen format, click the
40+
.. full-screen button (:guilabel:`⛶`) in the top-right corner of the lab pane.
41+
42+
Sample Data
43+
~~~~~~~~~~~
44+
45+
The examples in this guide use the ``sample_restaurants.restaurants`` collection
46+
from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
47+
free MongoDB Atlas cluster and load the sample datasets, see the
48+
:ref:`<pymongo-get-started>` tutorial.
49+
50+
Replace Operation
51+
-----------------
52+
53+
You can perform a replace operation in MongoDB by using the ``replace_one()`` method.
54+
This method removes all fields except the ``_id`` field from the first document that
55+
matches the search criteria. It then inserts the fields and values you specify into the
56+
document.
57+
58+
Required Parameters
59+
~~~~~~~~~~~~~~~~~~~
60+
61+
The ``replace_one()`` method requires the following parameters:
62+
63+
- A **query filter** document, which determines which documents to replace. For
64+
more information about query filters, see the
65+
:manual:`Query Filter Documents section </core/document/#query-filter-documents>` in
66+
the MongoDB Server manual.
67+
- A **replace** document, which specifies the fields and values to insert in the new
68+
document.
69+
70+
Replace One
71+
-----------
72+
73+
The following example uses the ``replace_one()`` method to replace the fields and values of a
74+
document with a ``name`` field value of ``"Pizza Town"``:
75+
76+
.. literalinclude:: /includes/write/replace.py
77+
:start-after: start-replace-one
78+
:end-before: end-replace-one
79+
:language: python
80+
:copyable:
81+
82+
.. important::
83+
84+
The values of ``_id`` fields are immutable. If your replacement document specifies
85+
a value for the ``_id`` field, it must match the ``_id`` value of the existing document.
86+
87+
Customize the Replace Operation
88+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
89+
90+
The ``replace_one()`` method optionally accepts additional
91+
parameters, which represent options you can use to configure the replace
92+
operation. If you don't specify any additional options, the driver does not customize
93+
the replace operation.
94+
95+
.. list-table::
96+
:widths: 30 70
97+
:header-rows: 1
98+
99+
* - Property
100+
- Description
101+
102+
* - ``upsert``
103+
- | Specifies whether the replace operation performs an upsert operation if no
104+
documents match the query filter. For more information, see the :manual:`upsert
105+
statement </reference/command/update/#std-label-update-command-upsert>`
106+
in the MongoDB Server manual.
107+
| Defaults to ``False``
108+
109+
* - ``bypass_document_validation``
110+
- | Specifies whether the replace operation bypasses document validation. This lets you
111+
replace documents that don't meet the schema validation requirements, if any
112+
exist. For more information about schema validation, see :manual:`Schema
113+
Validation </core/schema-validation/#schema-validation>` in the MongoDB
114+
Server manual.
115+
| Defaults to ``False``.
116+
117+
* - ``collation``
118+
- | Specifies the kind of language collation to use when sorting
119+
results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
120+
in the MongoDB Server manual.
121+
122+
* - ``hint``
123+
- | Gets or sets the index to scan for documents.
124+
For more information, see the :manual:`hint statement </reference/command/update/#std-label-update-command-hint>`
125+
in the MongoDB Server manual.
126+
127+
* - ``session``
128+
- | An instance of ``ClientSession``.
129+
130+
* - ``let``
131+
- | A Map of parameter names and values. Values must be constant or closed
132+
expressions that don't reference document fields. For more information,
133+
see the :manual:`let statement
134+
</reference/command/update/#std-label-update-let-syntax>` in the
135+
MongoDB Server manual.
136+
137+
* - ``comment``
138+
- | A comment to attach to the operation. For more information, see the :manual:`insert command
139+
fields </reference/command/insert/#command-fields>` guide in the
140+
MongoDB Server manual.
141+
142+
The following code uses the ``replace_one()`` method to find the first document where the
143+
``name`` field has the value ``"Food Town"``, then replaces this document
144+
with a new document named ``"Food World"``. Because the ``upsert`` option is
145+
set to ``True``, the driver inserts a new document if the query filter doesn't
146+
match any existing documents.
147+
148+
.. literalinclude:: /includes/write/replace.py
149+
:start-after: start-replace-options
150+
:end-before: end-replace-options
151+
:language: python
152+
:copyable:
153+
154+
Return Value
155+
~~~~~~~~~~~~
156+
157+
The ``replace_one()`` method returns an ``UpdateResult``
158+
object. The ``UpdateResult`` type contains the following properties:
159+
160+
.. list-table::
161+
:widths: 30 70
162+
:header-rows: 1
163+
164+
* - Property
165+
- Description
166+
167+
* - ``matched_count``
168+
- | The number of documents that matched the query filter, regardless of
169+
how many were updated.
170+
171+
* - ``modified_count``
172+
- | The number of documents modified by the update operation. If an updated
173+
document is identical to the original, it is not included in this
174+
count.
175+
176+
* - ``raw_result``
177+
- | The raw result document returned by the server.
178+
179+
* - ``upserted_id``
180+
- | The ID of the document that was upserted in the database, if the driver
181+
performed an upsert. Otherwise ``None``.
182+
183+
Additional Information
184+
----------------------
185+
186+
.. TODO: To learn more about creating query filters, see the :ref:`pymongo-specify-query` guide.
187+
188+
API Documentation
189+
~~~~~~~~~~~~~~~~~
190+
191+
To learn more about any of the methods or types discussed in this
192+
guide, see the following API documentation:
193+
194+
- `replace_one() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.replace_one>`__
195+
- `UpdateResult <{+api-root+}pymongo/results.html#pymongo.results.UpdateResult>`__

0 commit comments

Comments
 (0)