@@ -44,6 +44,22 @@ groupBy (toColumns -> exprs) = fromColumns $ htabulate $ \field ->
4444 dicts = hdicts @(Columns exprs) @(ConstrainDBType DBEq)
4545
4646
47+-- | Aggregate rows into a single row containing an array of all aggregated
48+-- rows. This can be used to associate multiple rows with a single row, without
49+-- changing the over cardinality of the query. This allows you to essentially
50+-- return a tree-like structure from queries.
51+--
52+-- For example, if we have a table of orders and each orders contains multiple
53+-- items, we could aggregate the table of orders, pairing each order with its
54+-- items:
55+--
56+-- @
57+-- ordersWithItems :: Query (Order Expr, ListTable (Item Expr))
58+-- ordersWithItems = do
59+-- order <- each orderSchema
60+-- items <- aggregate $ listAgg <$> itemsFromOrder order
61+-- return (order, items)
62+-- @
4763listAgg :: Table DB exprs => exprs -> Aggregate (ListTable exprs)
4864listAgg (toColumns -> exprs) = fromColumns $
4965 hvectorize
@@ -51,6 +67,7 @@ listAgg (toColumns -> exprs) = fromColumns $
5167 (pure exprs)
5268
5369
70+-- | Like 'listAgg', but the result is guaranteed to be a non-empty list.
5471nonEmptyAgg :: Table DB exprs => exprs -> Aggregate (NonEmptyTable exprs)
5572nonEmptyAgg (toColumns -> exprs) = fromColumns $
5673 hvectorize