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,BobEach 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=timeorders.csvandevents.tsvstay 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.txtabis a good way to review data you aren't allowed to touch.- Open
orders.csvand a tool may findorders.txtabnext 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.