Skip to content

Commit a32f4c0

Browse files
rustagirrustagir
authored
DOCSP-39542: delete crud fundamentals (#19)
1 parent 3a999fa commit a32f4c0

File tree

3 files changed

+204
-2
lines changed

3 files changed

+204
-2
lines changed

‎source/fundamentals/crud/write-operations.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,15 @@ Write Operations
99

1010
/fundamentals/crud/write-operations/insert
1111
/fundamentals/crud/write-operations/change
12+
/fundamentals/crud/write-operations/delete
1213

1314
..
14-
/fundamentals/crud/write-operations/delete
1515
/fundamentals/crud/write-operations/arrays
1616
/fundamentals/crud/write-operations/upsert
1717

1818
- :ref:`rust-insert-guide`
1919
- :ref:`rust-change-guide`
20+
- :ref:`rust-delete-guide`
2021

21-
.. - :ref:`rust-delete-guide`
2222
.. - :ref:`rust-arrays-guide`
2323
.. - :ref:`rust-upsert-guide`

‎source/fundamentals/crud/write-operations/delete.txt

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
.. _rust-delete-guide:
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+
Overview
14+
--------
15+
16+
In this guide, you can learn how to remove documents from your MongoDB
17+
collections using **delete operations**.
18+
19+
.. _rust-delete-sample-data:
20+
21+
Sample Data for Examples
22+
------------------------
23+
24+
.. TODO decide on structs for crud
25+
26+
The example in this guide uses the following sample documents. Each
27+
document represents an item in a store's inventory and contains
28+
information about its categorization and unit price:
29+
30+
.. code-block:: json
31+
:copyable: false
32+
33+
{ "item": "trowel", "category": "garden", "unit_price": 9.89 },
34+
{ "item": "placemat", "category": "kitchen", "unit_price": 3.19 },
35+
{ "item": "watering can", "category": "garden", "unit_price": 11.99 }
36+
37+
Delete Operations
38+
-----------------
39+
40+
The {+driver-short+} provides the ``delete_one()`` and ``delete_many()``
41+
methods to perform delete operations.
42+
43+
Parameters
44+
~~~~~~~~~~
45+
46+
The ``delete_one()`` and ``delete_many()`` methods take a query filter
47+
as a parameter. A query filter consists of the fields and values that
48+
form criteria for documents to match.
49+
50+
You can also optionally pass a ``DeleteOptions`` type as a parameter to
51+
either method. You can specify settings in a ``DeleteOptions`` instance
52+
to configure the delete operation. To use default values for each
53+
setting, specify the value ``None`` as the options parameter.
54+
55+
The following table describes settings that you can specify in a
56+
``DeleteOptions`` instance:
57+
58+
.. list-table::
59+
:header-rows: 1
60+
:class: compatibility-large
61+
62+
* - Option
63+
- Description
64+
65+
* - ``collation``
66+
- | The collation to use when sorting results.
67+
| Type: ``Collation``
68+
| Default: ``nil``
69+
70+
* - ``write_concern``
71+
- | The write concern for the operation. To learn more about write
72+
concerns, see :manual:`Write Concern
73+
</reference/write-concern/>` in the Server manual.
74+
| Type: ``WriteConcern``
75+
76+
* - ``hint``
77+
- | The index to use for the operation. To learn more about
78+
indexes, see :manual:`Indexes </indexes/>` in the Server
79+
manual. This option is available only when connecting to
80+
{+server+} versions 4.4 and later.
81+
| Type: ``Hint``
82+
| Default: ``nil``
83+
84+
* - ``let_vars``
85+
- | A map of parameters and values. These parameters can be accessed
86+
as variables in aggregation expressions. This option is available
87+
only when connecting to {+server+} versions 5.0 and later.
88+
| Type: ``Document``
89+
90+
* - ``comment``
91+
- | An arbitrary ``Bson`` value tied to the operation to trace
92+
it through the database profiler, ``currentOp``, and
93+
logs. This option is available only when connecting to
94+
{+server+} versions 4.4 and later.
95+
| Type: ``Bson``
96+
97+
.. TODO add links to guides for relevant options
98+
99+
The following code shows how to construct an ``DeleteOptions``
100+
instance and pass it to the ``delete_one()`` method:
101+
102+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/delete.rs
103+
:start-after: begin-options
104+
:end-before: end-options
105+
:language: rust
106+
:copyable:
107+
:dedent:
108+
109+
Return Value
110+
~~~~~~~~~~~~
111+
112+
The ``delete_one()`` and ``delete_many()`` methods return a
113+
``DeleteResult`` type. This type contains the ``deleted_count`` property,
114+
which describes the number of documents deleted. If no documents match
115+
the query filter you specified, the delete operation does
116+
not remove any documents, and the value of ``deleted_count`` is ``0``.
117+
118+
delete_many() Example
119+
~~~~~~~~~~~~~~~~~~~~~
120+
121+
This example shows how to call the ``delete_many()`` method with the
122+
following parameters:
123+
124+
- A query filter that matches documents where the value of ``category``
125+
is ``"garden"``
126+
- A ``DeleteOptions`` instance that uses the ``_id_`` index as the hint
127+
for the delete operation
128+
129+
.. io-code-block::
130+
131+
.. input:: /includes/fundamentals/code-snippets/crud/delete.rs
132+
:start-after: begin-delete
133+
:end-before: end-delete
134+
:language: rust
135+
:dedent:
136+
137+
.. output::
138+
:language: console
139+
:visible: false
140+
141+
Deleted documents: 2
142+
143+
.. note::
144+
145+
If the preceding example used the ``delete_one()`` method instead of
146+
``delete_many()`` for the delete operation, the driver would delete
147+
the first of the two documents that matched the query filter.
148+
149+
Additional Information
150+
----------------------
151+
152+
.. TODO For runnable examples of the delete operations, see the following usage
153+
.. examples:
154+
155+
.. - :ref:`rust-delete-one`
156+
.. - :ref:`rust-delete-many`
157+
158+
.. TODO To learn more about performing the operations mentioned, see the
159+
.. following guides:
160+
161+
.. - :ref:`rust-query-guide`
162+
.. - :ref:`rust-indexes`.
163+
.. - :ref:`rust-collations`.
164+
165+
API Documentation
166+
~~~~~~~~~~~~~~~~~
167+
168+
To learn more about any of the methods or types discussed in this
169+
guide, see the following API Documentation:
170+
171+
- `delete_one() <{+api+}/struct.Collection.html#method.delete_one>`__
172+
- `delete_many() <{+api+}/struct.Collection.html#method.delete_many>`__
173+
- `DeleteOptions <{+api+}/options/struct.DeleteOptions.html>`__
174+
- `Hint <{+api+}/options/enum.Hint.html>`__
175+
- `DeleteResult <{+api+}/results/struct.DeleteResult.html>`__

‎source/includes/fundamentals/code-snippets/crud/delete.rs

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
use bson::{ Document, bson };
2+
use mongodb::{ bson::doc, options::{ DeleteOptions, Hint }, Client, Collection };
3+
use std::{ env };
4+
5+
#[tokio::main]
6+
async fn main() -> mongodb::error::Result<()> {
7+
let uri = "<connection string>";
8+
let client = Client::with_uri_str(uri).await?;
9+
10+
let my_coll: Collection<Document> = client.database("db").collection("inventory");
11+
12+
// begin-delete
13+
let filter = doc! { "category": "garden" };
14+
let hint = Hint::Name("_id_".to_string());
15+
let opts: DeleteOptions = DeleteOptions::builder().hint(hint).build();
16+
17+
let res = my_coll.delete_many(filter, opts).await?;
18+
println!("Deleted documents: {}", res.deleted_count);
19+
// end-delete
20+
21+
// begin-options
22+
let opts: DeleteOptions = DeleteOptions::builder().comment(bson!("hello!")).build();
23+
let _res = my_coll.delete_one(filter, opts).await?;
24+
// end-options
25+
26+
Ok(())
27+
}

0 commit comments

Comments
 (0)