JvmMongoCollection¶

class JvmMongoCollection<Document : Any> : MongoCollection<Document>

Implementation of MongoCollection based on MongoDB's MongoCollection.

To access the inner iterable, see asKotlinClient.

To convert an existing MongoDB iterable into an instance of this class, see asKtMongo.

Properties¶

context¶

@LowLevelApi
open override val context: JvmBsonContext

Functions¶

aggregate¶

open override fun aggregate(): MongoAggregationPipeline<Document>

Start an aggregation pipeline.

Example

class User(
    val name: String,
    val age: Int,
)

users.aggregate()
    .match { User::age gt 18 }
    .toList()

External resources

Official documentation

asKotlinClient¶

@LowLevelApi
fun asKotlinClient(): MongoCollection<Document>

bulkWrite¶

open suspend override fun bulkWrite(
    options: BulkWriteOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    operations: BulkWrite<Document>.() -> Unit
)

Performs multiple update operations in a single request.

Example

class User(
    val name: String,
    val age: Int,
)

collection.bulkWrite {
    upsertOne(
        filter = {
            User::name eq "Patrick"
        },
        update = {
            User::age set 15
        }
    )

    updateMany {
        User::age inc 1
    }
}

To see which operations are available and their respective syntax, see BulkWrite.

Using filtered writes

We can group operations by the filter they apply on:

collection.bulkWrite {
    filtered(filter = { User::isAlive eq true }) {
        updateOne(…)
        updateOne(…)
        updateMany(…)
    }

    updateOne(…)
}

To learn more, see filtered.

Using filtered collections

If we want all operations to use the same filter, we can declare it before calling the operation:

collection.filter {
    User::isAlive eq true
}.bulkWrite {
    updateOne(…)
    updateOne(…)
    updateMany(…)
}

External resources

Official documentation

count¶

open suspend override fun count(): Long

Counts how many documents exist in the collection.

External resources

Official documentation

See also

countEstimated: Faster alternative when the result doesn't need to be exact.

open suspend override fun count(options: CountOptions<Document>.() -> Unit = {}, predicate: FilterQuery<Document>.() -> Unit): Long

Counts how many documents match predicate in the collection.

Example

class User(
    val name: String,
    val age: Int,
)

collection.count {
    User::name eq "foo"
    User::age eq 10
}

External resources

Official documentation

countEstimated¶

open suspend override fun countEstimated(): Long

Counts all documents in the collection.

This function reads collection metadata instead of actually counting through all documents. This makes it much more performant (almost no CPU nor RAM usage), but the count may be slightly out of date.

In particular, it may become inaccurate when:

there are orphaned documents in a shared cluster,
an unclean shutdown happened.

Views do not possess the required metadata. When this function is called on a view (either a MongoDB view or a filter logical view), a regular count is executed instead.

External resources

Official documentation

See also

count: Perform the count for real.

deleteMany¶

open suspend override fun deleteMany(options: DeleteManyOptions<Document>.() -> Unit = {}, filter: FilterQuery<Document>.() -> Unit)

Deletes all documents that match filter.

Example

class User(
    val name: String,
    val age: Int
)

collection.deleteMany {
    User::age lt 18
}

External resources

Official documentation

deleteOne¶

open suspend override fun deleteOne(options: DeleteOneOptions<Document>.() -> Unit = {}, filter: FilterQuery<Document>.() -> Unit)

Deletes the first document found that matches filter.

Example

class User(
    val name: String,
    val age: Int
)

collection.deleteOne {
    User::name eq "Bob"
}

External resources

Official documentation

drop¶

open suspend override fun drop(options: DropOptions<Document>.() -> Unit = {})

Removes an entire collection from the database.

Example

collection.drop()

Using with filtered collections

When using opensavvy.ktmongo.sync.MongoCollection.filter, all elements matching the filter are removed. Other documents are not impacted, and the collection is not deleted.

External resources

Official documentation

`exists`¶

open suspend fun exists(options: CountOptions<Document>.() -> Unit = {}, predicate: FilterQuery<Document>.() -> Unit): Boolean

Tests if there exists a document that matches predicate in the collection.

filter¶

fun <Document : Any> MongoCollection<Document>.filter(filter: FilterQuery<Document>.() -> Unit): MongoCollection<Document>

Returns a filtered collection that only contains the elements that match filter.

This function creates a logical view of the collection: by itself, this function does nothing, and MongoDB is never aware of the existence of this logical view. However, operations invoked on the returned collection will only affect elements from the original that match the filter.

Unlike actual MongoDB views, which are read-only, collections returned by this function can also be used for write operations.

Example

A typical usage of this function is to reuse filters for multiple operations. For example, if you have a concept of logical deletion, this function can be used to hide deleted values.

class Order(
    val id: String,
    val date: Instant,
    val deleted: Boolean,
)

