aggregation

---

title: Aggregation sidebar_position: 1

Aggregation

Part of the function and operator catalog. Every example shown below is executed as an assertion by the engine's own test suite (examples.test.ts), so a result shown here is a result the engine actually produces for that input.

SUM

SUM(values: an array of any value) -> a number

Returns the exact sum of a collection of numbers, skipping null elements. An empty collection, or a collection whose every element is null, has no defined total and is a coded error rather than a silent zero — a zero total from no positions is indistinguishable from a genuine zero total, and that ambiguity must never reach a financial booking.

Examples:

• SUM(input.xs)
  • context: {"xs":[1,2,3.5]}
  • result: "6.5"
• SUM(input.xs)
  • context: {"xs":[5]}
  • result: "5"
• SUM(input.xs)
  • context: {"xs":[1,null,2]}
  • result: "3"
• SUM(input.xs)
  • context: {"xs":[]}
  • fails with EXPR_EMPTY_AGGREGATION
• SUM(input.xs)
  • context: {"xs":[null,null]}
  • fails with EXPR_EMPTY_AGGREGATION

AVG

AVG(values: an array of any value) -> a number

Returns the exact average of a collection of numbers, skipping null elements. Computed as the exact sum divided at the division working scale — never truncated to an integer. An empty collection, or a collection whose every element is null, is a coded error, the same as SUM.

Examples:

• AVG(input.xs)
  • context: {"xs":[1,2,2]}
  • result: "1.66666666666666666667"
• AVG(input.xs)
  • context: {"xs":[4]}
  • result: "4.00000000000000000000"
• AVG(input.xs)
  • context: {"xs":[]}
  • fails with EXPR_EMPTY_AGGREGATION

MIN

MIN(values: an array of any value) -> any value

Returns the smallest element of a collection, skipping null elements, ordered through the one comparator — a mixed collection whose elements are not all the same comparable kind is a coded error rather than an arbitrary answer. Among elements that compare equal, the first in input order is returned, so which scale the result carries is not left to accident. An empty collection, or a collection whose every element is null, is a coded error.

Examples:

• MIN(input.xs)
  • context: {"xs":[3,1,2]}
  • result: "1"
• MIN(input.xs)
  • context: {"xs":[5]}
  • result: "5"
• MIN(ARGS(1.5, 1.50))
  • result: "1.5"
• MIN(ARGS(1.50, 1.5))
  • result: "1.50"
• MIN(input.xs)
  • context: {"xs":["a",1]}
  • fails with EXPR_INCOMPARABLE_ORDERING
• MIN(input.xs)
  • context: {"xs":[]}
  • fails with EXPR_EMPTY_AGGREGATION

MAX

MAX(values: an array of any value) -> any value

Returns the largest element of a collection, skipping null elements, ordered through the one comparator — a mixed collection whose elements are not all the same comparable kind is a coded error rather than an arbitrary answer. Among elements that compare equal, the first in input order is returned. An empty collection, or a collection whose every element is null, is a coded error.

Examples:

• MAX(input.xs)
  • context: {"xs":[3,1,2]}
  • result: "3"
• MAX(input.xs)
  • context: {"xs":[5]}
  • result: "5"
• MAX(ARGS(1.5, 1.50))
  • result: "1.5"
• MAX(ARGS(1.50, 1.5))
  • result: "1.50"
• MAX(input.xs)
  • context: {"xs":["a",1]}
  • fails with EXPR_INCOMPARABLE_ORDERING
• MAX(input.xs)
  • context: {"xs":[]}
  • fails with EXPR_EMPTY_AGGREGATION

COUNT

COUNT(values: an array of any value) -> a number

Returns the number of elements in a collection, at scale zero. Unlike SUM/AVG/MIN/MAX, COUNT counts every element including nulls — a count of nothing is unambiguous, which is why COUNT alone answers zero for an empty collection. Because the result is an integral decimal at scale zero, it is directly usable as an index or slice bound — though a count larger than the representable-integer range still fails loudly there rather than indexing somewhere unintended.

Examples:

• COUNT(input.xs)
  • context: {"xs":[1,2,3]}
  • result: "3"
• COUNT(input.xs)
  • context: {"xs":[]}
  • result: "0"
• COUNT(input.xs)
  • context: {"xs":[1,null,2]}
  • result: "3"