Controlling How Entity Data Loads

By default, when LightSpeed loads an entity, it loads all the fields of that entity.  This is an efficient strategy because most fields are small and the overhead of loading them is very low compared to the cost of having to go back to the database to load them on demand.

However, some entities contain bulky data which is rarely used.  For example, an employee record might contain a high-resolution security photograph of the employee.  Most uses of an Employee don’t need the high-resolution photograph, so downloading it is a waste of time and bandwidth.  You therefore typically want to mark the Photo field as lazy loaded – that is, to be loaded only when accessed, in a similar way to associations.

Of course, there are probably cases where the Photo field will be required.  For example, if you are working on a screen that prints security passes, you’ll always want the high-resolution photograph.  For situations like these, you want to be able to eager load the field just like a normal entity field.

As with associations, LightSpeed handles these requirements through named aggregates.

To mark a field as lazy loaded, select the field and enter one or more aggregate names in the Aggregates box.  (Unlike associations, you can’t specify that a field is always lazy loaded.  If you never plan to eager load a field, just enter an aggregate name that you never plan to use.)

For hand-coded fields, apply the EagerLoad attribute with the AggregateName property to the field, and implement the wrapper property using the Get method.

public class Employee : Entity<int>
{
  [EagerLoad(AggregateName = "WithSecurityBlobs")]
  private byte[] _securityPhoto;
  public byte[] SecurityPhoto
  {
    get { return Get(ref _securityPhoto); } // MUST use Get method here set { Set(ref _securityPhoto, value); }
  }
}

The marked field will now be loaded only when you access it:

using (IUnitOfWork unitOfWork = _context.CreateUnitOfWork())
{
  var employee = unitOfWork.FindById<Employee>(1); // does not load security photo
  var name = employee.Name; // already loaded, no database query
  var photo = employee.SecurityPhoto; // queries database to load SecurityPhoto column
}

However, if you supply one of the aggregates that the field is part of, using the WithAggregate method or the Query.AggregateName property, then the field will be eager-loaded as if it were a normal field:

using (StaffUnitOfWork unitOfWork = _context.CreateUnitOfWork())
{
  var employee = unitOfWork.Employees.
                             .WithAggregate("WithSecurityBlobs")
                           .Single(e => e.Id == 1); // loads security photo
  var photo = employee.SecurityPhoto; // already loaded, no database query
}

The aggregate name is an attribute of a query, and affects all fields in the aggregate, not just the fields on the starting object.  For example, if Site.Employees is eager loaded or is marked with the “WithSecurityBlobs” aggregate, then loading a Site with the WithSecurityBlobs attribute will load all the employees on that site, including their SecurityPhoto fields.