Skip to content

TypeValueOperators

interface TypeValueOperators : ValueOperators

Operators to interact with type information.

To learn more about aggregation operators, view AggregationOperators.

Inheritors

Properties

context

@LowLevelApi



abstract override val context: BsonContext

The strategy used when converting from KProperty1 to Field.

field

Converts a Kotlin property into a Field.

isArray

open val <R : Any> Value<R, *>.isArray: Value<R, Boolean>

Determines if this value is an array.

Example
class User(
    val data: String,
)

collection.aggregate()
    .project {
        Field.unsafe<Boolean>("dataIsArray") set of(User::data).isArray
    }
External resources

See also

isNumber

open val <R : Any> Value<R, *>.isNumber: Value<R, Boolean>

Determines if this value is a number.

The following types are considered numbers:

Example
class User(
    val data: String,
)

collection.aggregate()
    .project {
        Field.unsafe<Boolean>("dataIsNumber") set of(User::data).isNumber
    }
External resources

See also

type

open val <R : Any> Value<R, *>.type: Value<R, BsonType>

Gets the BsonType of the current value.

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

collection.aggregate()
    .project {
        Field.unsafe<Boolean>("nameIsString") set (of(User::name).type eq of(BsonType.String))
    }
External resources

See also

Functions

div

open operator fun <Context : Any, Root, Child> Value<Context, Root>.div(field: Field<Root, Child>): Value<Context, Child>

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

Examples
class User(
    val name: String,
)

class Data(
    val users: List<User>,
    val userNames: List<Int>,
)

data.aggregate()
    .set {
        Data::userNames set Data::users.map { it / User::name }
    }
External resources
open operator fun <Context : Any, Root, Child> Value<Context, Root>.div(field: KProperty1<Root, Child>): Value<Context, Child>

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

Examples
class User(
    val name: String,
)

class Data(
    val users: List<User>,
    val userNames: List<Int>,
)

data.aggregate()
    .set {
        Data::userNames set Data::users.map { it / User::name }
    }
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.

of

open fun <Context : Any, Result> of(field: Field<Context, Result>): Value<Context, Result>

Refers to a field within an aggregation value.

Example
class Product(
    val acceptanceDate: Instant,
    val publishingDate: Instant,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::publishingDate) lt of(Product::acceptanceDate)
    }
}

Refers to a field within an aggregation value.

Example
class Product(
    val acceptanceDate: Instant,
    val publishingDate: Instant,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::publishingDate) lt of(Product::acceptanceDate)
    }
}

open fun <Result> of(value: Result): Value<Any, Result>

Refers to a Kotlin value within an aggregation value.

Example
class Product(
    val age: Int,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::age) lt of(15)
    }
}

open fun of(value: BsonType): Value<Any, BsonType>

Refers to a BsonType within an aggregation value.

Example
class Product(
    val age: Int,
)

val publishedBeforeAcceptance = products.find {
    expr {
        of(Product::age).type eq of(BsonType.Int32)
    }
}

toBoolean

open fun <R : Any> Value<R, *>.toBoolean(): Value<R, Boolean>

Converts this value to a BsonType.Boolean.

Conversion algorithm

BsonType.Boolean is returned as itself.

Numeric types (BsonType.Int32, BsonType.Int64, BsonType.Double and BsonType.Decimal128) consider that 0 is false and all other values are true.

BsonType.Null always returns null.

All other types always return true.

Example
class User(
    val foo: String
)

users.aggregate()
    .project {
        Field.unsafe<Boolean>("asBoolean") set of(User::foo).toBoolean()
    }
External resources

See also

toDouble

open fun <R : Any> Value<R, *>.toDouble(): Value<R, Double>

Converts this value to a BsonType.Double.

Conversion algorithm

BsonType.Double is returned as itself.

BsonType.Int32 and BsonType.Int64 are extended to a double.

BsonType.Boolean becomes 1 if true and 0 if false.

BsonType.Decimal128 is converted if it is within the possible range of a double value. Otherwise, an exception is thrown.

BsonType.String is parsed as a double. Only base 10 numbers can be parsed. If the value is outside the range of a double, an exception is thrown. "-5.5" and "123456" are two valid examples.

BsonType.Datetime returns the number of milliseconds since the epoch.

BsonType.Null always returns null.

Other types throw an exception.

Example
class Metric(
    val instant: Instant,
    val millis: Double
)

users.aggregate()
    .set {
        User::millis set of(Metric::instant).toDouble()
    }
External resources

See also

toInstant

open fun <R : Any> Value<R, *>.toInstant(): Value<R, Instant>

Converts this value to an Instant (BsonType.Datetime).

Conversion algorithm

BsonType.Datetime is returned as itself.

