From e433cff932f82c97ecc365a4ec5e456b0b68f236 Mon Sep 17 00:00:00 2001 From: Simon Binder Date: Mon, 24 Jul 2023 21:10:04 +0200 Subject: [PATCH] Update docs for nested columns --- .../docs/Advanced Features/custom_row_classes.md | 11 +++++++---- docs/pages/docs/Using SQL/drift_files.md | 10 ++++------ drift_dev/CHANGELOG.md | 6 ++++++ 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/pages/docs/Advanced Features/custom_row_classes.md b/docs/pages/docs/Advanced Features/custom_row_classes.md index 02f07b99..51e989ad 100644 --- a/docs/pages/docs/Advanced Features/custom_row_classes.md +++ b/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`. 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`. 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); } diff --git a/docs/pages/docs/Using SQL/drift_files.md b/docs/pages/docs/Using SQL/drift_files.md index d9a44b0f..b6d67d7b 100644 --- a/docs/pages/docs/Using SQL/drift_files.md +++ b/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 diff --git a/drift_dev/CHANGELOG.md b/drift_dev/CHANGELOG.md index 642d253b..26bbd10c 100644 --- a/drift_dev/CHANGELOG.md +++ b/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.