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, 
    documentType: KType, 
    globalFilter: FilterQuery<Document>.() -> Unit
)

Properties

context

The context used to generate this expression.

documentType

operations

options

Functions

accept

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

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 expression 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

  • updateOne: Update an existing document.

  • repsertOne: Replace a document, or insert it if it doesn't exist.

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

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

toBson

Writes the result of simplifying to a new BsonDocument.

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

  • insertOne: Always create a new document.

  • updateOne: Do nothing if no matching documents are found.

writeTo

@LowLevelApi
override fun writeTo(writer: BsonFieldWriter)

Writes the result of simplifying this expression into writer.