Eager, Lazy and Explicit Loading

A navigation property is the property that points from one entity to another: an Order has a Customer, a Customer has a list of Orders, a Department has a list of Employees. The database stores a foreign key column; your model gives you an object to walk to.

This lesson is about when that related object arrives. EF Core does not guess. You choose, and each choice sends a different number of queries and a different volume of data across the connection.

There are three ways to do it, and the differences between them are the whole subject.

List<Order> orders = await context.Orders
    .Where(o => o.OrderDate >= from)
    .Include(o => o.Customer)
    .Include(o => o.Items)
        .ThenInclude(i => i.Product)
    .ToListAsync();

foreach (Order order in orders)
{
    // Already in memory. This loop touches the database zero times.
    Console.WriteLine(order.Customer.Name);

    foreach (OrderItem item in order.Items)
    {
        Console.WriteLine(item.Product.Name);
    }
}

• Include names a navigation property to bring back with the main query. It reads like part of the query because that is what it becomes: a join.
• ThenInclude continues from the previous Include. Items are order items, and Product hangs off each item, so reaching it needs the second step.
• Include only applies to a query that returns entities. Once you project to a different shape with Select, Include no longer has anything to attach to. The next lesson covers that.
• The loop is the payoff. With the data already loaded, property access is property access and nothing else.

SELECT [o].[Id], [o].[OrderDate], [o].[Status],
       [c].[Id], [c].[Name], [c].[Email],
       [i].[Id], [i].[OrderId], [i].[ProductId], [i].[Quantity], [i].[UnitPrice],
       [p].[Id], [p].[Name], [p].[Sku]
FROM [Orders] AS [o]
INNER JOIN [Customers] AS [c] ON [o].[CustomerId] = [c].[Id]
LEFT JOIN [OrderItems] AS [i] ON [o].[Id] = [i].[OrderId]
LEFT JOIN [Products] AS [p] ON [i].[ProductId] = [p].[Id]
WHERE [o].[OrderDate] >= @__from_0
ORDER BY [o].[Id], [c].[Id], [i].[Id];

• One query, which is the point of eager loading. Now look at what the row shape costs: an order with twelve items comes back as twelve rows, and every one of those rows repeats the order columns and the customer columns.
• EF Core removes the duplication when it builds the objects, so you receive one Order holding twelve Items. The duplication happened on the network, not in your code, which is exactly why it is easy to miss.
• The ORDER BY is not for your benefit. EF Core needs rows belonging to the same parent grouped together so it can assemble the object graph in one pass.
• Run your own query and read your own log. Provider and version change this text.

// --- Lazy loading: configured once, then invisible at the call site ---
// Needs the Microsoft.EntityFrameworkCore.Proxies package, and every
// navigation property must be virtual so the generated proxy can override it.
options.UseLazyLoadingProxies();

public class Order
{
    public int Id { get; set; }
    public int CustomerId { get; set; }
    public virtual Customer Customer { get; set; } = null!;
    public virtual ICollection<OrderItem> Items { get; set; } = new List<OrderItem>();
}

// --- Explicit loading: the same round trip, written down ---
Order order = await context.Orders.FirstAsync(o => o.Id == orderId);

await context.Entry(order).Reference(o => o.Customer).LoadAsync();
await context.Entry(order).Collection(o => o.Items).LoadAsync();

// Explicit loading can also load part of a collection
await context.Entry(order).Collection(o => o.Items)
    .Query()
    .Where(i => i.Quantity > 1)
    .LoadAsync();

• With proxies enabled, reading order.Customer sends a query the first time it happens. Nothing at the call site indicates that, which is both the appeal and the problem.
• Explicit loading does the same work with the cost on the page. Entry(order) returns EF Core's tracking entry for that object, Reference is for a single related entity, and Collection is for a list.
• Query() on a collection gives you a queryable for the related rows, so you can filter before loading instead of pulling the whole collection into memory.
• Explicit loading needs the entity to be tracked. It will not work on a result from a no-tracking query, because there is no entry to ask.