[0.1 draft] [guide 15 · spec 15 pages]

spec/aggregates

Aggregates (agg-*)

txtab

P agg-count-nonnull ,98,100
P agg-sum ,,154280.50
P agg-avg ,,1542.81

Syntax

  • 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> is agg-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: the rows records of its data — inline, in the reference= file, or in its .col files. 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-* and rows= 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 set rows= to the new count. Keeping the original aggregates with a new rows= 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).

spec/aggregates.md on GitHub