Update docs for nested columns

docs/pages/docs/Advanced Features/custom_row_classes.md

@@ -181,8 +181,9 @@ fields in existing types as well.
 
 Depending on what kind of result set your query has, you can use different fields for the existing Dart class:
 
-1. For a nested table selected with `**`, your field needs to store an instance of the table's row class.
- This is true for both drift-generated row classes and tables with existing, user-defined row classes.
+1. For a nested table selected with `**`, your field needs to store a structure compatible with the result set
+ the nested column points to. For `my_table.**`, that field could either be the generated row class for `MyTable`
+ or a custom class as described by rule 3.
 2. For nested list results, you have to use a `List<T>`. The `T` has to be compatible with the inner result
  set of the `LIST()` as described by these rules.
 3. For a single-table result, you can use the table class, regardless of whether the table uses an existing table
@@ -221,8 +222,8 @@ class EmployeeWithStaff {
 }
 ```
 
-As `self` is a `**` column, rule 1 applies. Therefore, `T1` must be `Employee`, the row class for the
-`employees` table.
+As `self` is a `**` column, rule 1 applies. `self` references a table, `employees`.
+By rule 3, this means that `T1` can be a `Employee`, the row class for the `employees` table.
 On the other hand, `staff` is a `LIST()` column and rule 2 applies here. This means that `T3` must
 be a `List<Something>`.
 The inner result set of the `LIST` references all columns of `employees` and nothing more, so rule
@@ -235,6 +236,8 @@ class IdAndName {
  final int id;
  final String name;
 
+ // This class can be used since id and name column are available from the list query.
+ // We could have also used the `Employee` class or a record like `(int, String)`.
  IdAndName(this.id, this.name);
 }
 

docs/pages/docs/Using SQL/drift_files.md

@@ -228,12 +228,10 @@ class RoutesWithNestedPointsResult {
 Great! This class matches our intent much better than the flat result class
 from before.
 
-At the moment, there are some limitations with this approach:
-
-- `**` is not yet supported in compound select statements
-- you can only use `table.**` if table is an actual table or a reference to it.
- In particular, it doesn't work for result sets from `WITH` clauses or table-
- valued functions.
+These nested result columns (`**`) can appear in top-level select statements
+only, they're not supported in compound select statements or subqueries yet.
+However, they can refer to any result set in SQL that has been joined to the
+select statement - including subqueries table-valued functions.
 
 You might be wondering how `**` works under the hood, since it's not valid sql.
 At build time, drift's generator will transform `**` into a list of all columns

drift_dev/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.11.0
+
+- [Nested result columns](https://drift.simonbinder.eu/docs/using-sql/drift_files/#nested-results)
+ in drift files can now refer to any result set (e.g. a table-valued function or a subquery).
+ They were restricted to direct table references before.
+
 ## 2.10.0
 
 - Add the `schema steps` command to generate help in writing step-by-step schema migrations.