Add doc

Author: LiaCastaneda

datafusion/functions-aggregate/src/map_agg.rs

@@ -445,11 +445,10 @@ impl Accumulator for OrderSensitiveMapAggAccumulator {
             vec![take(&mut self.keys).into()];
         let mut partition_orderings: Vec<VecDeque<Vec<ScalarValue>>> =
             vec![take(&mut self.ordering_values).into()];
-        // Values are carried inside the ordering merge by pairing them with keys
-        // through a side table; simpler to merge keys+values together below.
         let mut partition_values: Vec<VecDeque<ScalarValue>> =
             vec![take(&mut self.values).into()];
 
+        // Push keys and values from each partition's state into the merge buffers.
         for row in 0..map_array.len() {
             if map_array.is_null(row) {
                 continue;
@@ -485,7 +484,6 @@ impl Accumulator for OrderSensitiveMapAggAccumulator {
     }
 
     fn state(&mut self) -> Result<Vec<ScalarValue>> {
-        // Ship the de-duplicated map plus ordering values for re-sorting.
         let (keys, values) = self.sorted_deduped()?;
         let map_array = build_single_map(keys, values, &self.key_type, &self.value_type)?;
         Ok(vec![

datafusion/sqllogictest/test_files/map_agg.slt

@@ -60,6 +60,26 @@ SELECT map_agg(k, v) FROM nullkey;
 ----
 {a: 1, c: 3}
 
+# Window usage: a cumulative frame calls evaluate() once per row, so the map
+# grows as the frame expands. Guards against optimizations that consume the
+# accumulator state between evaluate() calls.
+statement ok
+CREATE TABLE win (k VARCHAR, v INT, ts INT) AS VALUES
+  ('a', 1, 10),
+  ('b', 2, 20),
+  ('c', 3, 30);
+
+query ?
+SELECT map_agg(k, v) OVER (ORDER BY ts ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)
+FROM win;
+----
+{a: 1}
+{a: 1, b: 2}
+{a: 1, b: 2, c: 3}
+
+statement ok
+DROP TABLE win;
+
 statement ok
 DROP TABLE kv;
 

docs/source/user-guide/sql/aggregate_functions.md

@@ -91,6 +91,7 @@ SELECT SUM(x) WITHIN GROUP (ORDER BY x) FROM t;
 - [first_value](#first_value)
 - [grouping](#grouping)
 - [last_value](#last_value)
+- [map_agg](#map_agg)
 - [max](#max)
 - [mean](#mean)
 - [median](#median)
@@ -347,6 +348,30 @@ last_value(expression [ORDER BY expression])
 +-----------------------------------------------+
 ```
 
+### `map_agg`
+
+Aggregate key-value pairs from two columns into a single map per group. Pairs with a NULL key are skipped; NULL values are retained. On a duplicate key the first value wins; use ORDER BY to make which value wins deterministic.
+
+```sql
+map_agg(key, value [ORDER BY expression])
+```
+
+#### Arguments
+
+- **key**: The expression to operate on. Can be a constant, column, or function, and any combination of operators.
+- **value**: The expression to operate on. Can be a constant, column, or function, and any combination of operators.
+
+#### Example
+
+```sql
+> SELECT map_agg(name, score) FROM scores GROUP BY department;
++-------------------------------+
+| map_agg(name, score)          |
++-------------------------------+
+| {Alice: 95, Bob: 87}          |
++-------------------------------+
+```
+
 ### `max`
 
 Returns the maximum value in the specified column.