Skip to content

Commit 515eb6c

Browse files
rustagirrustagir
authored
DOCSP-24549: delete fundamentals (#23)
* DOCSP-24549-delete-fundamentals-pg * first pass fixes and index creation * additions to parameters and code changes * small fixes * more small fixes * page rearrangement * discussion changes * add headers * header fix * rephrasing * header fix * PR comments 1 * link fix
1 parent 098048b commit 515eb6c

File tree

6 files changed

+316
-0
lines changed

6 files changed

+316
-0
lines changed

‎source/fundamentals.txt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
============
2+
Fundamentals
3+
============
4+
5+
.. default-domain:: mongodb
6+
7+
.. toctree::
8+
:titlesonly:
9+
:maxdepth: 1
10+
11+
/fundamentals/crud

‎source/fundamentals/crud.txt

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.. _csharp-crud:
2+
3+
===============
4+
CRUD Operations
5+
===============
6+
7+
.. default-domain:: mongodb
8+
9+
.. toctree::
10+
:caption: CRUD Operations
11+
12+
/fundamentals/crud/write-operations

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. _csharp-crud-write-operations:
2+
3+
================
4+
Write Operations
5+
================
6+
7+
.. default-domain:: mongodb
8+
9+
- :ref:`csharp-delete-guide`
10+
11+
.. toctree::
12+
:caption: Write Operations
13+
14+
/fundamentals/crud/write-operations/delete

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

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
.. _csharp-delete-guide:
2+
3+
================
4+
Delete Documents
5+
================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
Overview
16+
--------
17+
18+
In this guide, you can learn how to remove documents from your MongoDB
19+
collections using delete operations.
20+
21+
Sample Data
22+
~~~~~~~~~~~
23+
24+
The example in this guide use the ``restaurants`` collection
25+
from the ``sample_restaurants`` database. The documents in this
26+
collection are modeled by the following ``Restaurant`` class:
27+
28+
.. literalinclude:: /includes/fundamentals/code-examples/crud/delete.cs
29+
:language: csharp
30+
:dedent:
31+
:start-after: start-model
32+
:end-before: end-model
33+
34+
This collection is from the :atlas:`sample datasets </sample-data>` provided
35+
by Atlas. See the :ref:`<csharp-quickstart>` to learn how to create a free MongoDB cluster
36+
and load this sample data.
37+
38+
Delete Operations
39+
-----------------
40+
41+
Use delete operations to remove documents that match a **query filter**.
42+
The query filter determines which records are selected for deletion
43+
based on the criteria in :manual:`the query filter
44+
document</core/document/#query-filter-documents>`. You can perform
45+
delete operations in MongoDB with the following methods:
46+
47+
- ``DeleteOne()``, which deletes *the first document* that matches the query filter
48+
- ``DeleteMany()``, which deletes *all documents* that match the query filter
49+
50+
Delete One Document
51+
~~~~~~~~~~~~~~~~~~~
52+
53+
The following code shows how to use the asynchronous
54+
``DeleteOneAsync()`` method or the synchronous ``DeleteOne()`` method to
55+
delete one document.
56+
57+
.. tabs::
58+
59+
.. tab:: Asynchronous
60+
:tabid: delete-one-async
61+
62+
.. code-block:: csharp
63+
:copyable: true
64+
65+
var result = await _restaurantsCollection.DeleteOneAsync(filter);
66+
67+
.. tab:: Synchronous
68+
:tabid: delete-one-sync
69+
70+
.. code-block:: csharp
71+
:copyable: true
72+
73+
var result = _restaurantsCollection.DeleteOne(filter);
74+
75+
Delete Multiple Documents
76+
~~~~~~~~~~~~~~~~~~~~~~~~~
77+
78+
The following code shows how to use the asynchronous
79+
``DeleteManyAsync()`` method or the synchronous ``DeleteMany()`` method to
80+
delete all matched documents.
81+
82+
.. tabs::
83+
84+
.. tab:: Asynchronous
85+
:tabid: delete-many-async
86+
87+
.. code-block:: csharp
88+
:copyable: true
89+
90+
var result = await _restaurantsCollection.DeleteManyAsync(filter);
91+
92+
.. tab:: Synchronous
93+
:tabid: delete-many-sync
94+
95+
.. code-block:: csharp
96+
:copyable: true
97+
98+
var result = _restaurantsCollection.DeleteMany(filter);
99+
100+
.. tip::
101+
102+
Find runnable examples using these methods under :ref:`additional
103+
information <additional-info>`.
104+
105+
Parameters
106+
~~~~~~~~~~
107+
108+
The ``DeleteOne()`` and ``DeleteMany()`` methods require you to pass a
109+
query filter specifying which documents to match. More information
110+
on how to construct a query filter is available in :manual:`the Query Documents
111+
tutorial</tutorial/query-documents/>`.
112+
113+
Both methods optionally take a ``DeleteOptions`` type as an additional parameter,
114+
which represents options you can use to configure the delete operation.
115+
If you don't specify any ``DeleteOptions`` properties, the driver does
116+
not customize the delete operation.
117+
118+
The ``DeleteOptions`` type allows you to configure options with the
119+
following properties:
120+
121+
.. list-table::
122+
:widths: 30 70
123+
:header-rows: 1
124+
125+
* - Property
126+
- Description
127+
128+
* - ``Collation``
129+
- | Gets or sets the type of language collation to use when sorting
130+
results. See :manual:`the delete
131+
statements</reference/command/delete/#std-label-deletes-array-collation>`
132+
for more information.
133+
134+
* - ``Comment``
135+
- | Gets or sets the comment for the operation. See :manual:`the delete command
136+
fields</reference/command/delete/#command-fields>`
137+
for more information.
138+
139+
* - ``Hint``
140+
- | Gets or sets the index to use to scan for documents. See :manual:`the delete
141+
statements</reference/command/delete/#std-label-deletes-array-hint>`
142+
for more information.
143+
144+
* - ``Let``
145+
- | Gets or sets the let document. See :manual:`the delete command
146+
fields</reference/command/delete/#command-fields>`
147+
for more information.
148+
149+
Example
150+
~~~~~~~
151+
152+
The following code uses the ``DeleteMany()`` method to search on the
153+
"borough_1" index and delete all documents where the ``address.street``
154+
field value includes the phrase "Pearl Street":
155+
156+
.. io-code-block::
157+
:copyable: true
158+
159+
.. input::
160+
:language: csharp
161+
162+
var filter = Builders<Restaurant>.Filter
163+
.Regex("address.street", "Pearl Street");
164+
165+
DeleteOptions opts = new DeleteOptions { Hint = "borough_1" };
166+
167+
WriteLine("Deleting documents...");
168+
var result = _restaurantsCollection.DeleteMany(filter, opts);
169+
170+
WriteLine($"Deleted documents: {result.DeletedCount}");
171+
WriteLine($"Result acknowledged? {result.IsAcknowledged}");
172+
173+
.. output::
174+
:language: none
175+
:visible: false
176+
177+
Deleting documents...
178+
Deleted documents: 26
179+
Result acknowledged? True
180+
181+
.. tip::
182+
183+
If the preceding example used the ``DeleteOne()`` method instead of
184+
``DeleteMany()``, the driver would delete the first of the 26
185+
matched documents.
186+
187+
Return Value
188+
~~~~~~~~~~~~
189+
190+
The ``DeleteOne()`` and ``DeleteMany()`` methods return a
191+
``DeleteResult`` type. This type contains the ``DeletedCount`` property,
192+
which indicates the number of documents deleted, and the
193+
``IsAcknowledged`` property, which indicates if the result is
194+
acknowledged. If the query filter does not match any documents, no documents
195+
are deleted and ``DeletedCount`` is 0.
196+
197+
.. _additional-info:
198+
199+
Additional Information
200+
----------------------
201+
202+
For runnable examples of the delete operations, see the following usage
203+
examples:
204+
205+
- :ref:`csharp-delete-one`
206+
- :ref:`csharp-delete-many`
207+
208+
.. To learn more about performing the operations mentioned, see the
209+
.. following guides:
210+
211+
.. TODO create specify a query
212+
.. - :ref:`csharp-query-document`
213+
214+
API Documentation
215+
~~~~~~~~~~~~~~~~~
216+
217+
To learn more about any of the methods or types discussed in this
218+
guide, see the following API Documentation:
219+
220+
- `DeleteOne() <{+api-root+}/Overload_MongoDB_Driver_IMongoCollectionExtensions_DeleteOne.htm>`__
221+
- `DeleteOneAsync() <{+api-root+}/Overload_MongoDB_Driver_IMongoCollectionExtensions_DeleteOneAsync.htm>`__
222+
- `DeleteMany() <{+api-root+}/Overload_MongoDB_Driver_IMongoCollectionExtensions_DeleteMany.htm>`__
223+
- `DeleteManyAsync() <{+api-root+}/Overload_MongoDB_Driver_IMongoCollectionExtensions_DeleteManyAsync.htm>`__
224+
- `DeleteOptions <{+api-root+}/T_MongoDB_Driver_DeleteOptions.htm>`__
225+
- `DeleteResult <{+api-root+}/Properties_T_MongoDB_Driver_DeleteResult.htm>`__

‎source/includes/fundamentals/code-examples/crud/delete.cs

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
using MongoDB.Bson.Serialization.Conventions;
2+
using MongoDB.Driver;
3+
using static System.Console;
4+
5+
namespace TestRun.Fundamentals;
6+
7+
public class Delete
8+
{
9+
private static IMongoCollection<Restaurant> _restaurantsCollection;
10+
private static string _mongoConnectionString = "<Your MongoDB URI>";
11+
12+
public static void Main(string[] args)
13+
{
14+
Setup();
15+
16+
var filter = Builders<Restaurant>.Filter
17+
.Regex("address.street", "Pearl Street");
18+
19+
DeleteOptions opts = new DeleteOptions { Hint = "borough_1" };
20+
21+
WriteLine("Deleting documents...");
22+
var result = _restaurantsCollection.DeleteMany(filter, opts);
23+
24+
WriteLine($"Deleted documents: {result.DeletedCount}");
25+
WriteLine($"Result acknowledged? {result.IsAcknowledged}");
26+
}
27+
private static void Setup()
28+
{
29+
// This allows automapping of the camelCase database fields to our models.
30+
var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() };
31+
ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true);
32+
33+
// Establish the connection to MongoDB and get the restaurants database
34+
var mongoClient = new MongoClient(_mongoConnectionString);
35+
var restaurantsDatabase = mongoClient.GetDatabase("sample_restaurants");
36+
_restaurantsCollection = restaurantsDatabase.GetCollection<Restaurant>("restaurants");
37+
}
38+
}
39+
40+
// start-model
41+
public class Restaurant
42+
{
43+
public ObjectId Id { get; set; }
44+
public string Name { get; set; }
45+
46+
[BsonElement("restaurant_id")]
47+
public string RestaurantId { get; set; }
48+
public string Cuisine { get; set; }
49+
public object Address { get; set; }
50+
public string Borough { get; set; }
51+
public List<object> Grades { get; set; }
52+
}
53+
// end-model

‎source/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ MongoDB C# Driver
88

99
/quick-start
1010
/usage-examples
11+
/fundamentals
1112
/compatibility
1213
/faq
1314
/issues-and-help

0 commit comments

Comments
 (0)