Option

interface Option : BsonNode

Additional parameters that are passed to MongoDB operations.

Options are usually configured with the options = {} optional parameter in a command. For example, if we want to know how many notifications a user has but can only display "99" because of UI size constraints, we can use the following command:

notifications.count(
    options = {
        limit(99)
    }
) {
    Notification::ownedBy eq currentUser
}

By default, if the same option is specified multiple times, only the very last one applies:

notifications.count(
    options = {
        limit(99)
        limit(10)
    }
)

will only count at most 10 elements. To customize this behavior, see merge.

Accessing the current value of an option

See Options.allOptions and option.

Implementing this interface

Implementations of this interface must be careful to respect the contract of BsonNode, in particular about the toString representation.

Option implementations must be immutable. If the user wants to change an option, they can specify it a second time (which will override the previous one).

Inheritors

• AbstractOption

Properties

context

@LowLevelApi
abstract val context: BsonContext

The context used to generate this expression.

name

abstract val name: String

The name of this option, as it appears in the BSON representation.

Options always have the form:

find(
    { },
    { },
    {
        "limit": 10,
        "sort": { }
    },
)

In this example, the LimitOption has the name "limit" and the SortOption has the name "sort".

Implementation notes

This value should be immutable.

Functions

freeze

@LowLevelApi
abstract override fun freeze()

Makes this node immutable.

merge

@LowLevelApi
open fun merge(other: Option): Option

Merges this option with another of the same type.

This method is not meant to be called by end-users. It allows option implementations to customize the behavior when the same option is specified multiple times. This method is called automatically by the KtMongo library.

The caller is responsible for only calling this method with a parameter of the same concrete type as the current instance.

This method returns a new option, which combines the values of both options. The two options passed as parameters must not be modified. This method may return one of the two options passed as parameters.

This method must be called in the same order as the options are defined. For example, if a is defined before b, then a.merge(b) is valid, but b.merge(a) is not.

By default, this method returns the last declared option (other).

This method is called by the option holder's BsonNode.simplify method.

read

abstract fun read(): BsonValue

Reads the value of this option.

Performance

This method requires writing this option into a temporary BSON value.

Typically, most option implementations provide specific inexpensive accessors for their different components (e.g. LimitOption.limit).

simplify

@LowLevelApi
abstract fun simplify(): BsonNode?

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

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.