Embedded Relationships

Tip

If you are going to store more than a handful of entities within another entity, it is best to store them by reference as described in this page.

One-to-one

var author = new Author { Name = "Eckhart Tolle" };
await db.SaveAsync(author);

book.Author = author;
await db.SaveAsync(book);

As mentioned earlier, calling SaveAsync() persists author to the "Authors" collection in the database. It is also stored in book.Author property. So, the author entity now lives in two locations (in the collection and also inside the book entity) and will have the same ID. If the goal is to embed something as an independent document, it is best to use a class that does not inherit from the Entity class or simply use the .ToDocument() method of an entity as explained earlier.

Embed removal

To remove the embedded author, simply do:

book.Author = null!;
await db.SaveAsync(book);

The original author in the Authors collection is unaffected.

One-to-many

book.OtherAuthors = [author1, author2];
await db.SaveAsync(book);

Embed removal:

book.OtherAuthors = null!;
await db.SaveAsync(book);

The original author1, author2 entities in the Authors collection are unaffected.