Skip to content

Commit b4ddb51

Browse files
rustagirrustagir
authored
DOCSP-41129: update docs (#21)
* DOCSP-41129: update docs * MM PR fixes 1
1 parent eaa2386 commit b4ddb51

File tree

5 files changed

+276
-7
lines changed

5 files changed

+276
-7
lines changed

‎snooty.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,4 @@ mdb-server = "MongoDB Server"
2727
stable-api = "Stable API"
2828
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
2929
kotlin-docs = "https://kotlinlang.org"
30-
core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/"
30+
core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core"

‎source/connect.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ Be sure to replace all placeholders in the code examples, such as
5353
.. include:: /includes/usage-examples/sample-app-intro.rst
5454

5555
.. literalinclude:: /includes/usage-examples/connect-sample-app.kt
56-
:language: python
56+
:language: kotlin
5757
:copyable: true
5858
:linenos:
5959
:emphasize-lines: 6-8

‎source/includes/write/update.kt

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
import com.mongodb.client.model.Filters.*
2+
import com.mongodb.client.model.UpdateOptions
3+
import com.mongodb.client.model.Updates.*
4+
import com.mongodb.kotlin.client.MongoClient
5+
import org.bson.Document
6+
7+
// start-data-class
8+
data class Restaurant(
9+
val name: String,
10+
val borough: String,
11+
val cuisine: String,
12+
val address: Document
13+
)
14+
// end-data-class
15+
16+
fun main() {
17+
val uri = "<connection string>"
18+
19+
val mongoClient = MongoClient.create(uri)
20+
val database = mongoClient.getDatabase("sample_restaurants")
21+
val collection = database.getCollection<Restaurant>("restaurants")
22+
23+
// start-update-one
24+
val filter = eq(Restaurant::name.name, "Happy Garden")
25+
val update = set(Restaurant::name.name, "Mountain House")
26+
val result = collection.updateOne(filter, update)
27+
// end-update-one
28+
29+
// start-update-many
30+
val filter = eq(Restaurant::name.name, "Starbucks")
31+
val update = rename(Restaurant::address.name, "location")
32+
val result = collection.updateMany(filter, update)
33+
// end-update-many
34+
35+
// start-update-options
36+
val opts = UpdateOptions().upsert(true)
37+
val filter = eq(Restaurant::name.name, "Sunrise Pizzeria")
38+
val update = combine(
39+
set(Restaurant::borough.name, "Queens"),
40+
set(Restaurant::cuisine.name, "Italian")
41+
)
42+
43+
collection.updateOne(filter, update, opts)
44+
// end-update-options
45+
}

‎source/write-operations.txt

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,11 @@ Write Data to MongoDB
2222
:titlesonly:
2323
:maxdepth: 1
2424

25+
/write/update
2526
/write/delete
2627

2728
..
2829
/write/insert
29-
/write/update
3030
/write/replace
3131
/write/bulk-write
3232
/write/gridfs
@@ -103,8 +103,8 @@ collection by creating or editing a field:
103103
:copyable:
104104
:dedent:
105105

106-
.. To learn more about the ``update_one()`` method, see the
107-
.. :ref:`Update Documents <kotlin-sync-write-update>` guide.
106+
To learn more about the ``updateOne()`` method, see the
107+
:ref:`Update Documents <kotlin-sync-write-update>` guide.
108108

109109
Update Multiple
110110
---------------
@@ -119,8 +119,8 @@ collection by creating or editing a field:
119119
:copyable:
120120
:dedent:
121121

122-
.. To learn more about the ``update_many()`` method, see the
123-
.. :ref:`Update Documents <kotlin-sync-write-update>` guide.
122+
To learn more about the ``updateMany()`` method, see the
123+
:ref:`Update Documents <kotlin-sync-write-update>` guide.
124124

125125
Replace One
126126
-----------

‎source/write/update.txt

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
.. _kotlin-sync-write-update:
2+
3+
================
4+
Update 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, operator, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to update
24+
documents in a MongoDB collection by using the ``updateOne()`` and
25+
``updateMany()`` methods.
26+
27+
Sample Data
28+
~~~~~~~~~~~
29+
30+
The examples in this guide use the ``sample_restaurants.restaurants`` collection
31+
from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
32+
free MongoDB Atlas cluster and load the sample datasets, see the
33+
:atlas:`Get Started with Atlas </getting-started>` guide.
34+
35+
The documents in this collection are modeled by the following {+language+} data class:
36+
37+
.. literalinclude:: /includes/write/update.kt
38+
:start-after: start-data-class
39+
:end-before: end-data-class
40+
:language: kotlin
41+
:copyable:
42+
:dedent:
43+
44+
Update Operations
45+
-----------------
46+
47+
You can update documents in MongoDB by using the following methods:
48+
49+
- ``updateOne()``, which updates *the first document* that matches the search criteria
50+
- ``updateMany()``, which updates *all documents* that match the search criteria
51+
52+
Each update method requires the following parameters:
53+
54+
- **Query filter**, which matches which documents to update. To learn
55+
more about query filters, see the :ref:`kotlin-sync-specify-query`
56+
guide.
57+
58+
- **Update document**, which specifies the update operator, or the kind of update to
59+
perform, and the fields and values to be updated. For a list of update
60+
operators and their usages, see the :manual:`Field Update Operators
61+
guide page</reference/operator/update-field/>` in the {+mdb-server+} manual.
62+
63+
Update One Document
64+
~~~~~~~~~~~~~~~~~~~
65+
66+
The following example uses the ``updateOne()`` method to update the
67+
``name`` value of a document from ``"Happy Garden"`` to ``"Mountain
68+
House"``:
69+
70+
.. literalinclude:: /includes/write/update.kt
71+
:start-after: start-update-one
72+
:end-before: end-update-one
73+
:language: kotlin
74+
:copyable:
75+
:dedent:
76+
77+
Update Many Documents
78+
~~~~~~~~~~~~~~~~~~~~~
79+
80+
The following example uses the ``updateMany()`` method to update all documents
81+
in which the ``name`` value is ``"Starbucks"``. The update renames the
82+
``address`` field to ``location``.
83+
84+
.. literalinclude:: /includes/write/update.kt
85+
:start-after: start-update-many
86+
:end-before: end-update-many
87+
:language: kotlin
88+
:copyable:
89+
:dedent:
90+
91+
Customize the Update Operation
92+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93+
94+
The ``updateOne()`` and ``updateMany()`` methods optionally accept
95+
a parameter that sets options to configure the update operation.
96+
If you don't specify any options, the driver performs update
97+
operations with default settings.
98+
99+
The following table describes the setter methods that you can use to
100+
configure an ``UpdateOptions`` instance:
101+
102+
.. list-table::
103+
:widths: 30 70
104+
:header-rows: 1
105+
106+
* - Property
107+
- Description
108+
109+
* - ``upsert()``
110+
- | Specifies whether the update operation performs an upsert operation if no
111+
documents match the query filter. For more information, see the :manual:`upsert
112+
statement </reference/command/update/#std-label-update-command-upsert>`
113+
in the {+mdb-server+} manual.
114+
| Defaults to ``false``
115+
116+
* - ``bypassDocumentValidation()``
117+
- | Specifies whether the update operation bypasses document validation. This lets you
118+
update documents that don't meet the schema validation requirements, if any
119+
exist. For more information about schema validation, see :manual:`Schema
120+
Validation </core/schema-validation/#schema-validation>` in the MongoDB
121+
Server manual.
122+
| Defaults to ``false``.
123+
124+
* - ``collation()``
125+
- | Specifies the kind of language collation to use when sorting
126+
results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
127+
in the {+mdb-server+} manual.
128+
129+
* - ``arrayFilters()``
130+
- | Provides a list of filters that you specify to select which
131+
array elements the update applies to.
132+
133+
* - ``hint()``
134+
- | Sets the index to use when matching documents.
135+
For more information, see the :manual:`hint statement </reference/command/update/#std-label-update-command-hint>`
136+
in the {+mdb-server+} manual.
137+
138+
* - ``let()``
139+
- | Provides a map of parameter names and values to set top-level
140+
variables for the operation. Values must be constant or closed
141+
expressions that don't reference document fields. For more information,
142+
see the :manual:`let statement
143+
</reference/command/update/#std-label-update-let-syntax>` in the
144+
{+mdb-server+} manual.
145+
146+
* - ``comment()``
147+
- | Sets a comment to attach to the operation. For more
148+
information, see the :manual:`update command
149+
fields </reference/command/update/#update>` guide in the
150+
{+mdb-server+} manual for more information.
151+
152+
Modify Update Example
153+
`````````````````````
154+
155+
The following code uses the ``updateOne()`` method to match documents
156+
in which the ``name`` field value is ``"Sunrise Pizzeria"``. It then
157+
sets the ``borough`` value in the first matching document to
158+
``"Queens"`` and the ``cuisine`` value to ``"Italian"``.
159+
160+
Because the ``upsert`` option is set to ``true``, the driver inserts a
161+
new document that has the fields and values specified in the update
162+
document if the query filter doesn't match any existing documents.
163+
164+
.. literalinclude:: /includes/write/update.kt
165+
:start-after: start-update-options
166+
:end-before: end-update-options
167+
:language: kotlin
168+
:copyable:
169+
:dedent:
170+
171+
Return Value
172+
~~~~~~~~~~~~
173+
174+
The ``updateOne()`` and ``updateMany()`` methods each return an ``UpdateResult``
175+
object. You can use the following methods to access information from
176+
an ``UpdateResult`` instance:
177+
178+
.. list-table::
179+
:widths: 30 70
180+
:header-rows: 1
181+
182+
* - Property
183+
- Description
184+
185+
* - ``getMatchedCount()``
186+
- | Indicates the number of documents that matched the query filter, regardless of
187+
how many updates were performed.
188+
189+
* - ``getModifiedCount()``
190+
- | Indicates number of documents modified by the update operation. If an updated
191+
document is identical to the original, it is not included in this
192+
count.
193+
194+
* - ``wasAcknowledged()``
195+
- | Returns ``true`` if the server acknowledged the result.
196+
197+
* - ``getUpsertedId()``
198+
- | Specifies the ``_id`` value of the document that was upserted
199+
in the database, if the driver performed an upsert.
200+
201+
.. note::
202+
203+
If the ``wasAcknowledged()`` method returns ``false``, trying to
204+
access other information from the ``UpdateResult`` instance results in an
205+
``InvalidOperation`` exception. The driver cannot
206+
determine these values if the server does not acknowledge the write
207+
operation.
208+
209+
Additional Information
210+
----------------------
211+
212+
To view runnable code examples that demonstrate how to updates documents by
213+
using the {+driver-short+}, see :ref:`kotlin-sync-write`.
214+
215+
API Documentation
216+
~~~~~~~~~~~~~~~~~
217+
218+
To learn more about any of the methods or types discussed in this
219+
guide, see the following API documentation:
220+
221+
- `updateOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/update-one.html>`__
222+
- `updateMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/update-many.html>`__
223+
- `UpdateOptions <{+core-api+}/com/mongodb/client/model/UpdateOptions.html>`__
224+
- `UpdateResult <{+core-api+}/com/mongodb/client/result/UpdateResult.html>`__

0 commit comments

Comments
 (0)