withReferences method

ProcessedTableManager<_$FaceDatabase, $FaceEmbeddingsTable, FaceEmbedding, $$FaceEmbeddingsTableFilterComposer, $$FaceEmbeddingsTableOrderingComposer, $$FaceEmbeddingsTableAnnotationComposer, $$FaceEmbeddingsTableCreateCompanionBuilder, $$FaceEmbeddingsTableUpdateCompanionBuilder, (FaceEmbedding, BaseReferences<_$FaceDatabase, $FaceEmbeddingsTable, FaceEmbedding>), (FaceEmbedding, BaseReferences<_$FaceDatabase, $FaceEmbeddingsTable, FaceEmbedding>), PrefetchHooks Function()> withReferences([
  1. PrefetchHooks prefetch(
    1. PrefetchHooks prefetch()
    )?
])
inherited

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),
  );
}