MongoDB request DSL • opensavvy.ktmongo.dsl.query • FilterQuery

FilterQuery¶

interface FilterQuery<T> : CompoundBsonNode, FieldDsl

DSL for MongoDB operators that are used as predicates in conditions.

Example¶

This expression type is available in multiple operators, most commonly find:

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

collection.find {
    User::age gte 18
}

Beware of arrays!¶

MongoDB operators do not discriminate between scalars and arrays. When an array is encountered, all operators attempt to match on the array itself. If the match fails, the operators attempt to match array elements.

It is not possible to mimic this behavior in KtMongo while still keeping type-safety, so operators may behave strangely when arrays are encountered.

Note that if the collection corresponds to the declared Kotlin type, these situations can never happen, as the Kotlin type system doesn't allow them to.

When developers attempt to perform an operator on the entire array, they should use operators as normal:

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

collection.find {
    User::favoriteNumbers eq listOf(1, 2)
}

Developers should use the request above when they want to match a document similar to:

{
    favoriteNumbers: [1, 2]
}

The following document will NOT match:

{
    favoriteNumbers: [3]
}

However, due to MongoDB's behavior when encountering arrays, it should be noted that the following document WILL match:

{
    favoriteNumbers: [
        [3],
        [1, 2],
        [7, 2]
    ]
}

To execute an operator on one of the elements of an array, see anyValue.

Operators¶

Comparison query:

Logical query:

Element query:

Array query:

Bitwise query:

Text query:

$regex

If you can't find an operator you're searching for, visit the tracking issue.

Properties¶

`any`¶

open val <V> KProperty1<T, Collection<V>>.any: Field<T, V>

Specify operators on array elements.

open val <V> Field<T, Collection<V>>.any: Field<T, V>

Specify operators on array elements.

`context`¶

abstract val context:

The context used to generate this expression.

`field`¶

open val <Root, Type> KProperty1<Root, Type>.field: Field<Root, Type>

Converts a Kotlin property into a Field.

Functions¶

`accept`¶

abstract override fun accept(node: BsonNode)

Adds a new node as a child of this one.

`acceptAll`¶

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

Adds any number of nodes into this one.

`and`¶

abstract fun and(block: FilterQuery<T>.() -> Unit)

Performs a logical AND operation on one or more expressions, and selects the documents that satisfy all the expressions.

`any`¶

open fun <V> KProperty1<T, Collection<V>>.any(block: FilterQuery<V>.() -> Unit)

Specify multiple operators on fields of a single array element.

abstract fun <V> Field<T, Collection<V>>.any(block: FilterQuery<V>.() -> Unit)

Specify multiple operators on fields of a single array element.

`anyValue`¶

open fun <V> KProperty1<T, Collection<V>>.anyValue(block: FilterQueryPredicate<V>.() -> Unit)

Specify multiple operators on a single array element.

abstract fun <V> Field<T, Collection<V>>.anyValue(block: FilterQueryPredicate<V>.() -> Unit)

Specify multiple operators on a single array element.

`bitsAllClear`¶

open infix fun KProperty1<T, *>.bitsAllClear(mask: )

Matches documents where all bit positions present in mask are clear (i.e., 0) in the current field.

open infix fun KProperty1<T, *>.bitsAllClear(mask: ByteArray)

Matches documents where all bit positions present in mask are clear (i.e., 0) in the current field.

open infix fun Field<T, *>.bitsAllClear(mask: )

Matches documents where all bit positions present in mask are clear (i.e., 0) in the current field.

open infix fun Field<T, *>.bitsAllClear(mask: ByteArray)

Matches documents where all bit positions present in mask are clear (i.e., 0) in the current field.

`bitsAllSet`¶

open infix fun KProperty1<T, *>.bitsAllSet(mask: )

Matches documents where all bit positions present in mask are set (i.e., 1) in the current field.

open infix fun KProperty1<T, *>.bitsAllSet(mask: ByteArray)

Matches documents where all bit positions present in mask are set (i.e., 1) in the current field.

open infix fun Field<T, *>.bitsAllSet(mask: )

Matches documents where all bit positions present in mask are set (i.e., 1) in the current field.

open infix fun Field<T, *>.bitsAllSet(mask: ByteArray)

Matches documents where all bit positions present in mask are set (i.e., 1) in the current field.

`bitsAnyClear`¶

open infix fun KProperty1<T, *>.bitsAnyClear(mask: )

Matches documents where any bit position present in mask is clear (i.e., 0) in the current field.

open infix fun KProperty1<T, *>.bitsAnyClear(mask: ByteArray)

Matches documents where any bit position present in mask is clear (i.e., 0) in the current field.

open infix fun Field<T, *>.bitsAnyClear(mask: )

Matches documents where any bit position present in mask is clear (i.e., 0) in the current field.

open infix fun Field<T, *>.bitsAnyClear(mask: ByteArray)

Matches documents where any bit position present in mask is clear (i.e., 0) in the current field.

`bitsAnySet`¶

open infix fun KProperty1<T, *>.bitsAnySet(mask: )

Matches documents where any bit position present in mask is set (i.e., 1) in the current field.

