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¶
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
type: Get a value's type.
isNumber¶
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: Get a value's type.
type¶
Functions¶
div¶
open operator fun <Context : Any, Root, Child> Value<Context, Root>.div(field: Field<Root, Child>): Value<Context, Child>
@JvmName(name = "divFieldReceiver")
open operator fun <Context : Any, Root, Child> Field<Context, Root>.div(field: Field<Root, Child>): Value<Context, Child>
@JvmName(name = "divResultReceiver")
inline operator fun <Context : Any, Root, Child> Root.div(field: Field<Root, Child>): Value<Context, Child>
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¶
Refers to a specific item in an array, by its index.
Refers to a specific item in a map, by its name.
Refers to a specific item in an array, by its index.
Refers to a specific item in a map, by its name.
of¶
Refers to a field within an aggregation value.
Example
Refers to a Kotlin value within an aggregation value.
Example
Refers to a BsonType within an aggregation value.
Example
toBoolean¶
@JvmName(name = "toBooleanFieldReceiver")
open fun <R : Any> Field<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
type: Get the value's type.
toDouble¶
@JvmName(name = "toDoubleFieldReceiver")
open fun <R : Any> Field<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
type: Get the value's type.
toInstant¶
@JvmName(name = "toInstantFieldReceiver")
open fun <R : Any> Field<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
type: Get the value's type.
toInt¶
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
type: Get the value's type.
toLong¶
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
type: Get the value's type.
toObjectId¶
@JvmName(name = "toObjectIdFieldReceiver")
open fun <R : Any> Field<R, *>.toObjectId(): Value<R, ObjectId>
@JvmName(name = "toObjectIdPropertyReceiver")
open fun <R : Any> KProperty1<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
type: Get the value's type.
toText¶
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
type: Get the value's type.
toUuid¶
@JvmName(name = "toUuidFieldReceiver")
@ExperimentalUuidApi
open fun <R : Any> Field<R, *>.toUuid(): Value<R, Uuid>
@JvmName(name = "toUuidPropertyReceiver")
@ExperimentalUuidApi
open fun <R : Any> KProperty1<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
type: Get the value's type.
unsafe¶
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.
Refers to a field child of the current field, without checking that it is a field available on the current object.
Refers to a field child of the current field, without checking that it is a field available on the current object.
Refers to a field child of the current field, without checking that it is a field available on the current object.