Skip to content

Commit 07a2f57

Browse files
norareidynorareidy
committed
DOCSP-51323: Databases & collections
1 parent 6dc5793 commit 07a2f57

File tree

2 files changed

+230
-1
lines changed

2 files changed

+230
-1
lines changed

‎source/databases-collections.txt

Lines changed: 179 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,182 @@ Databases and Collections
88
:local:
99
:backlinks: none
1010
:depth: 2
11-
:class: singlecol
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: table, row, organize, storage, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use MongoDB databases and
24+
collections with the {+driver-short+}.
25+
26+
MongoDB organizes data into a hierarchy of the following levels:
27+
28+
- **Databases**: Top-level data structures in a MongoDB deployment that store collections.
29+
- **Collections**: Groups of MongoDB documents. They are analogous to tables in relational databases.
30+
- **Documents**: Units that store literal data such as string, numbers, dates, and other embedded documents.
31+
For more information about document field types and structure, see the
32+
:manual:`Documents </core/document/>` guide in the {+mdb-server+} manual.
33+
34+
Access a Database
35+
-----------------
36+
37+
To access a database, pass the database name to the ``getDatabase()``
38+
method.
39+
40+
The following example accesses a database named ``test_database``:
41+
42+
.. literalinclude:: /includes/databases-collections.kt
43+
:language: kotlin
44+
:dedent:
45+
:start-after: start-access-database
46+
:end-before: end-access-database
47+
48+
.. _kotlin-sync-db-coll-access-collection:
49+
50+
Access a Collection
51+
-------------------
52+
53+
To access a collection, pass the database name to the ``getCollection()``
54+
method.
55+
56+
The following example accesses a collection named ``test_collection``:
57+
58+
.. literalinclude:: /includes/databases-collections.kt
59+
:language: kotlin
60+
:dedent:
61+
:start-after: start-access-collection
62+
:end-before: end-access-collection
63+
64+
.. tip::
65+
66+
If the provided collection name does not already exist in the database,
67+
MongoDB implicitly creates the collection when you first insert data
68+
into it.
69+
70+
.. _kotlin-sync-db-coll-create-collection:
71+
72+
Create a Collection
73+
-------------------
74+
75+
To explicitly create a collection in a MongoDB database, pass a collection
76+
name to the ``createCollection()`` method.
77+
78+
The following example creates a collection named ``example_collection``:
79+
80+
.. literalinclude:: /includes/databases-collections.kt
81+
:language: kotlin
82+
:dedent:
83+
:start-after: start-create-collection
84+
:end-before: end-create-collection
85+
86+
You can specify collection options, such as maximum size and document
87+
validation rules, by setting them in a ``CreateCollectionOptions`` instance.
88+
Then, pass the ``CreateCollectionOptions`` to the ``createCollection()`` method.
89+
For a full list of optional parameters, see the `CreateCollectionOptions <{+core-api+}/client/model/CreateCollectionOptions.html>`__
90+
API documentation.
91+
92+
Get a List of Collections
93+
-------------------------
94+
95+
You can query for a list of collections in a database by calling the
96+
``listCollections()`` method. The method returns a cursor containing all
97+
collections in the database and their associated metadata.
98+
99+
The following example calls the ``listCollections()`` method and iterates over
100+
the returned iterator to print the collections from the :ref:`kotlin-sync-db-coll-access-collection`
101+
and :ref:`kotlin-sync-db-coll-create-collection` examples:
102+
103+
.. io-code-block::
104+
:copyable: true
105+
106+
.. input:: /includes/databases-collections.kt
107+
:language: kotlin
108+
:start-after: start-find-collections
109+
:end-before: end-find-collections
110+
:dedent:
111+
112+
.. output::
113+
114+
{
115+
"name": "october2024",
116+
"type": "timeseries",
117+
"options": {
118+
"timeseries": {
119+
"timeField": "temperature",
120+
"granularity": "seconds",
121+
"bucketMaxSpanSeconds": 3600
122+
}
123+
},
124+
"info": {
125+
"readOnly": false
126+
}
127+
}
128+
...
129+
130+
Delete a Collection
131+
-------------------
132+
133+
To delete a collection from the database, call the ``drop()`` method
134+
on your collection.
135+
136+
The following example deletes the ``test_collection`` collection:
137+
138+
.. literalinclude:: /includes/databases-collections.kt
139+
:language: kotlin
140+
:dedent:
141+
:start-after: start-drop-collection
142+
:end-before: end-drop-collection
143+
144+
.. warning:: Dropping a Collection Deletes All Data in the Collection
145+
146+
Dropping a collection from your database permanently deletes all
147+
documents and all indexes within that collection.
148+
149+
Drop a collection only if you no longer need the data in it.
150+
151+
.. _kotlin-sync-config-read-write:
152+
153+
Configure Read and Write Operations
154+
-----------------------------------
155+
156+
You can control how read and write operations run on replica sets
157+
by specifying a read preference, read concern, or write concern.
158+
159+
By default, databases inherit read and write settings from the ``MongoClient``
160+
instance. Collections inherit these settings from the ``MongoClient`` or
161+
``MongoDatabase`` instance on which the ``getCollection()`` method is called.
162+
You can change these settings by calling the following methods:
163+
164+
- `MongoDatabase.withReadConcern() <{+driver-api+}/-mongo-database/with-read-concern.html>`__
165+
166+
- `MongoDatabase.withReadPreference() <{+driver-api+}/-mongo-database/with-read-preference.html>`__
167+
168+
- `MongoDatabase.withWriteConcern() <{+driver-api+}/-mongo-database/with-write-concern.html>`__
169+
170+
- `MongoCollection.withReadConcern() <{+driver-api+}/-mongo-collection/with-read-concern.html>`__
171+
172+
- `MongoCollection.withReadPreference() <{+driver-api+}/-mongo-collection/with-read-preference.html>`__
173+
174+
- `MongoCollection.withWriteConcern() <{+driver-api+}/-mongo-collection/with-write-concern.html>`__
175+
176+
To learn more about setting a read preference, read concern, and write concern,
177+
see the :ref:`kotlin-sync-configure` guide.
178+
179+
API Documentation
180+
-----------------
181+
182+
To learn more about any of the methods or types discussed in this
183+
guide, see the following API documentation:
184+
185+
- `getDatabase() <{+driver-api+}/-mongo-cluster/get-database.html>`__
186+
- `getCollection() <{+driver-api+}/-mongo-database/get-collection.html>`__
187+
- `createCollection() <{+driver-api+}/-mongo-database/create-collection.html>`__
188+
- `listCollections() <{+driver-api+}/-mongo-database/list-collection.html>`__
189+
- `drop() <{+driver-api+}/-mongo-collection/drop.html>`__

