Q&A EmbeddedObject

[DominicFrei]

Q&A EmbeddedObject

This Q&A section aims to help you better understand the RealmObject subtype EmbeddedObject.
We will add and answer common questions here. Feel free to add questions to this thread that might be helpful or create a new discussion if you want to talk about it in detail. In case you encounter bugs or problems you can always create an issue instead and we'll do our best to help you there.

What is an EmbeddedObject?

For a general overview, please refer to our documentation and the API reference.

What kind of relationship is modeled using an EmbeddedObject?

Adding a single EmbeddedObject link to another RealmObject leads to a 1:1 relationship.
You can also use a List<EmbeddedObject> which would be a 1:n relationship.

This relationship is then enforced by the SDK. Such objects do have to have a parent and they cannot have more than one parent. Otherwise you'll get exceptions like the one's we've explained in more detail further down to help you understand if there is something that still needs to be solved. This has to be taken care of during the migration.

Can I change a RealmObject to EmbeddedObject and what about the migration?

You can swap those two types if you need to.
If you change a RealmObject to EmbeddedObject you need to write a migration for this step. During this migration you need to make sure that the 1:1 relationship of the EmbeddedObject and all other classes using it is fulfilled. From then on every EmbeddedObject can only be used by one and exactly one other (parent) object. EmbeddedObjects are not supposed to be queried but rather accessed via the object they are embedded in hence they don't have a primary key.

What does the exception At least one object does not have a backlink (data would get lost). mean?

If you see above exception, please make sure that every EmbeddedObject does have a parent.
If you don't need this EmbeddedObject anymore, you should delete it to fix this exception.

An enhancement for this is planned which will offer an option to do the deletion automatically. At the moment this has to be done manually by writing a migration.

What does the exception At least one object does have multiple backlinks. mean?

This exception indicates that after the migration has been finished there were still EmbeddedObjects that are used by more than one parent. This is basically the opposite to At least one object does not have a backlink (data would get lost)..
To solve this, you need to duplicate the EmbeddedObject and make sure every parent object has it's own copy to fullfil the 1:1 relationship.

An enhancement for this is planned which will offer an option to automatically create such duplicates. At the moment this has to be done manually by writing a migration.

What does the exception Cannot change table to embedded when using a primary key. mean?

When changing RealmObject to EmbeddedObject you need to make sure that the class does not have a primary key otherwise it cannot be changed to an EmbeddedObject.

Are there performance benefits from splitting a large object into a parent object with multiple properties that are EmbeddedObjects? Regardless of object size, are there performance benefits from using an EmbeddedObject over a normal relationship (RealmObject)? Are cascading deletes cheaper than normal deletes?

To answer this I first want to clarify that there are three options you could look at:

