Skip to content

Commit 4104261

Browse files
rustagirrustagir
committed
DOCSP-41128: delete docs
1 parent 12ef143 commit 4104261

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
@@ -23,4 +23,5 @@ version = "v{+version-number+}"
2323
patch-version-number = "{+version-number+}.0"
2424
mdb-server = "MongoDB Server"
2525
stable-api = "Stable API"
26-
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
26+
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
27+
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::name.name, "Happy Garden"),
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 ``delete_one()`` or
28+
``delete_many()`` 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>`.
45+
46+
.. TODO To learn how to create a
47+
.. free MongoDB Atlas cluster and load the sample datasets, see the
48+
.. :ref:`<kotlin-sync-get-started>` tutorial.
49+
50+
The documents in this collection are modeled by the following {+language+} data class:
51+
52+
.. literalinclude:: /includes/write/delete.kt
53+
:start-after: start-data-class
54+
:end-before: end-data-class
55+
:language: kotlin
56+
:copyable:
57+
58+
Delete Operations
59+
-----------------
60+
61+
You can perform delete operations in MongoDB by using the following methods:
62+
63+
- ``deleteOne()``, which deletes *the first document* that matches the search criteria
64+
- ``deleteMany()``, which deletes *all documents* that match the search criteria
65+
66+
Each delete method requires a **query filter** document, which specifies the
67+
search criteria that determine which documents to select for removal.
68+
For more information about query filters, see the
69+
:manual:`Query Filter Documents section </core/document/#query-filter-documents>` in
70+
the {+mdb-server+} manual.
71+
72+
Delete One Document
73+
~~~~~~~~~~~~~~~~~~~
74+
75+
The following example uses the ``deleteOne()`` method to remove a
76+
document in which the value of the ``name`` field is ``"Happy Garden"``:
77+
78+
.. literalinclude:: /includes/write/delete.kt
79+
:start-after: start-delete-one
80+
:end-before: end-delete-one
81+
:language: kotlin
82+
:copyable:
83+
84+
Delete Multiple Documents
85+
~~~~~~~~~~~~~~~~~~~~~~~~~
86+
87+
The following example uses the ``deleteMany()`` method to remove all documents
88+
in which the value of the ``borough`` field is ``"Brooklyn"`` and the
89+
value of the ``name`` field is ``"Starbucks"``:
90+
91+
.. literalinclude:: /includes/write/delete.kt
92+
:start-after: start-delete-many
93+
:end-before: end-delete-many
94+
:language: kotlin
95+
:copyable:
96+
97+
Customize the Delete Operation
98+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99+
100+
The ``deleteOne()`` and ``deleteMany()`` methods optionally accept a
101+
``DeleteOptions`` parameter, which represents options you can use to
102+
configure the delete operation. If you don't specify any additional
103+
options, the driver performs the delete operation with default settings.
104+
105+
The following table describes the setter methods that you can use to
106+
configure a ``DeleteOptions`` instance:
107+
108+
.. list-table::
109+
:widths: 30 70
110+
:header-rows: 1
111+
112+
* - Property
113+
- Description
114+
115+
* - ``collation()``
116+
- | Specifies the kind of language collation to use when sorting
117+
results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
118+
in the {+mdb-server+} manual.
119+
120+
* - ``hint()``
121+
- | Specifies the index to use when matching documents.
122+
For more information, see the :manual:`hint statement </reference/command/delete/#std-label-deletes-array-hint>`
123+
in the {+mdb-server+} manual.
124+
125+
* - ``hintString()``
126+
- | Specifies the index as a string to use when matching documents.
127+
For more information, see the :manual:`hint statement </reference/command/delete/#std-label-deletes-array-hint>`
128+
in the {+mdb-server+} manual.
129+
130+
* - ``let()``
131+
- | Provides a map of parameter names and values to set top-level
132+
variables for the operation. Values must be constant or closed
133+
expressions that don't reference document fields. For more information,
134+
see the :manual:`let statement
135+
</reference/command/delete/#std-label-delete-let-syntax>` in the
136+
{+mdb-server+} manual.
137+
138+
* - ``comment()``
139+
- | Sets a comment to attach to the operation. For more
140+
information, see the :manual:`delete command
141+
fields </reference/command/delete/#command-fields>` guide in the
142+
{+mdb-server+} manual for more information.
143+
144+
The following code uses the ``deleteMany()`` method to delete all
145+
documents in the ``restaurants`` collection in which the value of the
146+
``name`` field includes the string ``"Red"``. The example also uses the
147+
``comment()`` method to add a comment to the operation and passes the
148+
resulting ``DeleteOptions`` instance to the ``deleteMany()`` method:
149+
150+
.. literalinclude:: /includes/write/delete.kt
151+
:start-after: start-delete-options
152+
:end-before: end-delete-options
153+
:language: kotlin
154+
:copyable:
155+
156+
.. tip::
157+
158+
If the preceding example used the ``deleteOne()`` method instead of
159+
the ``deleteMany()`` method, the driver would delete only the first
160+
document that matched 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+
.. note::
174+
175+
If the ``wasAcknowledged()`` method returns ``false``, trying to
176+
access the ``deletedCount`` property results in an
177+
``InvalidOperation`` exception. The driver cannot
178+
determine these values if the server does not acknowledge the write
179+
operation.
180+
181+
If the query filter does not match any documents, the driver doesn't delete any
182+
documents and ``deletedCount`` is ``0``.
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+
- `deleteOne() <{+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)