spec/example
Full example
One file that uses most of the vocabulary: two tables, file and table metadata, column schema with units, money, a computed column, a relation, aggregates, SQL in both sections, notes, links and a chart.
txtab
# texttables=0.1 delim=comma quote=double tables=2
# meta-source shop_db
# meta-as-of 2026-11-01
# meta-exported 2026-11-03T09:00:00Z
# meta-license CC-BY-4.0
# note text="November snapshot; refunds are processed separately"
# -- generated by the nightly export job
# sql-pre-data postgres CREATE SCHEMA IF NOT EXISTS shop
# table name=orders rows=3 columns=6
# meta-grain one row per order
# column name=id type=long role=id unique=1 link="https://crm.example.com/orders/{$}"
# column name=customer_id type=long role=dimension references=customers.id
# column name=status type=string role=dimension enum=pending|completed|cancelled
# column name=price type=decimal format=0.00 unit=@cur role=measure agg=avg
# column name=quantity type=int role=measure agg=sum min=1
# column name=cur type=string pattern="^[A-Z]{3}$" example=EUR
# column name=total type=decimal unit=@cur role=measure agg=sum formula="price * quantity"
# chart type=bar name=quantity_by_status x=status y=quantity
# note key=1002 col=status author=alex@example.com text="Awaiting payment confirmation"
# link key=1003 col=id href="https://crm.example.com/archive/1003"
# sql-pre-data postgres CREATE TABLE shop.orders (id bigint PRIMARY KEY, customer_id bigint, status text, price numeric(12,2), quantity int, cur char(3), total numeric(12,2) GENERATED ALWAYS AS (price * quantity) STORED)
# sql-post-data postgres ALTER TABLE shop.orders ADD FOREIGN KEY (customer_id) REFERENCES shop.customers(id)
# sql-post-data postgres CREATE INDEX orders_customer ON shop.orders(customer_id)
# sql-dql postgres SELECT status, sum(quantity) FROM shop.orders GROUP BY status
# agg-count-nonnull 3,3,3,3,3,3
# agg-count-distinct 3,2,3,3,3,2
# agg-sum ,,,,15,
# agg-min ,,,,1,
# agg-max ,,,,10,
id,customer_id,status,price,quantity,cur
1001,7,completed,12.50,4,EUR
1002,7,pending,99.00,1,USD
1003,8,cancelled,5.00,10,EUR
# table name=customers rows=2
# meta-grain one row per customer
# column name=id type=long role=id
# column name=name type=string len-max=200
# column name=email type=string example=someone@example.com
# sql-pre-data postgres CREATE TABLE shop.customers (id bigint PRIMARY KEY, name text, email text)
id,name,email
7,Ann,ann@example.org
8,Bob,bob@example.orgNotes on the example:
tables=2is required because there are two tables;quote=doubleapplies to both. Both start with a header row:headeris a table key and defaults to1.totalis virtual: it has no header cell and no field, socolumns=6and everyagg-*line has six values.priceandtotaltake their currency fromcurper row (unit=@cur), soagg-sum,agg-minandagg-maxleavepriceempty — orders are in EUR and USD, and money in different currencies is never combined.- The foreign key from
orderstocustomersis in theordersblock althoughcustomerscomes later:sql-post-dataruns after every table is created and loaded. - The file-level
notehas no address; the table-level one is pinned bykey=to order 1002 and survives sorting. linkoverrides theidcolumn'slink=template for order 1003 only.
The same tables as external files
txtab
# texttables=0.1 tables=2
# meta-source shop_db
# table name=orders reference=orders.csv rows=48213 delim=comma data-size=1900000
# column name=id type=long role=id
# column name=customer_id type=long references=customers.id
# table name=customers reference=customers.tsv rows=5120 delim=tab
# column name=id type=long role=idorders.csv and customers.tsv stay untouched, ordinary CSV and TSV files.
The same tables in an archive
text
shop.txtab.zip
├── shop.txtab
├── orders/
│ ├── 00-id.col
│ ├── 01-customer_id.col
│ └── …
└── customers.tsvtxtab
# texttables=0.1 tables=2
# table name=orders reference=orders/ storage=columns rows=48213 section-size=10000 data-size=1900000
# column name=id type=long role=id
# column name=customer_id type=long references=customers.id
# table name=customers reference=customers.tsv rows=5120 delim=tab
# column name=id type=long role=id