Skip to content

Commit 5b5ca74

Browse files
rustagirrustagir
authored
DOCSP-27283: db coll page (#204)
* DOCSP-27283: db coll page * JS PR fixes 1
1 parent 0175d7a commit 5b5ca74

File tree

2 files changed

+333
-0
lines changed

2 files changed

+333
-0
lines changed

‎source/fundamentals.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ Fundamentals
1212
:maxdepth: 1
1313

1414
/fundamentals/connection
15+
/fundamentals/database-collection
1516
/fundamentals/crud
1617
/fundamentals/builders
1718
/fundamentals/atlas-search
@@ -29,6 +30,7 @@ Fundamentals
2930
/fundamentals/encrypt-fields
3031

3132
- :ref:`Connecting to MongoDB <csharp-connection>`
33+
- :ref:`csharp-db-coll`
3234
- :ref:`csharp-crud`
3335
- :ref:`csharp-builders`
3436
- :ref:`csharp-atlas-search`

‎source/fundamentals/database-collection.txt

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
.. _csharp-db-coll:
2+
3+
=========================
4+
Databases and Collections
5+
=========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: access data, delete data, organize connections
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to access
24+
and manage MongoDB databases and collections.
25+
26+
MongoDB organizes data in a hierarchical structure. A MongoDB
27+
deployment contains one or more **databases**, and each database
28+
contains one or more **collections**. In each collection, MongoDB stores
29+
data as **documents** that contain field-and-value pairs.
30+
31+
To learn more about the document data format,
32+
see :manual:`Documents </core/document/>` in the Server manual.
33+
34+
Access a Database
35+
-----------------
36+
37+
You can access a database by retrieving an `IMongoDatabase
38+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.html>`__
39+
instance from your ``IMongoClient`` instance. You can use
40+
the returned ``IMongoDatabase`` instance to perform database-level operations and access
41+
collections that the database contains.
42+
43+
To create an ``IMongoDatabase``, call the `GetDatabase()
44+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoClient.GetDatabase.html>`__
45+
method on an `IMongoClient
46+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoClient.html>`__
47+
instance, passing the database name as a
48+
parameter. You can also pass an optional `MongoDatabaseSettings
49+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoDatabaseSettings.html>`__
50+
as a parameter to customize how you access a database.
51+
52+
If you pass the name of a nonexistent database to the ``GetDatabase()``
53+
method, the driver still returns an
54+
``IMongoDatabase`` instance. When you insert any data into a collection in this
55+
database, the server creates the database and collection at that time.
56+
57+
The following example creates a client, then uses the ``GetDatabase()``
58+
method to access a database called ``test_db``:
59+
60+
.. code-block:: csharp
61+
:emphasize-lines: 2
62+
63+
var client = new MongoClient("<connection string>");
64+
var myDB = mongoClient.GetDatabase("test_db");
65+
66+
List Databases
67+
--------------
68+
69+
To see a list of your deployment's databases, call the
70+
asynchronous `ListDatabaseNamesAsync()
71+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoClient.ListDatabaseNamesAsync.html>`__
72+
method or synchronous `ListDatabaseNames()
73+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoClient.ListDatabaseNames.html>`__ method on
74+
your ``IMongoClient`` instance.
75+
76+
To see detailed information about each database, call the
77+
asynchronous `ListDatabasesAsync()
78+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoClient.ListDatabasesAsync.html>`__
79+
method or synchronous `ListDatabases()
80+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoClient.ListDatabases.html>`__ method on
81+
your ``IMongoClient`` instance. These methods return fields describing
82+
the databases in the cluster, such as their sizes and whether they contain data.
83+
84+
The following code shows how to use the asynchronous
85+
``ListDatabaseNamesAsync()`` method or the synchronous ``ListDatabaseNames()`` method to
86+
list the names of the databases in a cluster:
87+
88+
.. tabs::
89+
90+
.. tab:: Asynchronous
91+
:tabid: list-db-async
92+
93+
.. code-block:: csharp
94+
:copyable: true
95+
96+
await mongoClient.ListDatabaseNamesAsync();
97+
98+
.. tab:: Synchronous
99+
:tabid: list-db-sync
100+
101+
.. code-block:: csharp
102+
:copyable: true
103+
104+
mongoClient.ListDatabaseNames();
105+
106+
Drop a Database
107+
---------------
108+
109+
Dropping a database permanently deletes all the data in that database's
110+
collections. To drop a database, call the
111+
asynchronous `DropDatabaseAsync()
112+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoClient.DropDatabaseAsync.html>`__
113+
method or synchronous `DropDatabase()
114+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoClient.DropDatabase.html>`__
115+
method on your ``IMongoClient`` instance, passing the database name as
116+
the parameter.
117+
118+
The following code shows how to use the asynchronous
119+
``DropDatabaseAsync()`` method or the synchronous ``DropDatabase()`` method to
120+
drop a database called ``test_db``:
121+
122+
.. tabs::
123+
124+
.. tab:: Asynchronous
125+
:tabid: drop-db-async
126+
127+
.. code-block:: csharp
128+
:copyable: true
129+
130+
await mongoClient.DropDatabaseAsync("test_db");
131+
132+
.. tab:: Synchronous
133+
:tabid: drop-db-sync
134+
135+
.. code-block:: csharp
136+
:copyable: true
137+
138+
mongoClient.DropDatabase("test_db");
139+
140+
.. warning:: Dropping a Database Deletes Data
141+
142+
Dropping a database permanently deletes all
143+
documents in the database's collections and all indexes on those collections.
144+
After you drop a database, you cannot access or restore any of its data.
145+
146+
Access a Collection
147+
-------------------
148+
149+
You can access a collection by retrieving an `IMongoCollection
150+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.html>`__
151+
instance from your database. You can use an ``IMongoCollection``
152+
instance to perform data operations,
153+
create aggregations, and manage indexes. To retrieve an
154+
``IMongoCollection``, call the `GetCollection()
155+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.GetCollection.html>`__
156+
method on an ``IMongoDatabase`` instance. You can also pass an optional `MongoCollectionSettings
157+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.MongoCollectionSettings.html>`__
158+
as a parameter to customize how you access a collection.
159+
160+
If you pass the name of a nonexistent collection to this method, the
161+
driver still returns an ``IMongoCollection`` instance. When you insert
162+
any data into this collection, the server creates it. To learn how to
163+
explicitly create a collection, see the :ref:`Create a Collection
164+
<csharp-create-collection>` section of this guide.
165+
166+
This example uses the ``GetCollection()`` method to
167+
access a collection called ``coll_xyz`` from a database referenced by
168+
the ``myDB`` variable:
169+
170+
.. code-block:: csharp
171+
172+
var myColl = myDB.GetCollection<BsonDocument>("coll_xyz");
173+
174+
.. _csharp-coll-parameterization:
175+
176+
Collection Parameterization
177+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
178+
179+
You must parameterize your ``IMongoCollection`` instance by specifying what
180+
data type you want to serialize the collection's
181+
data into. When you call a method on a ``IMongoCollection`` instance that is
182+
parameterized with a specific type, the method accepts or returns
183+
instances of this type.
184+
185+
The following example shows how to parameterize a
186+
collection with the ``BsonDocument`` type:
187+
188+
.. code-block:: csharp
189+
190+
var collection = database.GetCollection<BsonDocument>("coll_xyz", settings);
191+
192+
.. tip::
193+
194+
We recommend that you parameterize your ``IMongoCollection`` instance with a
195+
custom type that models your data instead of the ``BsonDocument`` type.
196+
You can avoid repetitive serialization and validation by defining a
197+
type that models your specific data.
198+
199+
To learn more about serialization in the {+driver-short+}, see the
200+
guide on :ref:`csharp-serialization`.
201+
202+
.. _csharp-create-collection:
203+
204+
Create a Collection
205+
-------------------
206+
207+
You can explicitly create a collection by calling the
208+
asynchronous `CreateCollectionAsync()
209+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.CreateCollectionAsync.html>`__
210+
method or synchronous `CreateCollection()
211+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.CreateCollection.html>`__
212+
method on your ``IMongoDatabase`` instance.
213+
214+
This method takes the collection name and an
215+
optional `CreateCollectionOptions
216+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.CreateCollectionOptions.html>`__ type as
217+
parameters. You can then access the created collection to perform data
218+
operations, create aggregations, and manage indexes.
219+
220+
The following code shows how to use the asynchronous
221+
``CreateCollectionAsync()`` method or the synchronous
222+
``CreateCollection()`` method to create a collection called
223+
``coll_abc`` within a database referenced by the ``myDB`` variable:
224+
225+
.. tabs::
226+
227+
.. tab:: Asynchronous
228+
:tabid: create-coll-async
229+
230+
.. code-block:: csharp
231+
:copyable: true
232+
233+
await myDB.CreateCollectionAsync("coll_abc");
234+
235+
.. tab:: Synchronous
236+
:tabid: create-coll-sync
237+
238+
.. code-block:: csharp
239+
:copyable: true
240+
241+
myDB.CreateCollection("coll_abc");
242+
243+
List Collections
244+
----------------
245+
246+
To see a list of collections in a database, call the
247+
asynchronous `ListCollectionNamesAsync()
248+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.ListCollectionNamesAsync.html>`__
249+
method or synchronous `ListCollectionNames()
250+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.ListCollectionNames.html>`__ method on
251+
your ``IMongoDatabase`` instance.
252+
253+
To see detailed information about each database, call the
254+
asynchronous `ListCollectionsAsync()
255+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.ListCollectionsAsync.html>`__
256+
method or synchronous `ListCollections()
257+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.ListCollections.html>`__ method on
258+
your ``IMongoDatabase`` instance. These methods return fields describing
259+
the collections in the database, such as their types and settings.
260+
261+
The following code shows how to use the asynchronous
262+
``ListCollectionNamesAsync()`` method or the synchronous ``ListCollectionNames()`` method to
263+
list the names of the collections in a database:
264+
265+
.. tabs::
266+
267+
.. tab:: Asynchronous
268+
:tabid: list-coll-async
269+
270+
.. code-block:: csharp
271+
:copyable: true
272+
273+
await myDB.ListCollectionNamesAsync();
274+
275+
.. tab:: Synchronous
276+
:tabid: list-coll-sync
277+
278+
.. code-block:: csharp
279+
:copyable: true
280+
281+
myDB.ListCollectionNames();
282+
283+
.. _csharp-drop-collection:
284+
285+
Drop a Collection
286+
-----------------
287+
288+
Dropping a collection permanently deletes all the data in that
289+
collection. To drop a collection, call the asynchronous `DropCollectionAsync()
290+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.DropCollectionAsync.html>`__ method or the
291+
synchronous `DropCollection()
292+
<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.DropCollection.html>`__
293+
method on your ``IMongoCollection`` instance.
294+
295+
The following code shows how to use the asynchronous
296+
``DropCollectionAsync()`` method or the synchronous ``DropCollection()`` method to
297+
drop a database called ``coll_abc``:
298+
299+
.. tabs::
300+
301+
.. tab:: Asynchronous
302+
:tabid: drop-coll-async
303+
304+
.. code-block:: csharp
305+
:copyable: true
306+
307+
await myDB.DropCollectionAsync("coll_abc");
308+
309+
.. tab:: Synchronous
310+
:tabid: drop-coll-sync
311+
312+
.. code-block:: csharp
313+
:copyable: true
314+
315+
myDB.DropCollection("coll_abc");
316+
317+
.. warning:: Dropping a Collection Deletes Data
318+
319+
Dropping a collection from your database permanently deletes all
320+
documents within that collection and all indexes on that collection.
321+
After you drop a collection, you cannot access or restore any of its data.
322+
323+
Additional Information
324+
----------------------
325+
326+
For more information about the concepts in this guide, see the following documentation:
327+
328+
- :ref:`Insert Documents <csharp-insert-guide>` guide
329+
- :manual:`Databases and Collections </core/databases-and-collections/>`
330+
in the Server manual
331+
- :manual:`Documents </core/document/>` in the Server manual

0 commit comments

Comments
 (0)