‎source/includes/databases-collections.kt

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
import com.mongodb.ConnectionString
2+
import com.mongodb.MongoClientSettings
3+
import com.mongodb.ReadConcern
4+
import com.mongodb.ReadPreference
5+
import com.mongodb.WriteConcern
6+
import com.mongodb.client.MongoClient
7+
import com.mongodb.client.MongoClients
8+
import com.mongodb.client.MongoCollection
9+
import com.mongodb.client.MongoDatabase
10+
import org.bson.Document
11+
12+
fun main() {
13+
val uri = "<connection string URI>"
14+
15+
val settings = MongoClientSettings.builder()
16+
.applyConnectionString(ConnectionString(uri))
17+
.retryWrites(true)
18+
.build()
19+
20+
val mongoClient = MongoClient.create(settings)
21+
val database = mongoClient.getDatabase("sample_restaurants")
22+
val collection = database.getCollection<Restaurant>("restaurants")
23+
24+
// Accesses the "test_database" database
25+
// start-access-database
26+
val db: MongoDatabase = client.getDatabase("test_database")
27+
// end-access-database
28+
29+
// Accesses the "test_collection" collection
30+
// start-access-collection
31+
val collection: MongoCollection<Document> = client.getDatabase("test_database").getCollection("test_collection")
32+
// end-access-collection
33+
34+
// Explicitly creates the "example_collection" collection
35+
// start-create-collection
36+
client.getDatabase("test_database").createCollection("example_collection")
37+
// end-create-collection
38+
39+
// Lists the collections in the "test_database" database
40+
// start-find-collections
41+
for (collectionInfo in client.getDatabase("test_database").listCollections()) {
42+
println(collectionInfo.toJson())
43+
}
44+
// end-find-collections
45+
46+
47+
// Deletes the "test_collection" collection
48+
// start-drop-collection
49+
client.getDatabase("test_database").getCollection("test_collection").drop()
50+
// end-drop-collection
51+
}

0 commit comments

Comments
 (0)