Skip to content

Commit 6dda8ff

Browse files
rustagirrustagir
authored
DOCSP-41128: delete docs (#17)
* DOCSP-41128: delete docs * first pass fixes * MM PR fixes 1 * vale fix
1 parent bd33ef7 commit 6dda8ff

File tree

4 files changed

+250
-14
lines changed

4 files changed

+250
-14
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,5 @@ version = "v{+version-number+}"
2424
patch-version-number = "{+version-number+}.0"
2525
mdb-server = "MongoDB Server"
2626
stable-api = "Stable API"
27-
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
27+
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/"

‎source/includes/write/delete.kt

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import com.mongodb.client.model.DeleteOptions
2+
import com.mongodb.client.model.Filters.*
3+
import com.mongodb.kotlin.client.MongoClient
4+
5+
// start-data-class
6+
data class Restaurant(val name: String, val borough: String)
7+
// end-data-class
8+
9+
fun main() {
10+
val uri = "<connection string>"
11+
12+
val mongoClient = MongoClient.create(uri)
13+
val database = mongoClient.getDatabase("sample_restaurants")
14+
val collection = database.getCollection<Movie>("restaurants")
15+
16+
// start-delete-one
17+
val filter = eq(Restaurant::name.name, "Happy Garden")
18+
val result = collection.deleteOne(filter)
19+
// end-delete-one
20+
21+
// start-delete-many
22+
val filter = and(
23+
eq(Restaurant::borough.name, "Brooklyn"),
24+
eq(Restaurant::name.name, "Starbucks")
25+
)
26+
val result = collection.deleteMany(filter)
27+
// end-delete-many
28+
29+
// start-delete-options
30+
val opts = DeleteOptions().comment("sample comment")
31+
val filter = regex(Restaurant::name.name, "Red")
32+
val result = collection.deleteOne(filter, opts)
33+
// end-delete-options
34+
35+
}

‎source/write-operations.txt

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,18 @@ Write Data to MongoDB
1818
:description: Learn how to use the Kotlin Sync driver to write data to MongoDB.
1919
:keywords: usage examples, save, crud, create, code example
2020

21-
.. .. toctree::
22-
.. :titlesonly:
23-
.. :maxdepth: 1
21+
.. toctree::
22+
:titlesonly:
23+
:maxdepth: 1
24+
25+
/write/delete
26+
2427
..
25-
.. /write/insert
26-
.. /write/update
27-
.. /write/replace
28-
.. /write/delete
29-
.. /write/bulk-write
30-
.. /write/gridfs
28+
/write/insert
29+
/write/update
30+
/write/replace
31+
/write/bulk-write
32+
/write/gridfs
3133

3234
Overview
3335
--------
@@ -149,8 +151,8 @@ collection:
149151
:copyable:
150152
:dedent:
151153

152-
.. To learn more about the ``delete_one()`` method, see the
153-
.. :ref:`Delete Documents <kotlin-sync-write-delete>` guide.
154+
To learn more about the ``deleteOne()`` method, see the
155+
:ref:`Delete Documents <kotlin-sync-write-delete>` guide.
154156

155157
Delete Multiple
156158
---------------
@@ -165,8 +167,8 @@ collection:
165167
:copyable:
166168
:dedent:
167169

168-
.. To learn more about the ``delete_many()`` method, see the
169-
.. :ref:`Delete Documents <kotlin-sync-write-delete>` guide.
170+
To learn more about the ``deleteMany()`` method, see the
171+
:ref:`Delete Documents <kotlin-sync-write-delete>` guide.
170172

171173
Bulk Write
172174
----------

‎source/write/delete.txt

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
.. _kotlin-sync-write-delete:
2+
3+
================
4+
Delete 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: remove, drop, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to remove
24+
documents from a MongoDB collection by performing **delete operations**.
25+
26+
A delete operation removes one or more documents from a MongoDB collection.
27+
You can perform a delete operation by using the ``deleteOne()`` or
28+
``deleteMany()`` methods.
29+
30+
.. TODO .. tip:: Interactive Lab
31+
32+
.. This page includes a short interactive lab that demonstrates how to
33+
.. modify data by using the ``deleteMany()`` method. You can complete this
34+
.. lab directly in your browser window without installing MongoDB or a code editor.
35+
36+
.. To start the lab, click the :guilabel:`Open Interactive Tutorial` button at the
37+
.. top of the page. To expand the lab to a full-screen format, click the
38+
.. full-screen button (:guilabel:`⛶`) in the top-right corner of the lab pane.
39+
40+
Sample Data
41+
~~~~~~~~~~~
42+
43+
The examples in this guide use the ``sample_restaurants.restaurants`` collection
44+
from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
45+
free MongoDB Atlas cluster and load the sample datasets, see the
46+
:atlas:`Get Started with Atlas </getting-started>` guide.
47+
48+
The documents in this collection are modeled by the following {+language+} data class:
49+
50+
.. literalinclude:: /includes/write/delete.kt
51+
:start-after: start-data-class
52+
:end-before: end-data-class
53+
:language: kotlin
54+
:copyable:
55+
:dedent:
56+
57+
Delete Operations
58+
-----------------
59+
60+
You can perform delete operations in MongoDB by using the following methods:
61+
62+
- ``deleteOne()``, which deletes *the first document* that matches the search criteria
63+
- ``deleteMany()``, which deletes *all documents* that match the search criteria
64+
65+
Each delete method requires a **query filter** document, which specifies the
66+
search criteria that determine which documents to select for removal.
67+
To learn more about query filters, see the :ref:`kotlin-sync-specify-query` guide.
68+
69+
Delete One Document
70+
~~~~~~~~~~~~~~~~~~~
71+
72+
The following example uses the ``deleteOne()`` method to remove a
73+
document in which the value of the ``name`` field is ``"Happy Garden"``:
74+
75+
.. literalinclude:: /includes/write/delete.kt
76+
:start-after: start-delete-one
77+
:end-before: end-delete-one
78+
:language: kotlin
79+
:copyable:
80+
:dedent:
81+
82+
Delete Multiple Documents
83+
~~~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
The following example uses the ``deleteMany()`` method to remove all documents
86+
in which the value of the ``borough`` field is ``"Brooklyn"`` and the
87+
value of the ``name`` field is ``"Starbucks"``:
88+
89+
.. literalinclude:: /includes/write/delete.kt
90+
:start-after: start-delete-many
91+
:end-before: end-delete-many
92+
:language: kotlin
93+
:copyable:
94+
:dedent:
95+
96+
Customize the Delete Operation
97+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98+
99+
The ``deleteOne()`` and ``deleteMany()`` methods optionally accept a
100+
``DeleteOptions`` parameter, which represents options you can use to
101+
configure the delete operation. If you don't specify any
102+
options, the driver performs the delete operation with default settings.
103+
104+
The following table describes the setter methods that you can use to
105+
configure a ``DeleteOptions`` instance:
106+
107+
.. list-table::
108+
:widths: 30 70
109+
:header-rows: 1
110+
111+
* - Property
112+
- Description
113+
114+
* - ``collation()``
115+
- | Specifies the kind of language collation to use when sorting
116+
results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
117+
in the {+mdb-server+} manual.
118+
119+
* - ``hint()``
120+
- | Specifies the index to use when matching documents.
121+
For more information, see the :manual:`hint statement </reference/command/delete/#std-label-deletes-array-hint>`
122+
in the {+mdb-server+} manual.
123+
124+
* - ``hintString()``
125+
- | Specifies the index as a string to use when matching documents.
126+
For more information, see the :manual:`hint statement </reference/command/delete/#std-label-deletes-array-hint>`
127+
in the {+mdb-server+} manual.
128+
129+
* - ``let()``
130+
- | Provides a map of parameter names and values to set top-level
131+
variables for the operation. 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/delete/#std-label-delete-let-syntax>` in the
135+
{+mdb-server+} manual.
136+
137+
* - ``comment()``
138+
- | Sets a comment to attach to the operation. For more
139+
information, see the :manual:`delete command
140+
fields </reference/command/delete/#command-fields>` guide in the
141+
{+mdb-server+} manual for more information.
142+
143+
The following code creates options and uses the ``comment()`` method to
144+
add a comment to the delete operation. Then, the example uses the
145+
``deleteMany()`` method to delete all documents in the ``restaurants``
146+
collection in which the value of the ``name`` field includes the string
147+
``"Red"``.
148+
149+
.. literalinclude:: /includes/write/delete.kt
150+
:start-after: start-delete-options
151+
:end-before: end-delete-options
152+
:language: kotlin
153+
:copyable:
154+
:dedent:
155+
156+
.. tip::
157+
158+
If you use the the ``deleteOne()`` method in the preceding example
159+
instead of the ``deleteMany()`` method, the driver deletes only the
160+
first document that matches the query filter.
161+
162+
Return Value
163+
~~~~~~~~~~~~
164+
165+
The ``deleteOne()`` and ``deleteMany()`` methods each return a
166+
``DeleteResult`` instance. You can access the following information from
167+
a ``DeleteResult`` instance:
168+
169+
- ``deletedCount``, which indicates the number of documents deleted
170+
- ``wasAcknowledged()``, which returns ``true`` if the server
171+
acknowledges the result
172+
173+
If the query filter does not match any documents, the driver doesn't delete any
174+
documents and the value of ``deletedCount`` is ``0``.
175+
176+
.. note::
177+
178+
If the ``wasAcknowledged()`` method returns ``false``, trying to
179+
access the ``deletedCount`` property results in an
180+
``InvalidOperation`` exception. The driver cannot
181+
determine these values if the server does not acknowledge the write
182+
operation.
183+
184+
API Documentation
185+
~~~~~~~~~~~~~~~~~
186+
187+
To learn more about any of the methods or types discussed in this
188+
guide, see the following API Documentation:
189+
190+
- `deleteOne() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-one.html>`__
191+
- `deleteMany() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/delete-many.html>`__
192+
- `DeleteResult <{+core-api+}/com/mongodb/client/result/DeleteResult.html>`__
193+
194+
.. .. _kotlin-sync-delete-instruqt-lab:
195+
196+
.. .. instruqt:: /mongodb-docs/tracks/...
197+
.. :title: deleteMany() Lesson
198+
.. :drawer:

0 commit comments

Comments
 (0)