join<T extends ManagedObject> abstract method Null safety

Configures this instance to fetch a relationship property identified by object or set.

By default, objects returned by Query.fetch do not have their relationship properties populated. (In other words, ManagedObject and ManagedSet properties are null.) This method configures this instance to conduct a SQL join, allowing it to fetch relationship properties for the returned instances.

Consider a ManagedObject subclass with the following relationship properties as an example:

    class User extends ManagedObject<_User> implements _User {}
    class _User {
      Profile profile;
      ManagedSet<Note> notes;
    }

To fetch an object and one of its has-one properties, use the object closure:

    var query = Query<User>()
      ..join(object: (u) => u.profile);

To fetch an object and its has-many properties, use the set closure:

    var query = Query<User>()
      ..join(set: (u) => u.notes);

Both object and set are passed an empty instance of the type being queried. object must return a has-one property (a ManagedObject subclass) of the object it is passed. set must return a has-many property (a ManagedSet) of the object it is passed.

Multiple relationship properties can be included by invoking this method multiple times with different properties, e.g.:

    var query = Query<User>()
      ..join(object: (u) => u.profile)
      ..join(set: (u) => u.notes);

This method also returns a new instance of Query, where InstanceType is is the type of the relationship property. This can be used to configure which properties are returned for the related objects and to filter a ManagedSet relationship property. For example:

    var query = Query<User>();
    var subquery = query.join(set: (u) => u.notes)
      ..where.dateCreatedAt = whereGreaterThan(someDate);

This mechanism only works on fetch and fetchOne execution methods. You must not execute a subquery created by this method.