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

guide/aggregates

Aggregates (agg-*)

Here's the quiet superpower. An agg-* line carries a pre-computed statistic for the whole table — one value per column, written like a CSV row so it lines up under the columns it describes:

txtab

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

Column 2 has 98 non-null values, column 3 has 100; column 3 sums to 154,280.50 and averages 1,542.81. Empty slots mean "no aggregate here".

Why it matters: the total is a fact written in the file. Paste the first 50 rows of a million-row table into a chat with a model, or open them in a preview — agg-sum still tells the truth about all the rows. The slice you see can't mislead you about the whole.

The aggregates

Keyword Meaning For
agg-count-nonnull how many values aren't null any column
agg-count-null how many are null any column
agg-count-distinct how many distinct values any column
agg-sum total numbers
agg-avg mean numbers
agg-min / agg-max smallest / largest numbers
agg-len-min / agg-len-max shortest / longest length strings

Nulls sit out, as in SQL. Money in mixed currencies gets no total — the slot stays empty.

The file speaks for its own rows

Aggregates always describe exactly the rows the table declares. If a tool cuts a table down — the first 1,000 rows, a filter — and writes a new file, it recomputes the aggregates for those rows (or drops them) and sets rows= to match. A file never carries totals of some other, bigger dataset.

guide/aggregates.md on GitHub