Supported Types - Kotlin SDK

Supported Data Types List

The Kotlin SDK supports the following Kotlin types, BSON types, and Realm-specific types, which you can use for unique identifiers, timestamps, counters, and collections.

The Kotlin SDK does not natively support:

• user-defined enumeration properties. Refer to the Enums section for more information on how to use enums in your Realm objects.

• Kotlin's built-in Date or Instant. Refer to the RealmInstant section for more information on how to use timestamps in your Realm objects.

Realm object properties must be mutable and initialized when declared. The Kotlin SDK does not currently support abstract properties. You can declare properties optional (nullable) using the built-in ? Kotlin operator, or you can assign a default value to a property when you declare it.

Kotlin Data Types

The following table lists the supported Kotlin data types and examples of how to declare them as required or optional properties in your object model.

var stringReq: String = ""

var stringOpt: String? = null

var byteReq: Byte = 0

var byteOpt: Byte? = null

var shortReq: Short = 0

var shortOpt: Short? = null

var intReq: Int = 0

var intOpt: Int? = null

var longReq: Long = 0L

var longOpt: Long? = null

var floatReq: Float = 0.0f

var floatOpt: Float? = null

var doubleReq: Double = 0.0

var doubleOpt: Double? = null

var boolReq: Boolean = false

var boolOpt: Boolean? = null

var charReq: Char = 'a'

var charOpt: Char? = null

MongoDB BSON Types

The following table lists the supported MongoDB BSON data types and examples of how to declare them as required or optional properties in your object model. To use these types, you must import them from the org.mongodb.kbson package.

var objectIdReq: ObjectId = ObjectId()

var objectIdOpt: ObjectId? = null

var decimal128Req: Decimal128 = Decimal128("123.456")

var decimal128Opt: Decimal128? = null

Realm-Specific Types

The following table lists the supported Realm-specific data types and examples of how to declare them as required or optional properties in your object model.

var uuidReq: RealmUUID = RealmUUID.random()

var uuidOpt: RealmUUID? = null

var realmInstantReq: RealmInstant = RealmInstant.now()

var realmInstantOpt: RealmInstant? = null

var realmAnyOpt: RealmAny? = RealmAny.create("foo")

var mutableRealmIntReq: MutableRealmInt = MutableRealmInt.create(0)

var mutableRealmIntOpt: MutableRealmInt? = null

var listReq: RealmList<CustomObjectType> = realmListOf()

var setReq: RealmSet<String> = realmSetOf()

var dictionaryReq: RealmDictionary<String> = realmDictionaryOf()

var realmObjectPropertyOpt: CustomObjectType? = null

var embeddedProperty: EmbeddedObjectType? = null

Unique Identifiers

The Kotlin SDK supports UUID and ObjectId as unique identifiers for Realm objects.

val uuid1 = RealmUUID.from("46423f1b-ce3e-4a7e-812f-004cf9c42d76")
val uuid2 = RealmUUID.random()

MutableRealmInt (Counter)

The Kotlin SDK offers MutableRealmInt as a special integer type that you can use as a logical counter to accurately synchronize numeric changes across multiple distributed clients. It behaves like a Long but also supports increment and decrement methods that implement a conflict-free replicated data type. This ensures that numeric updates can be executed regardless of order to converge to the same value.

A MutableRealmInt property:

• cannot be used as a primary key

• cannot store null values, but it can be declared nullable (MutableRealmInt?)

Additionally, MutableRealmInt fields:

• are backed by Kotlin's numeric types, so no migration is required when changing a numeric field to MutableRealmInt.

• can use operators and infix functions similar to those provided by Long. However, note that any operations other than set, increment, and decrement do not mutate the instance on which they are executed. Instead, they create a new, unmanaged MutableRealmInt instance with the updated value.

Learn how to Create a MutableRealmInt (Counter) Property and Update a MutableRealmInt (Counter) Property.

RealmInstant (Timestamp)

You cannot store Kotlin's built-in Date or Instant types in Realm.

Instead, the Kotlin SDK uses the RealmInstant type to store time information as a Unix epoch timestamp.

If you need timestamp data in a form other than RealmInstant, you can add conversion code to your model class based on the following example:

