FilterQueryPredicate¶

interface FilterQueryPredicate<T> : CompoundBsonNode, FieldDsl

DSL for MongoDB operators that are used as predicates in conditions in a context where the targeted field is already specified.

Example¶

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

collection.find {
    User::name { //(1)
        eq("foo")
    }
}

By referring to a specific property, we obtain a FilterQueryPredicate that we can use to declare many operators on that property.

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

External resources¶

Official documentation

Parameters¶

T: The type on which this predicate applies. For example, if the selected field is of type String, then T is String.

Constructors¶

FilterQueryPredicate¶

@LowLevelApi



fun <T> FilterQueryPredicate(context: BsonContext): FilterQueryPredicate<T>

Creates an empty FilterQueryPredicate.

Properties¶

`context`¶

@LowLevelApi



abstract val context: BsonContext

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`¶

@LowLevelApi



@DangerousMongoApi



abstract override fun accept(node: BsonNode)

Adds a new node as a child of this one.

`acceptAll`¶

@LowLevelApi



@DangerousMongoApi



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

Adds any number of nodes into this one.

bitsAllClear¶

abstract fun bitsAllClear(mask: UInt)

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

This operator will not match numerical values that cannot be represented as a signed 64-bit integer (e.g. Decimal128) nor ones that have a fractional component.

Example¶

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

collection.find {
    User::age {
        bitsAllClear(UInt.MAX_VALUE)
    }
}

Performance¶

Queries cannot use indexes for this operator, but they can use indexes for other operators.

External resources¶

Official documentation

abstract fun bitsAllClear(mask: ByteArray)

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

This operator will not match numerical values that cannot be represented as a signed 64-bit integer (e.g. Decimal128) nor ones that have a fractional component.

Performance¶

Queries cannot use indexes for this operator, but they can use indexes for other operators.

External resources¶

Official documentation

bitsAllSet¶

abstract fun bitsAllSet(mask: UInt)

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

This operator will not match numerical values that cannot be represented as a signed 64-bit integer (e.g. Decimal128) nor ones that have a fractional component.

Example¶

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

collection.find {
    User::age {
        bitsAllSet(UInt.MAX_VALUE)
    }
}

Performance¶

Queries cannot use indexes for this operator, but they can use indexes for other operators.

External resources¶

Official documentation

abstract fun bitsAllSet(mask: ByteArray)

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

This operator will not match numerical values that cannot be represented as a signed 64-bit integer (e.g. Decimal128) nor ones that have a fractional component.

Performance¶

Queries cannot use indexes for this operator, but they can use indexes for other operators.

External resources¶

Official documentation

bitsAnyClear¶

abstract fun bitsAnyClear(mask: UInt)

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

This operator will not match numerical values that cannot be represented as a signed 64-bit integer (e.g. Decimal128) nor ones that have a fractional component.

Example¶

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

collection.find {
    User::age {
        bitsAnyClear(UInt.MAX_VALUE)
    }
}

Performance¶

Queries cannot use indexes for this operator, but they can use indexes for other operators.

External resources¶

Official documentation

abstract fun bitsAnyClear(mask: ByteArray)

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

This operator will not match numerical values that cannot be represented as a signed 64-bit integer (e.g. Decimal128) nor ones that have a fractional component.

Performance¶

Queries cannot use indexes for this operator, but they can use indexes for other operators.

External resources¶

Official documentation

bitsAnySet¶

abstract fun bitsAnySet(mask: UInt)

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

This operator will not match numerical values that cannot be represented as a signed 64-bit integer (e.g. Decimal128) nor ones that have a fractional component.

Example¶

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

collection.find {
    User::age {
        bitsAnySet(UInt.MAX_VALUE)
    }
}

Performance¶

Queries cannot use indexes for this operator, but they can use indexes for other operators.

External resources¶

Official documentation

abstract fun bitsAnySet(mask: ByteArray)

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

This operator will not match numerical values that cannot be represented as a signed 64-bit integer (e.g. Decimal128) nor ones that have a fractional component.

Performance¶

Queries cannot use indexes for this operator, but they can use indexes for other operators.

External resources¶

Official documentation

`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 <Root, Type, Child> Field<Root, Type>.div(child: KProperty1<in Type & Any, Child>): Field<Root, Child>

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

open operator fun <Root, Type, Child> Field<Root, Type>.div(child: Field<Type, Child>): Field<Root, Child>

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

doesNotExist¶

abstract fun doesNotExist()

Matches documents that do not contain the specified field. Documents where the field if null are counted as existing.

Example¶

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

collection.find {
    User::name {
        doesNotExist()
    }
}

External resources¶

Official documentation

See also

FilterQuery.doesNotExist: Shorthand.
FilterQueryPredicate.exists: Opposite.
FilterQueryPredicate.isNull: Only matches elements that are specifically null.

eq¶

abstract fun eq(value: T)

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

Example¶

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

