abstract fun <T : RealmObject> copyToRealm(instance: T, updatePolicy: UpdatePolicy = UpdatePolicy.ERROR): T

Copy new objects into the realm or update existing objects.

This will recursively copy objects to the realm. Both those with and without primary keys. The behavior of copying objects with primary keys will depend on the specified update policy. Calling with UpdatePolicy.ERROR will disallow updating existing objects. So if an object with the same primary key already exists, an error will be thrown. Setting this thus means that only new objects can be created. Calling with UpdatePolicy.ALL mean that an existing object with a matching primary key will have all its properties updated with the values from the input object.

Already managed update-to-date objects will not be copied but just return the instance itself. Trying to copy outdated objects will throw an exception. To get hold of an updated reference for an object use findLatest.


the managed version of the instance.



the object to create a copy from.


update policy when importing objects.


if the object graph of instance either contains an object with a primary key value that already exists and the update policy is UpdatePolicy.ERROR or if the object graph contains an object from a previous version.