val allOrders = database.getCollection<Order>("orders").asKtMongo()
val activeOrders = allOrders.filter { Order::deleted ne true }

allOrders.find()    // Returns all orders, deleted or not
activeOrders.find() // Only returns orders that are not logically deleted

find¶

open override fun find(): JvmMongoIterable<Document>

Finds all documents in this collection.

External resources

Official documentation

open override fun find(options: FindOptions<Document>.() -> Unit = {}, filter: FilterQuery<Document>.() -> Unit): JvmMongoIterable<Document>

Finds all documents in this collection that satisfy filter.

If multiple predicates are specified, an and operator is implied.

Example

class User(
    val name: String,
    val age: Int,
)

collection.find {
    User::name eq "foo"
    User::age eq 10
}

External resources

Official documentation

See also

findOne: When only one result is expected.

`findOne`¶

open suspend fun findOne(options: FindOptions<Document>.() -> Unit = {}, filter: FilterQuery<Document>.() -> Unit): Document?

Finds a document in this collection that satisfies filter.

findOneAndUpdate¶

open suspend override fun findOneAndUpdate(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpdateQuery<Document>.() -> Unit
): Document?

Updates one element that matches filter according to update and returns it, atomically.

Example

class User(
    val name: String,
    val age: Int,
)

collection.findOneAndUpdate(
    filter = {
        User::name eq "Patrick"
    },
    update = {
        User::age set 15
    },
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.findOneAndUpdate {
    User::age set 15
}

To learn more, see filter.

External resources

Official documentation

Parameters

filter: Optional filter to select which document is updated. If no filter is specified, the first document found is updated.

See also

updateMany: Update more than one document.
updateOne: Do not return the value.

insertMany¶

open suspend override fun insertMany(documents: Iterable<Document>, options: InsertManyOptions<Document>.() -> Unit = {})

Inserts multiple documents in a single operation.

Example

class User(
    val name: String,
    val age: Int,
)

collection.insertMany(users)

Note that insertOne ignores filtered collection. That is, insertOne on a filtered collection behaves exactly the same as the same insertOne on the underlying real collection.

External resources

Official documentation

See also

insertOne: Insert a single document.

insertOne¶

open suspend override fun insertOne(document: Document, options: InsertOneOptions<Document>.() -> Unit = {})

Inserts a document.

Example

class User(
    val name: String,
    val age: Int,
)

collection.insertOne(User(name = "Bob", age = 18))

Note that insertOne ignores filtered collection. That is, insertOne on a filtered collection behaves exactly the same as the same insertOne on the underlying real collection.

External resources

Official documentation

See also

insertMany: Insert multiple documents.

newId¶

open override fun newId(): ObjectId

replaceOne¶

open suspend override fun replaceOne(
    options: ReplaceOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    document: Document
)

Replaces a document that matches filter by document.

If multiple documents match filter, only the first one found is updated.

Data races

This operator is often used by first reading a document, processing it, and replacing it. This can be dangerous in distributed systems because another replica of the server could have updated the document between the read and the write.

If this is a concern, it is recommended to use updateOne with explicit operators on the data that has changed, allowing to do the modification in a single operation. Doing the update that way, MongoDB is responsible for ensuring the read and the write are atomic.

Example

class User(
    val name: String,
    val age: Int,
)

collection.replaceOne(
    filter = {
        User::name eq "Patrick"
    },
    document = User("Bob", 15)
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.replaceOne(User("Patrick", 15))

To learn more, see filter.

External resources

Official documentation

Parameters

filter: Optional filter to select which document is updated. If no filter is specified, the first document found is updated.

See also

updateOne: Updates an existing document.
updateMany: Update more than one document.
repsertOne: Replaces a document, or inserts it if it doesn't exist.
findOneAndUpdate: Also returns the result of the update.

repsertOne¶

open suspend override fun repsertOne(
    options: ReplaceOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    document: Document
)

Replaces a document that matches filter by document.

If multiple documents match filter, only the first one found is updated.

If no documents match filter, document is inserted.

Data races

This operator is often used by first reading a document, processing it, and replacing it. This can be dangerous in distributed systems because another replica of the server could have updated the document between the read and the write.

If this is a concern, it is recommended to use updateOne with explicit operators on the data that has changed, allowing to do the modification in a single operation. Doing the update that way, MongoDB is responsible for ensuring the read and the write are atomic.

Example

class User(
    val name: String,
    val age: Int,
)

collection.repsertOne(
    filter = {
        User::name eq "Patrick"
    },
    document = User("Bob", 15)
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.repsertOne(User("Patrick", 15))

To learn more, see filter.

External resources

Official documentation

Parameters

filter: Optional filter to select which document is updated. If no filter is specified, the first document found is updated.

See also

updateOne: Updates an existing document.
replaceOne: Replaces an existing document.
findOneAndUpdate: Also returns the result of the update.

toString¶

open override fun toString(): String

updateMany¶

open suspend override fun updateMany(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpdateQuery<Document>.() -> Unit
): UpdateOperations.UpdateResult

Updates all documents that match filter according to update.

Example

class User(
    val name: String,
    val age: Int,
)

collection.updateMany(
    filter = {
        User::name eq "Patrick"
    },
    update = {
        User::age set 15
    },
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.updateMany {
    User::age set 15
}

To learn more, see filter.

External resources

Official documentation

Parameters

filter: Optional filter to select which documents are updated. If no filter is specified, all documents are updated.

See also

updateOne

updateManyWithPipeline¶

open suspend override fun updateManyWithPipeline(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpdateWithPipelineQuery<Document>.() -> Unit
): UpdateOperations.UpdateResult

Updates all documents that match filter according to the update pipeline.

Example

class User(
    val name: String,
    val age: Int,
)

collection.updateManyWithPipeline(
    filter = {
        User::name eq "Patrick"
    }
) {
    set {
        User::age set 15
    }
}

External resources

Official documentation

Parameters

filter: Optional filter to select which documents are updated. If no filter is specified, all documents are updated.

See also

updateOneWithPipeline: Update a single document.

updateOne¶

open suspend override fun updateOne(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpdateQuery<Document>.() -> Unit
): UpdateOperations.UpdateResult

Updates a single document that matches filter according to update.

If multiple documents match filter, only the first one found is updated.

Example

class User(
    val name: String,
    val age: Int,
)

collection.updateOne(
    filter = {
        User::name eq "Patrick"
    },
    update = {
        User::age set 15
    },
)

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.updateOne {
    User::age set 15
}

To learn more, see filter.

External resources

Official documentation

Parameters

filter: Optional filter to select which document is updated. If no filter is specified, the first document found is updated.

See also

updateMany: Update more than one document.
findOneAndUpdate: Also returns the result of the update.

updateOneWithPipeline¶

open suspend override fun updateOneWithPipeline(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpdateWithPipelineQuery<Document>.() -> Unit
): UpdateOperations.UpdateResult

Updates a single document that matches filter according to the update pipeline.

If multiple documents match filter, only the first one found is updated.

Example

class User(
    val name: String,
    val age: Int,
)

collection.updateOneWithPipeline(
    filter = {
        User::name eq "Patrick"
    }
) {
    set {
        User::age set 15
    }
}

External resources

Official documentation

Parameters

filter: Optional filter to select which document is updated. If no filter is specified, the first document found is updated.

See also

updateManyWithPipeline: Update multiple documents.
upsertOneWithPipeline: Update a document, creating it if it doesn't exist.

upsertOne¶

open suspend override fun upsertOne(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpsertQuery<Document>.() -> Unit
): UpdateOperations.UpsertResult

Updates a single document that matches filter according to update.

If multiple documents match filter, only the first one is updated.

If no documents match filter, a new one is created.

Example

class User(
    val name: String,
    val age: Int,
)

collection.upsertOne(
    filter = {
        User::name eq "Patrick"
    },
    update = {
        User::age set 15
    },
)

If a document exists that has the name of "Patrick", its age is set to 15. If none exists, a document with name "Patrick" and age 15 is created.

Using filtered collections

The following code is equivalent:

collection.filter {
    User::name eq "Patrick"
}.upsertOne {
    User::age set 15
}

To learn more, see filter.

External resources

See also

updateOne

upsertOneWithPipeline¶

open suspend override fun upsertOneWithPipeline(
    options: UpdateOptions<Document>.() -> Unit = {}, 
    filter: FilterQuery<Document>.() -> Unit = {}, 
    update: UpdateWithPipelineQuery<Document>.() -> Unit
): UpdateOperations.UpsertResult

Updates a single document that matches filter according to the update pipeline.

If multiple documents match filter, only the first one is updated.

If no documents match filter, a new one is created.

Example

class User(
    val name: String,
    val age: Int,
)

collection.upsertOneWithPipeline(
    filter = {
         User::name eq "Patrick"
    }
) {
    set {
        User::age set 15
    }
}

External resources

Official documentation

See also

updateOneWithPipeline: Do nothing if the document doesn't already exist.

JvmMongoCollection¶

Properties¶

context¶

Functions¶

aggregate¶

asKotlinClient¶

bulkWrite¶

count¶

countEstimated¶

deleteMany¶

deleteOne¶

drop¶

exists¶

filter¶

find¶

findOne¶

findOneAndUpdate¶

insertMany¶

insertOne¶

newId¶

replaceOne¶

repsertOne¶

toString¶

updateMany¶

updateManyWithPipeline¶

updateOne¶

updateOneWithPipeline¶

upsertOne¶

upsertOneWithPipeline¶

`exists`¶

`findOne`¶