collection.find {
    User::name {
        eq("foo")
    }
}

External resources¶

Official documentation

See also

FilterQuery.eq: Shorthand.

eqNotNull¶

open fun eqNotNull(value: T?)

Matches documents where the value of a field equals value.

If value is null, the operator is not added (all documents are matched).

Example¶

This operator is useful to simplify searches when the criteria is optional. For example, instead of writing:

collection.find {
    User::name {
        if (criteria.name != null)
            eq(criteria.name)
    }
}

this operator can be used instead:

collection.find {
    User::name {
        eqNotNull(criteria.name)
    }
}

External resources¶

Official documentation

See also

FilterQuery.eqNotNull: Shorthand.
FilterQueryPredicate.eq: Equality filter.

exists¶

abstract fun exists()

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

Example¶

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

collection.find {
    User::name {
        exists()
    }
}

External resources¶

Official documentation

See also

FilterQuery.exists: Shorthand.
FilterQueryPredicate.doesNotExist: Opposite.
FilterQueryPredicate.isNotNull: Identical, but does not match elements where the field is null.

`freeze`¶

@LowLevelApi



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.

open operator fun <Root, Type> Field<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> Field<Root, Map<String, Type>>.get(key: String): Field<Root, Type>

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

gt¶

abstract fun gt(value: T)

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

Example¶

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

collection.find {
    User::age { gt(18) }
}

External resources¶

Official documentation

See also

gte¶

abstract fun gte(value: T)

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

Example¶

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

collection.find {
    User::age { gte(18) }
}

External resources¶

Official documentation

See also

gteNotNull¶

open fun gteNotNull(value: T?)

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

If value is null, the operator is not added (all elements are matched).

Example¶

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

collection.find {
    User::age { gteNotNull(18) }
}

External resources¶

Official documentation

See also

FilterQuery.gteNotNull
FilterQueryPredicate.eqNotNull: Learn more about the 'notNull' variants

gtNotNull¶

open fun gtNotNull(value: T?)

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

If value is null, the operator is not added (all elements are matched).

Example¶

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

collection.find {
    User::age { gtNotNull(18) }
}

External resources¶

Official documentation

See also

FilterQuery.gtNotNull
FilterQueryPredicate.eqNotNull: Learn more about the 'notNull' variants

hasType¶

abstract fun hasType(type: BsonType)

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

Querying by data type is useful when dealing with highly unstructured data where data types are not predictable.

Example¶

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

collection.find {
    User::age {
        type(BsonType.STRING)
    }
}

External resources¶

Official documentation

See also

FilterQuery.hasType: Shorthand.
FilterQueryPredicate.isNull: Checks if a value has the type BsonType.Null.
FilterQueryPredicate.isUndefined: Checks if a value has the type BsonType.Undefined.

isNotNull¶

open fun isNotNull()

Selects documents for which the field is not null.

Example¶

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

collection.find {
    User::age { isNotNull() }
}

External resources¶

Official documentation

See also

FilterQuery.isNotNull: Shorthand.
FilterQueryPredicate.isNull: Opposite.

isNotOneOf¶

abstract fun isNotOneOf(values: Collection<T>)

Selects documents for which this field is not equal to any of the given values.

This operator will also select documents for which the field doesn't exist.

Example¶

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

collection.find {
    User::name {
        isNotOneOf(listOf("Alfred", "Arthur"))
    }
}

External resources¶

Official documentation

See also

FilterExpression.isNotOneOf
FilterQueryPredicate.ne

open fun isNotOneOf(vararg values: T)

Selects documents for which this field is not equal to any of the given values.

This operator will also select documents for which the field doesn't exist.

Example¶

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

collection.find {
    User::name {
        isNotOneOf("Alfred", "Arthur")
    }
}

External resources¶

Official documentation

See also

FilterExpression.isNotOneOf
FilterQueryPredicate.ne

isNotUndefined¶

open fun isNotUndefined()

Deprecated¶

This functionality is deprecated in the BSON specification. See https://bsonspec.org/spec.html

Selects documents for which the field is not undefined.

Example¶

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

collection.find {
    User::age { isNotUndefined() }
}

External resources¶

Official documentation

See also

FilterQuery.isNotUndefined: Shorthand.
FilterQueryPredicate.isUndefined: Opposite.

isNull¶

open fun isNull()

Selects documents for which the field is null.

Example¶

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

collection.find {
    User::age { isNull() }
}

External resources¶

Official documentation

See also

FilterQuery.isNull: Shorthand.
FilterQueryPredicate.doesNotExist: Checks if the value is not set.
FilterQueryPredicate.isNotNull: Opposite.

isOneOf¶

abstract fun isOneOf(values: Collection<T>)

Selects documents for which this field is equal to one of the given values.

Example¶

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

collection.find {
    User::name {
        isOneOf(listOf("Alfred", "Arthur"))
    }
}

External resources¶

Official documentation

See also

FilterQuery.isOneOf

