guide/example
Full example
Two tables, one file — most of the vocabulary at once. The same file, annotated line by line for tool builders, is in ../spec/example.md.
txtab
# texttables=0.1 delim=comma quote=double tables=2
# meta-source shop_db
# meta-as-of 2026-11-01
# note text="November snapshot; refunds are processed separately"
# -- generated by the nightly export job
# 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 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 text="Awaiting payment confirmation"
# sql-pre-data postgres CREATE TABLE orders (id bigint PRIMARY KEY, customer_id bigint, status text, price numeric(12,2), quantity int, cur char(3))
# sql-post-data postgres ALTER TABLE orders ADD FOREIGN KEY (customer_id) REFERENCES customers(id)
# agg-count-distinct 3,2,3,3,3,2
# agg-sum ,,,,15,
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
# column name=id type=long role=id
# column name=email type=string example=someone@example.com
# sql-pre-data postgres CREATE TABLE customers (id bigint PRIMARY KEY, email text)
id,email
7,ann@example.org
8,bob@example.orgWhat to notice:
- Two tables, counted.
tables=2on the first line,rows=on each table — a truncated file can't pass for a complete one. totalcosts nothing. It's a formula overpriceandquantity, with no cell in any row.- Two currencies, no fake total.
pricetakes its currency fromcur, so the price slot inagg-sumstays empty. - The foreign key comes before its target. It's in
sql-post-data, which runs after both tables exist and are loaded. - The note survives sorting. It's pinned by
key=1002, not by position. - Every system line starts with
#— sopd.read_csv(f, comment="#")would read the orders table as plain CSV. (With two tables in the file it would glue them together; read them with a Text Tables tool.)