Skip to content

Commit c7932db

Browse files
rustagirrustagir
committed
DOCSP-41129: update docs
1 parent 0379473 commit c7932db

File tree

5 files changed

+272
-7
lines changed

5 files changed

+272
-7
lines changed

‎snooty.toml

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

0 commit comments

Comments
 (0)