@@ -266,11 +266,39 @@ impl LambdaArgument {
266266 /// so they align with the evaluation batch. Captures are snapshotted from the
267267 /// outer batch at construction time, giving one value per outer row, but the
268268 /// function may evaluate the lambda body over a batch with a different number
269- /// of rows. It is the function responsibility to provide the appropriate `spread_captures`
270- /// closure to expand (or otherwise reshape) the captures to match.
271- /// Function working on lists, for example `array_transform(arr, v -> v + 1)`
272- /// flattens all list elements into a single batch, duplicating captured
273- /// values for rows with multiple elements and dropping them for empty lists.
269+ /// of rows. It is the function's responsibility to provide the appropriate
270+ /// `spread_captures` closure to expand (or otherwise reshape) the captures
271+ /// to match.
272+ ///
273+ /// Taking as an example the following table:
274+ ///
275+ /// ```sql
276+ /// CREATE TABLE t (arr INT[], a INT) AS VALUES
277+ /// ([1, 2, 3], 10),
278+ /// ([], 20),
279+ /// ([4], 30);
280+ /// ```
281+ ///
282+ /// `SELECT array_transform(arr, v -> v + a) from t` would execute over three outer rows:
283+ ///
284+ /// ```text
285+ /// arr (ListArray): [[1, 2, 3], [], [4]] -- 3 outer rows, 4 total elements
286+ /// a (captured): [10, 20, 30] -- one value per outer row
287+ /// ```
288+ ///
289+ /// `array_transform` flattens the list elements into a single batch of 4 rows,
290+ /// so `spread_captures` must repeat/drop captured values to match:
291+ ///
292+ /// ```text
293+ /// v (flattened args): [1, 2, 3, 4]
294+ /// a (spread): [10, 10, 10, 30] -- 10 repeated for 3 elements in row 0,
295+ /// -- 20 dropped for the empty sublist in row 1,
296+ /// -- 30 once for the single element in row 2
297+ /// ```
298+ ///
299+ /// The lambda body `v + a` then evaluates element-wise over these 4-row arrays,
300+ /// producing `[11, 12, 13, 34]`, which `array_transform` reassembles into `[[11, 12, 13], [], [34]]`.
301+ ///
274302 /// If the lambda has no captures, `spread_captures` is never called.
275303 pub fn evaluate (
276304 & self ,
0 commit comments