Merge window-functions into develop

Author: simolus3

docs/docs/dart_api/expressions.md

@@ -146,7 +146,7 @@ Support for common JSON operators is provided through `package:drift/extensions/
 This provides things like `jsonExtract` to extract fields from JSON or `jsonEach` to query
 nested JSON structures. For more details, see the [JSON support](select.md#json-support) section on the page about selects or [this more complex example](../Examples/relationships.md#with-json-functions).
 
-## Aggregate functions (like count and sum) 
+## Aggregate functions (like count and sum)
 
 [Aggregate functions](https://www.sqlite.org/lang_aggfunc.html) are available
 from the Dart api. Unlike regular functions, aggregate functions operate on multiple rows at
@@ -225,6 +225,21 @@ Stream<String> allTodoContent() {
 The separator defaults to a comma without surrounding whitespace, but it can be changed
 with the `separator` argument on `groupConcat`.
 
+### Window functions
+
+In addition to aggregate expressions and `groupBy`, drift supports [window functions](https://en.wikipedia.org/wiki/Window_function_(SQL)).
+Unlike regular aggregates, which collapse a group of rows into a single value, window functions allow
+running aggregations over a subset of rows related to the current one.
+For instance, you could use this to track a running total of values:
+
+{{ load_snippet('window','lib/snippets/dart_api/expressions.dart.excerpt.json') }}
+
+An interesting use for window function is to determine the rank a row would have if rows were
+sorted by some column (without actually returning all rows, or sorting them by that column).
+This ranking can be attached to each row:
+
+{{ load_snippet('window2','lib/snippets/dart_api/expressions.dart.excerpt.json') }}
+
 ## Mathematical functions and regexp
 
 When using a `NativeDatabase`, a basic set of trigonometric functions will be available.

docs/lib/snippets/dart_api/expressions.dart

@@ -34,6 +34,40 @@ extension Snippets on CanUseCommonTables {
     await update(todoItems).write(change);
   }
   // #enddocregion date3
+
+  // #docregion window
+  /// Returns all todo items, associating each item with the total length of all
+  /// titles up until (and including) each todo item.
+  Selectable<(TodoItem, int)> todosWithRunningLength() {
+    final runningTitleLength = WindowFunctionExpression(
+      todoItems.title.length.sum(),
+      orderBy: [OrderingTerm.asc(todoItems.id)],
+    );
+    final query = select(todoItems).addColumns([runningTitleLength]);
+    query.orderBy([OrderingTerm.asc(todoItems.id)]);
+
+    return query.map((row) {
+      return (row.readTable(todoItems)!, row.read(runningTitleLength)!);
+    });
+  }
+  // #enddocregion window
+
+  // #docregion window2
+  /// Returns all todo items, also reporting the index (counting from 1) each
+  /// todo item would have if all items were sorted by descending content
+  /// length.
+  Selectable<(TodoItem, int)> todosWithLengthRanking() {
+    final lengthRanking = WindowFunctionExpression(
+      todoItems.id.count(),
+      orderBy: [OrderingTerm.desc(todoItems.content.length)],
+    );
+    final query = select(todoItems).addColumns([lengthRanking]);
+
+    return query.map((row) {
+      return (row.readTable(todoItems)!, row.read(lengthRanking)!);
+    });
+  }
+  // #enddocregion window2
 }
 
 // #docregion bitwise

drift/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.26.0-dev
+
+- Add support for window functions with `WindowFunctionExpression`.
+
 ## 2.25.1
 
 - Fix shared worker feature detection when the main app is compiled with