PushBuilder

interface PushBuilder<V> : BsonNode

DSL builder for advanced $push operations.

See push.

Properties

context

@LowLevelApi
abstract val context: BsonContext

The context used to generate this expression.

Functions

each

open fun each(vararg values: V)

Specifies the values to push to the array.

If this function is called multiple times, they are combined (keeping the calling order).

Example

class User(
    val name: String,
    val tokens: List<String>,
)

collection.updateOne(
    filter = {
        User::name eq "Bob"
    },
    update = {
        User::tokens push {
            each("123", "456")
        }
    }
)

You can also call push multiple times:

collection.updateOne(
    filter = {
        User::name eq "Bob"
    },
    update = {
        User::tokens push "123"
        User::tokens push "456"
    }
)

External resources

• Official documentation

abstract fun each(values: Iterable<V>)

Specifies the values to push to the array.

If this function is called multiple times, they are combined (keeping the calling order).

Example

class User(
    val name: String,
    val tokens: List<String>,
)

collection.updateOne(
    filter = {
        User::name eq "Bob"
    },
    update = {
        User::tokens push {
            each(listOf("123", "456"))
        }
    }
)

You can also call push multiple times:

collection.updateOne(
    filter = {
        User::name eq "Bob"
    },
    update = {
        User::tokens push "123"
        User::tokens push "456"
    }
)

External resources

• Official documentation

freeze

@LowLevelApi
abstract override fun freeze()

Makes this expression immutable.

position

abstract fun position(index: Int)

Specifies the location in the array at which the $push operator inserts elements.

Without the $position modifier, the $push operator inserts elements to the end of the array.

A non-negative number corresponds to the position in the array, starting from the beginning of the array. If the value is greater or equal to the length of the array, the $position modifier has no effect and $push adds elements to the end of the array.

A negative number corresponds to the position in the array, counting from (but not including) the last element of the array. For example, -1 indicates the position just before the last element in the array. If you specify multiple elements in the $each array, the last added element is in the specified position from the end. If the absolute value is greater than or equal to the length of the array, the $push adds elements to the beginning of the array.

Said otherwise:

• To insert elements at the end of the array, do not specify position at all.

• To insert elements at the start of the array, specify position(0).

• To insert elements just after the first value, specify position(1).

• To insert elements just before the last value, specify position(-1).

If this function is called multiple times, only the last value has an effect.

If this function is called without an each operator, this function does nothing.

Example

class User(
    val name: String,
    val scores: List<Int>,
)

collection.updateOne(
    filter = {
        User::name eq "Bob"
    },
    update = {
        User::scores push {
            each(50, 60, 70)
            position(0)  // Insert at the beginning
        }
    }
)

External resources

• Official documentation

simplify

@LowLevelApi
abstract fun simplify(): BsonNode?

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

slice

abstract fun slice(count: Int)

Limits the number of array elements after the push operation.

If count is positive, after adding the elements to the array, only the first count elements are kept, and all additional elements are discarded.

If count is negative, after adding the elements to the array, only the last count elements are kept, and prior elements are discarded.

If this operator is specified without an each operator, the size of the array is truncated but no elements are added.

If this function is called multiple times, only the latest value has an effect.

Example

class User(
    val name: String,
    val tokens: List<String>,
)

collection.updateOne(
    filter = {
        User::name eq "Bob"
    },
    update = {
        User::tokens push {
            each("123", "456")
            slice(3)  // Keep only the first 3 elements
        }
    }
)

External resources

• Official documentation

sort

abstract fun sort(block: UpdateQuery.PushSortDsl<V & Any>.() -> Unit)

Orders the elements of an array during a $push operation.

If this function is called multiple times, only the last value has an effect.

If this function is called without an each operator, the existing data is sorted but no elements are added.

Example

class Quiz(
    val id: Int,
    val score: Int,
)

class User(
    val name: String,
    val quizzes: List<Quiz>,
)

collection.updateOne(
    filter = {
        User::name eq "Bob"
    },
    update = {
        User::quizzes push {
            each(Quiz(3, 8), Quiz(4, 7), Quiz(5, 6))
            sort {
                ascending(Quiz::score)
            }
        }
    }
)

To sort based on the natural order of the array elements themselves:

class User(
    val name: String,
    val scores: List<Int>,
)

collection.updateOne(
    filter = {
        User::name eq "Bob"
    },
    update = {
        User::scores push {
            each(12, 34)
            sort { ascending() }
        }
    }
)

External resources

• Official documentation

toBson

@LowLevelApi
open fun toBson(): BsonDocument

Writes the result of simplifying to a new BsonDocument.

toString

abstract override fun toString(): String

JSON representation of this expression.

writeTo

@LowLevelApi
abstract override fun writeTo(writer: BsonFieldWriter)

Writes the result of simplifying this expression into writer.