open infix fun KProperty1<T, *>.bitsAnySet(mask: ByteArray)

Matches documents where any bit position present in mask is set (i.e., 1) in the current field.

open infix fun Field<T, *>.bitsAnySet(mask: )

Matches documents where any bit position present in mask is set (i.e., 1) in the current field.

open infix fun Field<T, *>.bitsAnySet(mask: ByteArray)

Matches documents where any bit position present in mask is set (i.e., 1) in the current field.

`containsAll`¶

open infix fun <V> KProperty1<T, Collection<V>>.containsAll(values: Collection<V>)

Selects documents where the value of a field is an array that contains all the specified values.

abstract infix fun <V> Field<T, Collection<V>>.containsAll(values: Collection<V>)

Selects documents where the value of a field is an array that contains all the specified values.

`div`¶

open operator fun <Root, Parent, Child> KProperty1<Root, Parent>.div(child: KProperty1<Parent & Any, Child>): Field<Root, Child>

Refers to child as a nested field of the current field.

open operator fun <V, V2> KProperty1<T, Collection<V>>.div(other: KProperty1<V, V2>): Field<T, V2>

Combines Kotlin properties into a path usable to point to any item in an array.

open operator fun <V, V2> KProperty1<T, Collection<V>>.div(other: Field<V, V2>): Field<T, V2>

Combines Kotlin properties into a path usable to point to any item in an array.

open operator fun <V, V2> Field<T, Collection<V>>.div(other: KProperty1<V, V2>): Field<T, V2>

Combines Kotlin properties into a path usable to point to any item in an array.

open operator fun <V, V2> Field<T, Collection<V>>.div(other: Field<V, V2>): Field<T, V2>

Combines Kotlin properties into a path usable to point to any item in an array.

`doesNotExist`¶

open fun KProperty1<T, *>.doesNotExist()

Matches documents that do not contain the specified field. Documents where the field if null are not matched.

open fun Field<T, *>.doesNotExist()

Matches documents that do not contain the specified field. Documents where the field if null are not matched.

`eq`¶

open infix fun <V> KProperty1<T, V>.eq(value: V)

Matches documents where the value of a field equals the value.

open infix fun <V> Field<T, V>.eq(value: V)

Matches documents where the value of a field equals the value.

`eqNotNull`¶

open infix fun <V> KProperty1<T, V>.eqNotNull(value: V?)

Matches documents where the value of a field equals value.

open infix fun <V> Field<T, V>.eqNotNull(value: V?)

Matches documents where the value of a field equals value.

`exists`¶

open fun KProperty1<T, *>.exists()

Matches documents that contain the specified field, including values where the field value is null.

open fun Field<T, *>.exists()

Matches documents that contain the specified field, including values where the field value is null.

`expr`¶

abstract fun expr(block: AggregationOperators.() -> Value<T & Any, Boolean>)

Enables the usage of aggregation values within a regular query.

`freeze`¶

abstract override fun freeze()

Makes this expression immutable.

`get`¶

open operator fun <Root, Type> KProperty1<Root, Collection<Type>>.get(index: Int): Field<Root, Type>

Refers to a specific item in an array, by its index.

open operator fun <Root, Type> KProperty1<Root, Map<String, Type>>.get(index: String): Field<Root, Type>

Refers to a specific item in a map, by its name.

`gt`¶

open infix fun <V> KProperty1<T, V>.gt(value: V)

Selects documents for which this field has a value strictly greater than value.

open infix fun <V> Field<T, V>.gt(value: V)

Selects documents for which this field has a value strictly greater than value.

`gte`¶

open infix fun <V> KProperty1<T, V>.gte(value: V)

Selects documents for which this field has a value greater or equal to value.

open infix fun <V> Field<T, V>.gte(value: V)

Selects documents for which this field has a value greater or equal to value.

`gteNotNull`¶

open infix fun <V> KProperty1<T, V>.gteNotNull(value: V?)

Selects documents for which this field has a value greater or equal to value.

open infix fun <V> Field<T, V>.gteNotNull(value: V?)

Selects documents for which this field has a value greater or equal to value.

`gtNotNull`¶

open infix fun <V> KProperty1<T, V>.gtNotNull(value: V?)

Selects documents for which this field has a value strictly greater than value.

open infix fun <V> Field<T, V>.gtNotNull(value: V?)

Selects documents for which this field has a value strictly greater than value.

`hasType`¶

open infix fun KProperty1<T, *>.hasType(type: )

Selects documents where the value of the field is an instance of the specified BSON type.

open infix fun Field<T, *>.hasType(type: )

Selects documents where the value of the field is an instance of the specified BSON type.

`invoke`¶

open operator fun <V> KProperty1<T, V>.invoke(block: FilterQueryPredicate<V>.() -> Unit)

Targets a single field to execute a targeted predicate.

abstract operator fun <V> Field<T, V>.invoke(block: FilterQueryPredicate<V>.() -> Unit)

Targets a single field to execute a targeted predicate.

`isEmpty`¶

open fun KProperty1<T, Collection<*>>.isEmpty()

Matches documents in which an array is empty or absent.

open fun Field<T, Collection<*>>.isEmpty()

Matches documents in which an array is empty or absent.