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

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.org

What to notice:

  • Two tables, counted. tables=2 on the first line, rows= on each table — a truncated file can't pass for a complete one.
  • total costs nothing. It's a formula over price and quantity, with no cell in any row.
  • Two currencies, no fake total. price takes its currency from cur, so the price slot in agg-sum stays 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 # — so pd.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.)

guide/example.md on GitHub