spec/aggregates
Aggregates (agg-*)
txtab
P agg-count-nonnull ,98,100
P agg-sum ,,154280.50
P agg-avg ,,1542.81Syntax
- The keyword is
agg-<name>, where<name>is a standard aggregate (below). - The payload is one record in the table's effective dialect (
delim,quote), one value per physical column (stored and materialized; virtual computed columns have no slot). - Fewer values than columns: the trailing columns have no aggregate. More values:
agg-arity-mismatch(WARN). - An empty value means "not applicable" or "not computed".
- Order of
agg-*lines does not matter. One line per name per table; a repeat: last wins (agg-duplicate, WARN). agg-*belongs in a table block (agg-in-file-block, FAIL).- An unknown
<name>isagg-unknown(WARN, ignored).
Standard aggregates
| Keyword | Applies to | Meaning |
|---|---|---|
agg-count-nonnull |
any type | Number of non-null values |
agg-count-null |
any type | Number of null values |
agg-count-distinct |
any type | Number of distinct non-null values |
agg-sum |
numeric | Sum |
agg-avg |
numeric | Arithmetic mean |
agg-min |
numeric | Minimum |
agg-max |
numeric | Maximum |
agg-len-min |
string |
Length of the shortest value |
agg-len-max |
string |
Length of the longest value |
Numeric types: int, long, float, double, decimal. Implementations SHOULD check that an aggregate fits the column type and MAY ignore a mismatch with a warning (agg-type-mismatch, WARN).
Nulls follow SQL: excluded from sum, avg, min, max, len-min, len-max and count-distinct; count-nonnull and count-null count what their names say. Money columns in different currencies (unit=@<column>) have no meaningful single agg-sum; writers SHOULD leave it empty.
What aggregates describe
agg-*describe all rows of the table: therowsrecords of its data — inline, in thereference=file, or in its.colfiles. A file asserts its own data; there is no other "source" dataset behind it.- A reader that has seen only part of the rows (the first N lines, a preview) MUST treat
agg-*androws=as authoritative over values it recomputes from the rows it saw. It knows it read a slice. - A writer that changes the set of rows — slice, filter, append, delete — MUST recompute the affected
agg-*lines or drop them, and MUST setrows=to the new count. Keeping the original aggregates with a newrows=is not allowed. - A validator that recomputes an aggregate and gets a different value reports
agg-mismatch(WARN, never escalated: floating-point and decimal rounding make exact comparison unreliable).