Skip to content

BulkWrite

class BulkWrite<Document : Any> : Command, AbstractBsonNode, CompoundNode<AvailableInBulkWrite<Document>>

Performing multiple write operations in a single request.

Example

users.bulkWrite {
    updateOne({ User::name eq "foo" }) {
        User::age set 18
    }

    upsertOne({ User::name eq "bob" }) {
        User::age setOnInsert 18
        User::age inc 1
    }
}

Filtered writes

If we have multiple writes that share a similar filter, we can extract it to be common between them.

users.bulkWrite {
    updateOne({ User::name eq "foo" }) {
        User::age set 18
    }

    filtered({ User::isAlive eq true }) {
        updateMany({ User::name eq "bar" }) {
            User::age inc 2
        }

        updateOne({ User::name eq "baz" }) {
            User::age inc 1
        }
    }
}

To learn more, see filtered.

External resources

See also

Constructors

BulkWrite

constructor(context: BsonContext, globalFilter: FilterQuery<Document>.() -> Unit)

Properties

context

@LowLevelApi



open val context: BsonContext

The context used to generate this expression.

operations

options

Functions

accept

@LowLevelApi



@DangerousMongoApi



open override fun accept(node: AvailableInBulkWrite<Document>)

Adds a new Node into the current node.

This method is generally considered unsafe, as it allows inserting any kind of node into the current node. Since this library is about representing database requests, this method allows inserting any kind of operation, without necessarily checking any security or coherence invariants.

Users should only interact with this method when they add a new type of node that doesn't exist in the library. For example, when adding an operator that is missing from the library. In these cases, we highly recommend users to contact the maintainers of KtMongo to ensure the created operator respects all invariants. If possible, upstreaming the operator would be of benefit to all users, and guarantees future bug fixes.

In all other cases, it is expected that implementations of this interface provide methods for each added functionality that are responsible for checking invariants and are safe to call.

For a more detailed explanation of the contract of this method, see Node.

acceptAll

@LowLevelApi



@DangerousMongoApi



fun <N : Node> CompoundNode<N>.acceptAll(nodes: Iterable<N>)

Adds any number of nodes into this one.

filtered

fun filtered(filter: FilterQuery<Document>.() -> Unit, operations: BulkWrite<Document>.() -> Unit)

Declares a filter that is shared between all children operations.

Example

Sometimes, we have multiple operations in a single bulk write that share the same filter. This method allows to declare it a single time.

users.bulkWrite {
    filtered({ User::isAlive eq true }) {
        updateOne { /* … */}
        updateOne { /* … */}
    }
}

freeze

@LowLevelApi



open override fun freeze()

Makes this node immutable.

insertMany

fun insertMany(documents: Iterable<Document>, options: InsertOneOptions<Document>.() -> Unit = {})

Inserts multiple documents in a single operation.

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

collection.bulkWrite {
    insertMany(listOf(User(name = "Bob", age = 18), User(name = "Alice", age = 17)))
}
External resources

See also

fun insertMany(vararg documents: Document, options: InsertOneOptions<Document>.() -> Unit = {})

Inserts multiple documents in a single operation.

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

collection.bulkWrite {
    insertMany(User(name = "Bob", age = 18), User(name = "Alice", age = 17))
}
External resources

See also

insertOne

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

Inserts a document.

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

collection.bulkWrite {
    insertOne(User(name = "Bob", age = 18))
}
External resources

See also

replaceOne

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.

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

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

See also

repsertOne

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.

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

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

If a document exists that has the name of "Patrick", it is replaced by the new document. If none exist, the document is inserted.

External resources

See also

simplify

@LowLevelApi



open fun simplify(): AbstractBsonNode?

Returns a simplified (but equivalent) expression to the current expression.

toBson

@LowLevelApi



open fun toBson(): Bson

Writes the result of simplifying to a new BSON document.

toString

fun toString(simplified: Boolean): String

JSON representation of this expression.

override fun toString(): String

JSON representation of this expression.

updateMany

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

Updates all documents that match filter according to update.

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

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

See also

updateOne

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

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.bulkWrite {
    updateOne(
        filter = { User::name eq "Patrick" },
        update = {
            User::age set 15
        }
    )
}
External resources

See also

upsertOne

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

Updates a single document that matches filter according to update.

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

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

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

collection.bulkWrite {
    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 exist, a document with name "Patrick" and age 15 is created.

External resources

See also

writeTo

@LowLevelApi



override fun writeTo(writer: BsonFieldWriter)

Writes the result of simplifying this expression into writer.