guide/columns
Columns (column)
This is where guessing ends. One column line per column tells anyone — a person or a tool — what it holds: the type, the unit, the allowed values, what the column is for.
txtab
# column name=id type=long unique=1
# column name=email type=string len-max=254 example=ann@example.com
# column name=amount type=decimal format=0.00 unit=USDColumns are optional. Describe the three that matter and skip the rest. With a header row, a column is matched to its header cell by name (or title), so the order of column lines doesn't matter. Without a header row, use index= (counting from zero).
name is a plain identifier — Latin letters, digits and underscores (customer_id), the kind every database accepts without quotes. Whatever the header actually says goes into title:
txtab
# column name=amount title="Сумма (руб.)" type=decimal unit=RUB
Сумма (руб.)
1500.00Type and format
| Type | What it is |
|---|---|
string |
Text |
int / long |
32- / 64-bit integer |
float / double |
32- / 64-bit floating point |
decimal |
Exact decimal — money, no float rounding |
boolean |
true/false (also 1/0) |
date / time / datetime |
ISO 8601 |
uuid |
A UUID |
binary |
Base64 bytes |
format= is a display hint (format=0.00). example= shows what a value looks like — useful when the data isn't in the file. Make it up; don't copy a real customer's email into the metadata.
Units and money
| You write | It means |
|---|---|
unit=kg, unit=ms, unit=% |
A unit of measurement |
unit=USD |
Money, in US dollars — any ISO 4217 code in capitals |
unit=EUR/kg |
Euros per kilogram |
unit=@cur |
The unit is in column cur, row by row |
The last one is for tables where every row can have its own currency:
txtab
# column name=amount type=decimal unit=@cur role=measure agg=sum
# column name=cur type=string
amount,cur
12.50,EUR
99.00,USDTools never add euros to dollars: they group by cur first. And a table total over mixed currencies is left empty, because there isn't one.
Allowed values
| Attribute | Meaning |
|---|---|
enum |
A closed set: enum=pending|completed|cancelled |
pattern |
A regex the values match |
min / max |
Bounds for numbers and dates |
len-min / len-max |
Bounds for string length |
required |
1 — never null |
unique |
1 — values are meant to be unique |
default |
The default a database would use — never filled in when reading |
An empty cell reads as null, always — even with default=. The file describes the data as it is.
What a column is for: role and agg
txtab
# column name=order_id type=long role=id
# column name=status type=string role=dimension
# column name=amount type=decimal role=measure agg=sum
# column name=balance type=decimal role=measure agg=avg
# column name=created_at type=datetime role=timerole |
What you do with it |
|---|---|
id |
count, join — never sum |
dimension |
group by, filter |
measure |
sum, average, min, max |
time |
group by period, trend |
agg says how a measure combines: sum for revenue, avg for a balance (never sum balances across months), min/max for highs and lows, none for ratios. A measure without agg sums.
Relations: references
txtab
# table name=orders rows=1200
# column name=customer_id type=long references=customers.idcustomer_id points at id in the customers table of the same file — which may come later in the file. It's a map of how tables connect, not a check: nobody validates the values. For keys made of several columns, write the FOREIGN KEY in SQL.
Computed columns
txtab
# column name=price type=decimal
# column name=quantity type=int
# column name=total type=decimal formula="price * quantity"total isn't stored anywhere — it has no header cell and no field in any row. A tool computes it on demand from price and quantity. Ask a tool to materialize it and the values are written into the data as an ordinary column (materialized=1); dematerialize it to drop them again. The formula stays either way.
Formulas use a small portable language — arithmetic, comparisons, case when, and functions like concat, coalesce, round — so every tool can evaluate them. Anything fancier belongs in a database's generated column, written in SQL.
Everything else
title and description for people, order=asc|desc if the data is sorted, separator= for cells holding several values, link= to make values clickable (Notes and links). Your own attributes start with x-.