ref<T extends Object> method

Expression<T> ref<T extends Object>(Expression<T> inner)

Makes a column from the subquery available to the outer select statement.

For instance, consider a complex column like subqueryContentLength being added into a subquery:

 final subqueryContentLength = todoEntries.content.length.sum();
 final subquery = Subquery(
   db.selectOnly(todoEntries)
     ..addColumns([todoEntries.category, subqueryContentLength])
     ..groupBy([todoEntries.category]),
   's');

When the subqueryContentLength column gets written, drift will write the actual SUM() expression which is only valid in the subquery itself. When an outer query joining the subqery wants to read the column, it needs to refer to that expression by name. This is what ref is doing:

 final readableLength = subquery.ref(subqueryContentLength);
 final query = selectOnly(categories)
   ..addColumns([categories.id, readableLength])
   ..join([
     innerJoin(subquery,
         subquery.ref(db.todosTable.category).equalsExp(db.categories.id))
   ]);

Here, ref is called two times: Once to obtain a column selected by the outer query and once as a join condition.

ref needs to be used every time a column from a subquery is used in an outer query, regardless of the context.

Implementation

Expression<T> ref<T extends Object>(Expression<T> inner) {
  final name = select._nameForColumn(inner);
  if (name == null) {
    throw ArgumentError(
        'The source select statement does not contain that column');
  }

  return columnsByName[name]!.dartCast();
}