Docs Menu

Docs HomeRealm

Update Realm Objects - Kotlin SDK

On this page

  • Update Object Properties
  • Update a Dictionary Property
  • Update an Embedded Object Property
  • Update a Collection
  • Overwrite an Embedded Object
  • Upsert a Realm Object


You can only modify objects in a realm within a write transaction.

To modify an object stored within a realm:

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

  2. Query the transaction's mutable realm with realm.query(). Specify the object type as a type parameter passed to query(). To ensure your query returns the correct object, filter with unique identifying information such as a primary key value.

  3. Change an object property within the write transaction. The SDK automatically persists changes to the realm.

realm.write {
// fetch a frog from the realm by primary key
val frog: Frog? =
this.query<Frog>("_id == $0", PRIMARY_KEY_VALUE).first().find()
// modify the frog's age in the write transaction to persist the new age to the realm
frog?.age = 42


Updating Strings or Byte arrays

Because Realm operates on fields as a whole, it's not possible to directly update individual elements of strings or byte arrays. Instead, you'll need to read the whole field, make your modification to individual elements, and then write the entire field back again in a transaction block.

You can update a RealmDictionary as you would a Kotlin Map.

// Find frogs who have forests with favorite ponds
val frogs = realm.query<Frog>().find()
val frogsWithFavoritePonds = frogs.query("favoritePondsByForest.@count > 1").find()
val thisFrog = frogsWithFavoritePonds.first()
// Update the value for a key if it exists
if (thisFrog.favoritePondsByForest.containsKey("Hundred Acre Wood")) {
realm.write {
"Hundred Acre Wood",
"Lily Pad Pond"
// Add a new key-value pair
realm.write {
findLatest(thisFrog)?.favoritePondsByForest?.put("Sherwood Forest", "Miller Pond")

To update a property in an EmbeddedRealmObject, fetch the object and reassign the embedded object properties in a write transaction:

// Modify embedded object properties in a write transaction
realm.write {
// Fetch the objects
val addressToUpdate = findLatest(address)?: error("Cannot find latest version of embedded object")
val contactToUpdate = findLatest(contact)?: error("Cannot find latest version of parent object")
// Update a single embedded object property directly
addressToUpdate.street = "100 10th St N"
// Update multiple properties
addressToUpdate.apply {
street = "202 Coconut Court"
city = "Los Angeles"
state = "CA"
postalCode = "90210"
// Update property through the parent object
contactToUpdate.address?.state = "NY"

To update a collection of objects in a realm, such as a RealmList or RealmSet:

  1. Query a realm for a collection of objects with realm.query().

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

  3. Update elements of the set of RealmResults returned by the query.

val tadpoles: RealmQuery<Frog> =
realm.query<Frog>("age > $0", 2)
for (tadpole in tadpoles.find()) {
realm.write {
findLatest(tadpole)?.name = + " Jr."

To overwrite an embedded object, assign a new embedded object instance to the property in a write transaction:

// Overwrite the embedded object in a write transaction
realm.write {
// Fetch the parent object
val parentObject: Contact =
realm.query<Contact>("name == 'Nick Riviera'").find().first()
// Overwrite the embedded object (deletes the existing object)
parentObject.address = Address().apply {
street = "202 Coconut Court"
city = "Los Angeles"
state = "CA"
postalCode = "90210"

The upsert operation either inserts a new instance of an object or updates an existing object that meets certain criteria.

To upsert into a realm:

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

  2. Insert an object with a primary key using copyToRealm(). If an object matching the primary key already exists, the Kotlin SDK updates the existing object. If no object exists that matches the primary key, the Kotlin SDK inserts a new object.

You can specify the UpdatePolicy to use when you upsert an object with an existing primary key:

  • UpdatePolicy.ALL: Update all properties on any existing objects identified with the same primary key.

  • UpdatePolicy.ERROR: Disallow updating existing objects and instead throw an exception if an object already exists with the same primary key.

realm.write {
// The ID of a particular frog can either already exist or be a new ObjectId
val frogId = ObjectId()
// If a frog matching the ID exists, update its properties, otherwise create it
this.copyToRealm(Frog().apply {
_id = frogId
name = "Wirt"
age = 4
species = "Greyfrog"
owner = "L'oric"
}, updatePolicy = UpdatePolicy.ALL)
←  Read Realm Objects - Kotlin SDKDelete Realm Objects - Kotlin SDK →
Share Feedback
© 2023 MongoDB, Inc.


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