// model class that stores an Instant (kotlinx-datetime) field as a RealmInstant via a conversion
class RealmInstantConversion : RealmObject {
    private var _timestamp: RealmInstant = RealmInstant.from(0, 0)
    public var timestamp: Instant
        get() {
            return _timestamp.toInstant()
        }
        set(value) {
            _timestamp = value.toRealmInstant()
        }
}
fun RealmInstant.toInstant(): Instant {
    val sec: Long = this.epochSeconds
    // The value always lies in the range `-999_999_999..999_999_999`.
    // minus for timestamps before epoch, positive for after
    val nano: Int = this.nanosecondsOfSecond
    return if (sec >= 0) { // For positive timestamps, conversion can happen directly
        Instant.fromEpochSeconds(sec, nano.toLong())
    } else {
        // For negative timestamps, RealmInstant starts from the higher value with negative
        // nanoseconds, while Instant starts from the lower value with positive nanoseconds
        // TODO This probably breaks at edge cases like MIN/MAX
        Instant.fromEpochSeconds(sec - 1, 1_000_000 + nano.toLong())
    }
}
fun Instant.toRealmInstant(): RealmInstant {
    val sec: Long = this.epochSeconds
    // The value is always positive and lies in the range `0..999_999_999`.
    val nano: Int = this.nanosecondsOfSecond
    return if (sec >= 0) { // For positive timestamps, conversion can happen directly
        RealmInstant.from(sec, nano)
    } else {
        // For negative timestamps, RealmInstant starts from the higher value with negative
        // nanoseconds, while Instant starts from the lower value with positive nanoseconds
        // TODO This probably breaks at edge cases like MIN/MAX
        RealmInstant.from(sec + 1, -1_000_000 + nano)
    }
}

RealmAny (Mixed)

RealmAny represents a non-nullable mixed data type. It behaves like the value type that it contains. RealmAny can hold:

• supported Kotlin data types (note that Byte, Char, Int, Long, and Short values are converted internally to int64_t values)

• supported BSON types

• the following Realm-specific types:

  • RealmInstant

  • RealmUUID

  • RealmObject (holds a reference to the object, not a copy of it)

RealmAny cannot hold EmbeddedRealmObject types, collection types (RealmList, RealmSet, RealmDictionary), or another RealmAny.

RealmAny properties:

• are indexable but cannot be used as a primary key

• must be declared nullable (RealmAny?), but they cannot store null values

• can be aggregated with RealmQuery.max, RealmQuery.min, and RealmQuery.sum.

• can be sorted. Sort order from highest to lowest:

  1. Boolean

  2. Byte, Double, Decimal128, Int, Float, Long, Short

  3. byte[], String

  4. Date

  5. ObjectId

  6. UUID

  7. RealmObject

You can store multiple RealmAny instances in RealmList, RealmDictionary, or RealmSet fields.

Collection Types

The Kotlin SDK offers several collection types that you can use as properties in your data model. A collection is an object that contains zero or more instances of one supported data type. Realm collections are homogenous (all objects in a collection are of the same type) and are backed by their corresponding built-in Kotlin classes.

Collection types are non-null. When you define a collection property, you must initialize it. For more information, refer to Create a Collection.

RealmObjects as Properties

You can use RealmObject and any subclasses, except AsymmetricRealmObject as properties in your object model.

Geospatial Types

The Kotlin SDK supports geospatial queries using the following data types:

• GeoPoint

• GeoCircle

• GeoBox

• GeoPolygon

For more information on querying with geospatial data, refer to Geospatial Data.

Enums

The Kotlin SDK does not natively support enumerations, or enums. To use enums in a Realm object class, define a field with a type matching the underlying data type of your enum.

Then, create getters and setters for the field that convert the field value between the underlying value and the enum type.

enum class EnumClass(var state: String) {
    NOT_STARTED("NOT_STARTED"),
    IN_PROGRESS("IN_PROGRESS"),
    COMPLETE("COMPLETE")
}
class EnumObject : RealmObject {
    var name: String? = null
    private var state: String = EnumClass.NOT_STARTED.state
    var stateEnum: EnumClass
        get() = EnumClass.valueOf(state)
        set(value) {
            state = value.state
        }
}