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

guide/tables

Tables

Every table starts with a table line — even when the file has only one.

txtab

# table name=orders rows=1200
Key What it says
rows How many data rows (not counting the header row). Always there.
header 1 if the data starts with a header row (the default), 0 if it doesn't
name A name, unique in the file. Optional — but other tables can only point at a named table.
columns How many physical columns, if you want it checked
reference Where the data is when it isn't in this file
storage rows (the default) or columns — see Archives
data-size Roughly how many bytes the data takes unpacked, for planning
delim, quote, null, encoding This table's own dialect, overriding the first line

Several tables in one file

txtab

# texttables=0.1 delim=comma tables=2
# table name=orders rows=2
# column name=id type=long role=id
# column name=customer_id type=long references=customers.id
id,customer_id
1001,7
1002,8
# table name=customers rows=2
# column name=id type=long role=id
id,name
7,Ann
8,Bob

Each table is read by its row count, then the next table line begins. tables=2 on the first line makes sure none went missing.

Data next door: reference=

Often the data already exists as CSV files you shouldn't — or can't — edit: a vendor dump, a regulated export, anything someone checks a hash of. Describe them from outside:

txtab

# texttables=0.1 tables=2
# meta-source nightly vendor dump
# table name=orders reference=orders.csv rows=48213 delim=comma encoding=windows-1251
# column name=id type=long role=id
# column name=amount type=decimal unit=EUR role=measure agg=sum
# table name=events reference=events.tsv rows=1200 delim=tab
# column name=ts type=datetime role=time
  • orders.csv and events.tsv stay byte-for-byte as they are — ordinary CSV and TSV.
  • Each table brings its own dialect: comma or tab, encoding, header row.
  • rows, aggregates and notes describe the referenced file. A note in the .txtab is a good way to review data you aren't allowed to touch.
  • Open orders.csv and a tool may find orders.txtab next to it automatically.
  • Mix freely: big tables in CSV files next door, a small lookup table right in the .txtab.

data-size

Roughly how many bytes the table's data takes on disk once unpacked: the rows in this file, the referenced CSV, or the .col files. Useful for deciding how to read a table before reading it. Nobody checks it.

guide/tables.md on GitHub