Databases and Collections

Overview

In this guide, you can learn how to use MongoDB databases and collections with the MongoDB Kotlin driver.

MongoDB organizes data into a hierarchy of the following levels:

1. Databases: Databases are the top level of data organization in a MongoDB instance.

2. Collections: Databases are organized into collections which contain documents.

3. Documents: Documents contain literal data such as strings, numbers, and dates, as well as other embedded documents. For more information on document field types and structure, see the Server documentation on documents.

With the MongoDB Kotlin driver, you can model data by using Kotlin data classes or by using the Document class to store and retrieve data from MongoDB.

To learn more about using data classes, see the guide on the Data Class Data Format. To learn more about using the Document class, see the guide on the Document Data Format.

Access a Database

Use the getDatabase() method of a MongoClient instance to access a MongoDatabase in a MongoDB instance.

The following example accesses a database named testDatabase:

val database = client.getDatabase("testDatabase")

Access a Collection

Use the getCollection() method of a MongoDatabase instance to access a MongoCollection in a database of your connected MongoDB instance.

The following example accesses a collection named testCollection from a MongoDatabase that contains documents of type ExampleDataClass:

data class ExampleDataClass(
    @BsonId val id: ObjectId = ObjectId(),
    val exampleProperty: String,
)

val collection = database.getCollection<ExampleDataClass>("testCollection")

data class Fruit(
    @BsonId val id: Int,
    val name: String,
    val qty: Int,
    val seasons: List<String>
)

val collection =
    database.getCollection<Fruit>("fruits")
// Define a data class for returned documents
data class NewFruit(
    @BsonId val id: Int,
    val name: String,
    val quantity: Int,
    val seasons: List<String>
)
val filter = Filters.eq(Fruit::name.name, "strawberry")
val update = Updates.combine(
    Updates.rename(Fruit::qty.name, "quantity"),
    Updates.push(Fruit::seasons.name, "fall"),
)
val options = FindOneAndUpdateOptions()
    .returnDocument(ReturnDocument.AFTER)
// Specify the class for returned documents as the type parameter in withDocumentClass()
val result = collection
    .withDocumentClass<NewFruit>()
    .findOneAndUpdate(filter, update, options)
println(result)

NewFruit(id=1, name=strawberry, quantity=205, seasons=[summer, fall])

Create a Collection

Use the createCollection() method of a MongoDatabase instance to create a collection in a database of your connected MongoDB instance.

The following example creates a collection called exampleCollection:

database.createCollection("exampleCollection")

You can specify collection options like maximum size and document validation rules using the CreateCollectionOptions class. The createCollection() method accepts an instance of CreateCollectionOptions as an optional second parameter.

val collOptions: ValidationOptions = ValidationOptions().validator(
    Filters.or(
        Filters.exists("title"),
        Filters.exists("name")
    )
)
database.createCollection(
    "movies",
    CreateCollectionOptions().validationOptions(collOptions)
)

Get a List of Collections

You can query for a list of collections in a database using the MongoDatabase.listCollectionNames() method:

val collectionList = database.listCollectionNames().toList()
println(collectionList)

[movies, exampleCollection]

Drop a Collection

You can remove a collection from the database using the MongoCollection.drop() method:

val collection =
    database.getCollection<ExampleDataClass>("movies")
collection.drop()

Specify Read Preferences, Read Concerns, and Write Concerns

Read preferences, read concerns, and write concerns control how the driver routes read operations and waits for acknowledgment for read and write operations when connected to a MongoDB replica set. Read preferences and read concerns apply to all read operations; write concerns apply to all write operations.

MongoDatabase instances inherit their write concern, read concern, and write preference settings from the MongoClient used to create them. MongoCollection instances inherit their write concern, read concern, and write preference settings from the MongoDatabase used to create them. However, you can use the following methods to obtain an instance of a MongoDatabase or MongoCollection with a read preference, read concern, or write concern that differs from the setting they would normally inherit:

• MongoDatabase.withReadConcern()

• MongoDatabase.withReadPreference()

• MongoDatabase.withWriteConcern()

• MongoCollection.withReadConcern()

• MongoCollection.withReadPreference()

• MongoCollection.withWriteConcern()

For more information on these topics, see the following pages in the Server manual:

• Read Preference

• Read Concern

• Write Concern