BsonType.Int64, BsonType.Double and BsonType.Decimal128 are interpreted as a timestamp from the UNIX epoch in milliseconds: positive values happen after the epoch, negative values happen before the epoch.

BsonType.String is parsed using the ISO timestamp formats, for example:

  • "2018-03-20"

  • "2018-03-20T12:00:00Z"

  • "2018-03-20T12:00:00+0500"

BsonType.ObjectId and BsonType.Timestamp are represented by extracting their timestamp component (both have a precision of one second).

BsonType.Null always returns null.

Other types throw an exception.

Example
class User(
    val modificationDate: Instant
)

// Update old data
users.updateManyWithPipeline(
    filter = {
        User::modificationType {
            not {
                hasType(BsonType.String)
            }
        }
    }
) {
   set {
       User::name set of(User::name).toInstant()
   }
}
External resources

See also

toInt

open fun <R : Any> Value<R, *>.toInt(): Value<R, Int>

Converts this value to an Int (BsonType.Int32).

Conversion algorithm

BsonType.Int32 is returned as itself.

BsonType.Int64 is converted to an Int if it fits into the range. Otherwise, an exception is thrown.

BsonType.Boolean becomes 1 if true and 0 if false.

BsonType.Double and BsonType.Decimal128 are truncated to an integer value. If this value does not fall in the valid range for an int, an exception is thrown.

BsonType.String is parsed as an int. Only base 10 numbers can be parsed. If the value is outside the range of a double, an exception is thrown. "-5" and "123456" are two valid examples. Floating-point numbers are not supported (use toDouble).

BsonType.Datetime returns the number of milliseconds since the epoch.

BsonType.Null always returns null.

Other types throw an exception.

Example
class Product(
    val quantity: Double,
)

users.aggregate()
    .set {
        Field.unsafe<Int>("quantity") set of(Product::quantity).toInt()
    }
External resources

See also

toLong

open fun <R : Any> Value<R, *>.toLong(): Value<R, Long>

Converts this value to an Long (BsonType.Int64).

Conversion algorithm

BsonType.Int64 is returned as itself.

BsonType.Int32 is extended to a Long.

BsonType.Boolean becomes 1 if true and 0 if false.

BsonType.Double and BsonType.Decimal128 are truncated to an integer value. If this value does not fall in the valid range for a long, an exception is thrown.

BsonType.String is parsed as a double. Only base 10 numbers can be parsed. If the value is outside the range of a double, an exception is thrown. "-5" and "123456" are two valid examples. Floating-point numbers are not supported (use toDouble).

BsonType.Datetime returns the number of milliseconds since the epoch.

BsonType.Null always returns null.

Other types throw an exception.

Example
class Product(
    val quantity: Double,
)

users.aggregate()
    .set {
        Field.unsafe<Long>("quantity") set of(Product::quantity).toLong()
    }
External resources

See also

toObjectId

open fun <R : Any> Value<R, *>.toObjectId(): Value<R, ObjectId>

Converts this value to an ObjectId.

Conversion algorithm

BsonType.ObjectId is returned as itself.

BsonType.String is parsed as an ObjectId as a 24-character hexadecimal representation, for example "5ab9cbfa31c2ab715d42129e".

BsonType.Null always returns null.

Other types throw an exception.

Example
class Product(
    val _id: ObjectId,
)

// Migrate ids which were accidentally written as strings:
products.updateManyWithPipeline {
    _id set of(Product::_id).toObjectId()
}
External resources

See also

toText

open fun <R : Any> Value<R, *>.toText(): Value<R, String>

Converts this value to a String.

Note: the MongoDB operator is called toString, but that name would be ambiguous in Kotlin because of Any.toString.

Conversion algorithm

BsonType.String is always returned as itself.

BsonType.Int32, BsonType.Int64, BsonType.Double, BsonType.Decimal128, BsonType.Boolean and BsonType.BinaryData are converted to a string.

BsonType.ObjectId returns its hexadecimal representation.

BsonType.Datetime is formatted in ISO.

BsonType.Null always returns null.

Example
class Product(
    val _id: ObjectId,
    val age: Double,
)

// Migrate ids which were accidentally written as strings:
products.updateManyWithPipeline {
    _id set of(Product::age).toText()
}
External resources

See also

toUuid

@ExperimentalUuidApi
open fun <R : Any> Value<R, *>.toUuid(): Value<R, Uuid>

Converts a string value to a Uuid (BsonType.BinaryData).

Example
class User(
    val _id: ObjectId,
    val eventId: Uuid,
)

// Convert old 'eventId' data which was incorrectly created as strings
users.updateManyWithPipeline {
    set {
        User::eventId set of(User::eventId).toUuid()
    }
}
External resources

See also

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.