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

Type 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, type: KType): FilterQueryPredicate<T>

Creates an empty FilterQueryPredicate.

Users should generally not need to interact with this function, as KtMongo already provides an instance of FilterQueryPredicate in all contexts where one is useful.

If calling this method, prefer the inline overload.

Parameters

type: The KType instance that corresponds to type T. If KType doesn't correspond to T, the behavior is unspecified.

@LowLevelApi
inline fun <T> FilterQueryPredicate(context: BsonContext): FilterQueryPredicate<T>

Creates an empty FilterQueryPredicate.

Users should generally not need to interact with this function, as KtMongo already provides an instance of FilterQueryPredicate in all contexts where one is useful.

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.
exists: Opposite.
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 are 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.
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.
doesNotExist: Opposite.
isNotNull: Identical, but does not match elements where the field is null.

`freeze`¶

@LowLevelApi
abstract override fun freeze()

Makes this expression immutable.

geoIntersects¶

abstract fun geoIntersects(geometry: Geo)

Matches documents whose geospatial data intersects with the given geometry.

This operator should only be called on fields containing GeoJSON data.

Example

class GasStation(
    val _id: ObjectId,
    val name: String,
    val loc: Geo.Point,
)

gasStations.find {
    GasStation::loc {
        geoIntersects(
            Geo.LineString(
                Geo.Point(Longitude(-105.82), Latitude(33.87)),
                Geo.Point(Longitude(-106.31), Latitude(35.65)),
                Geo.Point(Longitude(-107.39), Latitude(35.98)),
            )
        )
    }
}

Indexing

This operator does not require a 2dsphere index. However, such an index is recommended for performance.

External resources

abstract fun geoIntersects(polygon: Geo.Polygon, crs: Geo.CoordinateReferenceSystem? = null)

Matches documents whose geospatial data intersects with the given polygon.

This operator should only be called on fields containing GeoJSON data.

Indexing

This operator does not require a 2dsphere index. However, such an index is recommended for performance.

Big polygons

For queries that specify a polygon with an area greater than a single hemisphere, the default crs results in queries for the complementary geometry.

In these cases, specify a crs of Geo.CoordinateReferenceSystem.MongoDB. Only single-ringed polygons are supported.

External resources

geoWithin¶

abstract fun geoWithin(polygon: Geo.Polygon, crs: Geo.CoordinateReferenceSystem? = null)

Matches documents where a Geo.Point is within the given polygon.

This operator should only be called on fields of type Geo.Point.

Example

class Place(
    val _id: ObjectId,
    val name: String,
    val location: Geo.Point,
    val category: String,
)

places.find {
    Place::location {
        geoWithin(
            Geo.Polygon(
                Geo.Point(Longitude(-73.95), Latitude(40.80)),
                Geo.Point(Longitude(-73.94), Latitude(40.79)),
                Geo.Point(Longitude(-73.97), Latitude(40.79)),
                Geo.Point(Longitude(-79.98), Latitude(40.76)),
                Geo.Point(Longitude(-73.95), Latitude(40.80)),
            )
        )
    }
}

Indexing

This operator does not require a 2d or 2dsphere index. However, such an index is recommended for performance.

Big polygons

For queries that specify a polygon greater with areas greater than a single hemisphere, the default crs results in queries for the complimentary geometry.

In these cases, specify a crs of Geo.CoordinateReferenceSystem.MongoDB. Only single-ringed polygons are supported.

External resources

abstract fun geoWithin(polygons: Geo.MultiPolygon)

Matches documents where a Geo.Point is within the given polygons.

This operator should only be called on fields of type Geo.Point.

Indexing

This operator does not require a 2d or 2dsphere index. However, such an index is recommended for performance.

Big polygons

For queries that specify a polygon greater with areas greater than a single hemisphere, this operator matches the complimentary geometry.

External resources

`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
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
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.
isNull: Checks if a value has the type BsonType.Null.
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.
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

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

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.
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.
doesNotExist: Checks if the value is not set.
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.
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
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
ltNotNull: Learn more about the 'notNull' variants

mod¶

abstract fun mod(divisor: Long, remainder: Long)

Selects documents where the value of the field divided by divisor has the specified remainder.

If the value of the field is a floating-point number, it is rounded towards zero before the operation.

Example

To find all users with an odd score:

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

collection.find {
    User::age { mod(2, 1) }
}

This request returns elements where age % 2 == 1.

External resources

Official documentation

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.

near¶

abstract fun near(
    target: Geo.Point, 
    minDistance: Double? = null, 
    maxDistance: Double? = null
)

Matches documents where a Geo.Point is near the target.

Documents are returned sorted, from the closest to the furthest. For the best performance, avoid specifying an additional sort.

For large areas, in which the curvature of the Earth becomes significant, consider using nearSphere instead.

This operator should only be called on fields of type Geo.Point.

Example

Find all bear sightings with 1km of Périgueux:

class BearSightings(
    val _id: ObjectId,
    val location: Geo.Point,
)

sightings.find {
    BearSightings::location {
        near(
            target = Geo.Point(Longitude(0.7269), Latitude(45.1828)),
            maxDistance = 1000.0,
        )
    }
}.toList()

Indexing

This operator requires a 2dsphere index.

This operator cannot be combined with other operators requiring special indexes, like $text.

This operator is not permitted inside an aggregation pipeline. Instead, use the $geoNear stage.

External resources

Parameters

target: The point to search near.
minDistance: If specified, only matches documents that are further away from the target than this distance, in meters.
maxDistance: If specified, only matches documents that are closer to the target than this distance, in meters.

See also

FilterQuery.near: Convenience method with better type-safety.

nearSphere¶

abstract fun nearSphere(
    target: Geo.Point, 
    minDistance: Double? = null, 
    maxDistance: Double? = null
)

Matches documents where a Geo.Point is near the target, using spherical geometry.

Unlike near, uses spherical geometry for distance calculations, so results are accurate across large areas.

Documents are returned sorted, from the closest to the furthest. For the best performance, avoid specifying an additional sort.

This operator should only be called on fields of type Geo.Point.

Example

Find all bear sightings with 1km of Périgueux:

class BearSightings(
    val _id: ObjectId,
    val location: Geo.Point,
)

sightings.find {
    BearSightings::location {
        nearSphere(
            target = Geo.Point(Longitude(0.7269), Latitude(45.1828)),
            maxDistance = 1000.0,
        )
    }
}.toList()

Indexing

This operator requires a 2dsphere index.

This operator cannot be combined with other operators requiring special indexes, like $text.

This operator is not permitted inside an aggregation pipeline. Instead, use the $geoNear stage.

External resources

Parameters

target: The point to search near.
minDistance: If specified, only matches documents that are further away from the target than this distance, in meters.
maxDistance: If specified, only matches documents that are closer to the target than this distance, in meters.

See also

FilterQuery.nearSphere: Convenience method with better type-safety.

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(
    @Language(value = "JSRegexp") 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(): BsonDocument

Writes the result of simplifying to a new BsonDocument.

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