Docs Menu

Docs HomeRealm

Create Realm Objects - Kotlin SDK

On this page

  • Create an Object
  • Create a Collection
  • Create an Object with a RealmSet Property
  • Create an Object with a Dictionary Property
  • Create an Embedded Object
  • Create an Asymmetric Object


You can only insert new objects into a realm within a write transaction.

Instantiate Realm objects as you would any other object. In a transaction, you can add the object to the realm if the realm's schema includes the object type. When you add an instance to the realm, it becomes managed by that realm.

To persist a new object to a realm:

  1. Instantiate a new object instance with the class constructor. You can use an apply block to configure multiple properties at once.

  2. Open a write transaction with realm.write() or realm.writeBlocking().

  3. Pass the new object instance to copyToRealm() to persist the object data to the realm. This method returns a managed instance of the object. You can modify the persisted object through the returned instance.

realm.write {
this.copyToRealm(Frog().apply {
name = "Kermit"
age = 45
species = "Green"
owner = "Jim"


You can also upsert into a realm using specific criteria. See Upsert a Realm Object.

You can create collections of items using RealmList, RealmSet, and RealmDictionary types.

You can also register a notification handler to listen for changes to a collection. For more information, see React To Changes.

You can create objects that contain RealmSet properties as you would any Realm object, but you can only set the values of a mutable set property within a write transaction.

For more information about defining a set property, refer to Define a RealmSet.

To add a single item to a RealmSet, pass the object you want to add to the set to the set.add() method:

realm.write {
// Create a Frog object named 'Kermit'
// Add item to the RealmSet using the add() method
val frog = copyToRealm(
Frog().apply {
name = "Kermit"
favoriteSnacks.add(Snack().apply { name = "flies" })
println(frog.favoriteSnacks.first().name) // prints "flies"

To add multiple items to a RealmSet, pass the elements you want to add to the set.addAll() method:

realm.write {
val frog = query<Frog>().find().first()
val snackSet = frog.favoriteSnacks
// Create two more Snack objects
val cricketsSnack = copyToRealm(
Snack().apply {
name = "crickets"
val wormsSnack = copyToRealm(
Snack().apply {
name = "worms"
// Add multiple items to the RealmSet using the addAll() method
snackSet.addAll(setOf(cricketsSnack, wormsSnack))

You can create objects with RealmDictionary properties. The RealmDictionary keys may only be strings, but values may be any type of Realm-supported primitive, a RealmObject, or an EmbeddedObject.

For more information about defining a dictionary property, refer to Define a RealmDictionary/RealmMap.

realm.write {
this.copyToRealm(Frog().apply {
name = "Kermit"
favoritePondsByForest = realmDictionaryOf("Hundred Acre Wood" to "Picnic Pond", "Lothlorien" to "Linya")

Realm disallows the use of . or $ characters in map keys. You can use percent encoding and decoding to store a map key that contains one of these disallowed characters.

// Percent encode . or $ characters to use them in map keys
val mapKey = "Hundred Acre Wood.Northeast"
val encodedMapKey = "Hundred Acre Wood%2ENortheast"

To create an embedded object, assign an instance of the EmbeddedRealmObject to a parent object's property:

// Create a parent object with one embedded address
realm.write {
val contact = copyToRealm(Contact())
contact.apply {
name = "Nick Riviera"
// Embed the address in the contact object
address = Address().apply {
street = "123 Fake St"
city = "Some Town"
state = "MA"
postalCode = "12345"

New in version 1.10.0.

An asymmetric object is an insert-only object. When you create an AsymmetricRealmObject, it syncs unidirectionally via Data Ingest to the Atlas database linked to your Atlas App Services App. You cannot access an AsymmetricRealmObject locally, add it to or remove it from a realm, or query for it. For more information, see Asymmetric Objects.

You must create an AsymmetricRealmObject using the insert() extension method within a write transaction:

realm.write {
insert(WeatherSensor().apply {
deviceId = "WX1278UIT"
temperatureInFarenheit = 6.7F
barometricPressureInHg = 29.65F
windSpeedInMph = 2

You can create asymmetric objects for a realm initialized with a Flexible Sync SyncConfiguration. For more information, see Open the synced Realm with a Flexible Sync configuration.

←  Read & Write Data - Kotlin SDKRead Realm Objects - Kotlin SDK →
Share Feedback
© 2023 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2023 MongoDB, Inc.