Embedded Relationships and Manual References

When to Embed Documents

Use embedded documents when the related data is usually viewed in the context of its parent and when the embedded data remains reasonably bounded in size. This includes small sets of child values, such as addresses, settings, or a limited list of recent items. When you embed documents, MongoDB Server can improve performance by retrieving related data in a single database operation, and by updating related data atomically within a single document.

Consider embedding data in the following cases:

• Your application usually reads parent and child data together. Fetching everything in one query is more efficient than making separate calls.

• The related data doesn't grow without a clear upper bound. Bounded data won't cause documents to grow indefinitely or hit MongoDB's 16MB document size limit.

• The related data doesn't change often and independently of the parent. This incurs less overhead from rewriting the parent document.

To learn more, see Embedded Data in the MongoDB Server documentation.

How to Embed Documents

You can designate an owned entity in the following ways:

• [Owned] Attribute: Apply the [Owned] data annotation attribute to the model class for the subdocument. This approach is declarative and concise, but also less flexible, because it applies globally to all usages of the owned type.

• Fluent API: Call the OwnsOne() or OwnsMany() methods in your DbContext configuration. This approach offers more control and flexibility, allowing you to configure the relationship differently for specific entities without modifying the model class.

The following sections provide examples of these approaches for modeling single and multiple owned entities.

[Owned]
public class Address
{
    public string Street { get; set; } = null!;
    public string City { get; set; } = null!;
    public string Country { get; set; } = null!;
}
public class Customer
{
    public ObjectId Id { get; set; }
    public string Name { get; set; } = null!;
    public Address Address { get; set; } = null!;
}

public class CustomerDbContext : DbContext
{
    public DbSet<Customer> Customers { get; set; } = null!;
    public CustomerDbContext(DbContextOptions options) : base(options) { }
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        modelBuilder.Entity<Customer>(c =>
        {
            c.OwnsOne(c => c.Address);
            c.ToCollection("customers");
        });
    }
}

{
  "_id": ObjectId("..."),
  "Name": "John Doe",
  "Address": {
    "Street": "123 Main St",
    "City": "New York",
    "Country": "USA"
  }
}

[Owned]
public class Order
{
    public string Product { get; set; } = null!;
    public int Quantity { get; set; }
}
public class CustomerWithOrders
{
    public ObjectId Id { get; set; }
    public string Name { get; set; } = null!;
    public List<Order> Orders { get; set; } = new();
}

public class OrderDbContext : DbContext
{
    public DbSet<CustomerWithOrders> Customers { get; set; } = null!;
    public OrderDbContext(DbContextOptions options) : base(options) { }
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);
        modelBuilder.Entity<CustomerWithOrders>(c =>
        {
            c.OwnsMany(c => c.Orders);
            c.ToCollection("customers");
        });
    }
}

{
  "_id": ObjectId("..."),
  "Name": "Jane Smith",
  "Orders": [
    { "Product": "Laptop", "Quantity": 1 },
    { "Product": "Mouse", "Quantity": 2 }
  ]
}

When to Use References

Use references when you regularly query the related data independent of its parent, when the child set can grow very large, or when the related data changes frequently.

Consider using references in the following cases:

• The related data grows without a clear upper bound. Unbounded arrays can cause performance issues and might reach MongoDB's 16MB document size limit.

• You need to query the related entity on its own. You can query and index the child collection directly without scanning parent documents.

• The related data changes often and independently of the parent. Frequent updates to embedded data require rewriting the entire parent document each time, which is inefficient.

• The application doesn't usually read parent and child data together. By using references, you avoid fetching child data that you don't need.

• The relationship is many-to-many or otherwise complex.

• Duplicating the data would create too much update overhead.

To learn more, see Reference Data in the MongoDB Server documentation.

How to Use References

The following example shows how to store a reference to a related entity:

public class Author
{
    public ObjectId Id { get; set; }
    public string Name { get; set; } = null!;
}
public class Book
{
    public ObjectId Id { get; set; }
    public string Title { get; set; } = null!;
    // Store reference to Author by storing the Author's Id
    public ObjectId AuthorId { get; set; }
}

To retrieve the related entity, you must query the referenced collection separately, as shown in the following example:

// Query a book and its author
var book = db.Books.FirstOrDefault(b => b.Title == "My Book");
var author = db.Authors.FirstOrDefault(a => a.Id == book!.AuthorId);

API Documentation

To learn more about the methods and types discussed in this guide, see the following Microsoft API documentation:

• [Owned]

• OwnsOne()

• OwnsMany()