Add documentation for custom select expressions

docs/content/en/docs/Advanced Features/joins.md

@@ -1,11 +1,14 @@
 ---
-title: "Joins"
+title: "Advanced queries in Dart"
 weight: 1
-description: Use joins to write queries that read from more than one table
+description: Use sql joins or custom expressions from the Dart api
+url: /docs/advanced-features/joins
 aliases:
  - /queries/joins
 ---
 
+## Joins
+
 Moor supports sql joins to write queries that operate on more than one table. To use that feature, start
 a select regular select statement with `select(table)` and then add a list of joins using `.join()`. For
 inner and left outer joins, a `ON` expression needs to be specified. Here's an example using the tables
@@ -49,7 +52,37 @@ return query.watch().map((rows) {
 ```
 
 _Note_: `readTable` returns `null` when an entity is not present in the row. For instance, todo entries
-might not be in any category. If we a row without a category, `row.readTable(categories)` would return `null`.
+might not be in any category.For a row without a category, `row.readTable(categories)` would return `null`.
+
+## Custom expressions
+
+Select statements aren't limited to columns from tables. You can also include more complex expressions in the
+query. For each row in the result, those expressions will be evaluated by the database engine.
+
+```dart
+class EntryWithImportance {
+  final TodoEntry entry;
+  final bool important;
+
+  EntryWithImportance(this.entry, this.important);
+}
+
+Future<List<EntryWithImportance>> loadEntries() {
+  // assume that an entry is important if it has the string "important" somewhere in its content
+  final isImportant = todos.content.like('%important%');
+
+  return select(todos).addColumns([isImportant]).map((row) {
+    final entry = row.readTable(todos);
+    final entryIsImportant = row.read(isImportant);
+    
+    return EntryWithImportance(entry, entryIsImportant);
+  }).get();
+}
+```
+
+Note that the `like` check is _not_ performed in Dart - it's sent to the underlying database engine which
+can efficiently compute it for all rows.
+
 ## Aliases
 Sometimes, a query references a table more than once. Consider the following example to store saved routes for a
 navigation system:

docs/content/en/docs/Getting started/writing_queries.md

@@ -71,6 +71,8 @@ If an entry with the provided id exists, it will be sent to the stream. Otherwis
 more than one entry (which is impossible in this case), an error will be added
 instead.
 
+If you need more complex queries with joins or custom columns, see [this site]({{< relref "../Advanced Features/joins.md" >}}).
+
 ## Updates and deletes
 You can use the generated classes to update individual fields of any row:
 ```dart

moor/CHANGELOG.md

@@ -1,3 +1,15 @@
+## unreleased
+
+- Support custom expressions from selects in the Dart API:
+  ```dart
+  final currentBalance = accounts.income - accounts.expenses;
+  select(accounts).addColumns([currentBalance]).map((row) {
+    Account account = row.readTable(accounts);
+    int balanceOfAccount = row.read(currentBalance);
+    return ...
+  }).get();
+  ```
+
 ## 2.1.0
 
 - New extension methods to simplify the Dart api!