1. all properties directly in the parent class (i.e. Street, House number, City in Person)
2. using RealmObject to extract those properties into a child class (let's say the Address in Person)
3. using EmbeddedObject to extract those properties into a child class (also Address and Person)

In most cases, (1) will be faster than the other two options because everything is in the same place, no relationships needed. So in terms of usage (read/write) this would be a no, there aren't any performance improvements by extracting properties into another class (embedded or not).
The difference between (1) and (2) / (3) is more a structural one (and coding style to some extend). Especially if this new class (Address in our example) is shared with other classes (Person, Company, etc.) you would probably want one Address class instead of repeating Street, City, etc. in every class that needs an address.

The same is true for deletes. Deleting a single object (1) is going to be quicker than deleting relationships with multiple objects. There is, however, a difference between (2) and (3).
Cascading deletes of embedded objects will usually be faster than deleting nested RealmObjects because this is implemented natively in our Core library whereas cascading deletes for RealmObject would have to be implemented by the user at the app level, thus requiring multiple managed->native transitions.

[peppy]

I was reading up on this just last week and have some questions, hopefully this is an okay place to ask.

From the documentation, the main draw seems to be added 1:1 relationship constraints, which I guess was not possible to guarantee until now.

For non-mongodb users, what are the benefits of using EmbeddedObject?

• Are there performance benefits from splitting a large object into a main object with multiple properties that are EmbeddedObjects?
• Regardless of object size, are there performance benefits from using an EmbeddedObject over a normal relationship? Is the cascade deletion cheaper or anything?

It would be beneficial if there was some information on if/how the internal structure differs here, with any advantages or drawbacks.

[DominicFrei]

I was reading up on this just last week and have some questions, hopefully this is an okay place to ask.

Absolutely! I'll add any other questions to the initial post as soon as they are answered so that we end up with a nice overview for everyone clicking into this.

Happy about any question we can get to make everyone's life easier when using EmbeddedObject. 👍

From the documentation, the main draw seems to be added 1:1 relationship constraints, which I guess was not possible to guarantee until now.

Correct. EmbeddedObjects are used to model this type of relationship. The SDK also enforces that which I've just added to the initial post:

This relationship is then enforced by the SDK. Such object do have to have a parent and they cannot have more than one parent. Otherwise you'll get exception like the one's we've explained in more detail further down. This has to be taken care of during the migration.

The documentation expressed their use quite nicely:
An embedded object is a special type of Realm object that models complex data about a specific object.
So whenever you have multiple fields in an object that together can be treated as one an EmbeddedObject is a handy way of modeling it. Think Address (as an EmbeddedObject) instead of house number, street, zip, city (all as unconnected fields in the Person).

Also, if you delete the parent object, the child objects end up in a cascading delete since they can't exist on their own.

For non-mongodb users, what are the benefits of using EmbeddedObject?

* Are there performance benefits from splitting a large object into a main object with multiple properties that are `EmbeddedObject`s?

* Regardless of object size, are there performance benefits from using an `EmbeddedObject` over a normal relationship? Is the cascade deletion cheaper or anything?

It would be beneficial if there was some information on if/how the internal structure differs here, with any advantages or drawbacks.

Totally agree. I will evaluate the questions around performance with our Core team and add the answers as soon as I got them myself. 👍

[DominicFrei]

@peppy I have updated the initial post with your questions. The answers somewhat melted into each other so I decided to have it as one section. Let me know if it needs further clarification or other questions. 👍

[softlion]

Hello ! I just discovered embedded objects, and try to migrate a 1:1 child table to it.
I removed the primary key and inherited from IEmbeddedObject.

The issue is, this child table has leftovers items that were not cascade deleted (app bug), thus has no parent.

How can I delete those items in the migration code ?
I can't in OldRealm, because it's read only.
I can't in NewRealm, because you can't call "RemoveAll" on an IEmbeddedObject, and the DynamicApi don't let you RemoveAll those objects either.
And the migration won't let me migrate because some embedded objects have no parent - of course this is expected.

  //all fails
  migration.NewRealm.RemoveAll(nameof(DbReward)); //Does not compile
  migration.NewRealm.DynamicApi.RemoveAll(nameof(DbReward)); //Can't remove Embedded Objects "The class DbReward represents an embedded object and thus cannot be queried directly"
  migration.OldRealm.DynamicApi.RemoveAll("DbReward"); //OldRealm is read only

So how am I suppose to delete those entries in the migration ?

[nirinchev]

Looks like we didn't expose that config options in the .NET SDK which is an oversight. We'll need to do it.

[softlion]

Ok I will rename the "table" that will delete the old table and create a new embedded object.

[nirinchev]

I have a PR in review that adds automatic handling, so if it's not super urgent for you, you could wait for that one to be released (likely next week).

[Shreedhar73]

@nirinchev Hello,
Is there any way I can Implement the back linking to a field in embedded object ?

[GitMurf]

I was just trying to figure out the same thing!

[nirinchev]

Can you clarify this a little? What's the schema you're trying to build?