withReferences method

ProcessedTableManager<$Database, $Table, $Dataclass, $FilterComposer, $OrderingComposer, $ComputedFieldComposer, $CreateCompanionCallback, $UpdateCompanionCallback, $DataclassWithReferences, $DataclassWithReferences, $CreatePrefetchHooksCallback> withReferences([ PrefetchHooks prefetch($CreatePrefetchHooksCallback prefetch)? ])

This function with return a new manager which will return each item in the database with its references

The references are returned as a prefiltered manager, which will only return the items which are related to the item

For example:

for (final (group,refs) in await groups.withReferences().get()) {
  final usersInGroup = await refs.users.get();
  /// Is identical to:
  final usersInGroup = await users.filter((f) => f.group.id(group.id)).get();
}

Prefetching

The keen among you may notice that the above code is extremely inefficient, as it will run a query for each group to get the users in that group. This could mean hundreds of queries for a single page of data, grinding your application to a halt.

The solution to this is to use prefetching, which will run a single query to get all the data you need.

For example:

for (final (group,refs) in await groups.withReferences((prefetch) => prefetch(users: true)).get()) {
  final usersInGroup = refs.users.prefetchedData;
}

Note that prefetchedData will be null if the reference was not prefetched.

Implementation

ProcessedTableManager<
        $Database,
        $Table,
        $Dataclass,
        $FilterComposer,
        $OrderingComposer,
        $ComputedFieldComposer,
        $CreateCompanionCallback,
        $UpdateCompanionCallback,
        $DataclassWithReferences,
        $DataclassWithReferences,
        $CreatePrefetchHooksCallback>
    withReferences(
        [final PrefetchHooks Function($CreatePrefetchHooksCallback prefetch)?
            prefetch]) {
  // Build the prefetch hooks based on the user's input
  final prefetchHooks = ($state._prefetchHooksCallback != null)
      ? prefetch?.call($state._prefetchHooksCallback!)
      : null;

  // Return a new manager which is configured to return a
  // `$DataclassWithReferences` instead of a `$Dataclass`
  return ProcessedTableManager($state
      .copyWithActiveDataclass()
      .copyWith(prefetchHooks: prefetchHooks));
}