open fun isOneOf(vararg values: T)

Selects documents for which this field is equal to one of the given values.

Example¶

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

collection.find {
    User::name {
        isOneOf("Alfred", "Arthur")
    }
}

External resources¶

Official documentation

See also

FilterQuery.isOneOf

isUndefined¶

open fun isUndefined()

Deprecated¶

This functionality is deprecated in the BSON specification. See https://bsonspec.org/spec.html

Selects documents for which the field is undefined.

Example¶

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

collection.find {
    User::age { isUndefined() }
}

External resources¶

Official documentation

See also

FilterQuery.isUndefined: Shorthand.
FilterQueryPredicate.isNotUndefined: Opposite.

lt¶

abstract fun lt(value: T)

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

Example¶

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

collection.find {
    User::age { lt(18) }
}

External resources¶

Official documentation

See also

lte¶

abstract fun lte(value: T)

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

Example¶

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

collection.find {
    User::age { lte(18) }
}

External resources¶

Official documentation

See also

lteNotNull¶

open fun lteNotNull(value: T?)

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

If value is null, the operator is not added (all elements are matched).

Example¶

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

collection.find {
    User::age { lteNotNull(18) }
}

External resources¶

Official documentation

See also

FilterQuery.lteNotNull
FilterQueryPredicate.eqNotNull: Learn more about the 'notNull' variants

ltNotNull¶

open fun ltNotNull(value: T?)

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

If value is null, the operator is not added (all elements are matched).

Example¶

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

collection.find {
    User::age { ltNotNull(18) }
}

External resources¶

Official documentation

See also

FilterQuery.ltNotNull
FilterQueryPredicate.ltNotNull: Learn more about the 'notNull' variants

ne¶

abstract fun ne(value: T)

Matches documents where the value of a field does not equal the value.

The result includes documents which do not contain the specified field.

Example¶

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

collection.find {
    User::name {
        ne("foo")
    }
}

External resources¶

Official documentation

See also

FilterQuery.ne: Shorthand.

not¶

abstract fun not(expression: FilterQueryPredicate<T>.() -> Unit)

Performs a logical NOT operation on the specified expression and selects the documents that do not match the expression. This includes the elements that do not contain the field.

Example¶

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

collection.find {
    User::age {
        not {
            hasType(BsonType.STRING)
        }
    }
}

External resources¶

Official documentation

See also

FilterQuery.not: Shorthand.

regex¶

abstract fun regex(
    pattern: String, 
    caseInsensitive: Boolean = false, 
    dotAll: Boolean = false, 
    extended: Boolean = false, 
    matchEachLine: Boolean = false
)

Matches documents where the field corresponds to a given regex expression.

Example¶

class User(
    val name: String,
)

collection.find {
    User::name {
        regex("John .*")
    }
}

Indexing¶

If possible, prefer using a "^" prefix. For example, if we know that a pattern will only be present at the start of a string, "^foo" will use indexes, whereas "foo" will not.

Avoid using .* at the start and end of a pattern. "foo" is identical to "foo.*", but the former can use indexes and the latter cannot.

External resources¶

Parameters

caseInsensitive: If true, the result is matched even if its case doesn't match. Note that this also disables index usage (even case-insensitive indexes) and ignores collation.
dotAll: If true, the dot character (.) can match newlines.
extended: If true, whitespace (except in character classes) is ignored, and segments starting from an unescaped pound (#) until a newline are ignored, similarly to a Python comment.

User::name.regex(
    pattern = """
        abc # This is a comment, it's not part of the pattern
        123
    """.trimIndent(),
    extended = true,
)

which is identical to the non-extended pattern "abc123".

matchEachLine: If true, the special characters ^ and $ match the beginning and end of each line, instead of matching the beginning and end of the entire string. Therefore, "^S" will match "First line\nSecond line", which would not match otherwise.

See also

FilterQuery.regex: Shorthand syntax

`simplify`¶

@LowLevelApi



abstract fun simplify(): BsonNode?

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`¶

abstract override fun toString(): String

JSON representation of this expression.

`unsafe`¶

open infix fun <Root, Child> KProperty1<Root, *>.unsafe(child: String): Field<Root, Child>

Refers to a field child of the current field, with no compile-time safety.

open infix fun <Root, Child> KProperty1<Root, *>.unsafe(child: KProperty1<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Child> KProperty1<Root, *>.unsafe(child: Field<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Child> Field<Root, *>.unsafe(child: KProperty1<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Child> Field<Root, *>.unsafe(child: Field<*, Child>): Field<Root, Child>

Refers to a field child of the current field, without checking that it is a field available on the current object.

open infix fun <Root, Type, Child> Field<Root, Type>.unsafe(child: String): Field<Root, Child>

Refers to a field child of the current field, with no compile-time safety.

`writeTo`¶

@LowLevelApi



abstract override fun writeTo(writer: BsonFieldWriter)

Writes the result of simplifying this expression into writer.