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

guide/archive

Archives (.txtab.zip)

Zip a Text Tables file and it stays the same file — just smaller, and able to carry the data files it describes.

text

sales.txtab.zip
├── sales.txtab          ← the main file, always first
├── orders/              ← one table stored column by column
│   ├── 00-id.col
│   ├── 01-customer_id.col
│   └── 02-amount.col
└── customers.csv        ← another table as an ordinary CSV

The main file is an ordinary .txtab named after the archive. It describes every table — there's no separate manifest. Tables point at their data with reference=, resolved inside the archive.

Preview without unzipping

The archive's comment carries the main file without its rows: the first line, the metadata, every table with its columns, aggregates and SQL. A tool shows what's in a zipped export without extracting it:

bash

txtab peek sales.txtab.zip

The comment holds at most 64 KiB. If it doesn't fit, the writer keeps every table line and fills the rest by priority — columns first, then aggregates, then SQL, notes last — and adds a # meta-comment-truncated flag right under the first line. The file inside is always the source of truth.

Storing a table by column

txtab

# table name=orders reference=orders/ storage=columns rows=237000 section-size=10000

storage=columns keeps each column in its own .col file — one value per line. Worth it for wide tables and snapshots:

  • Read two columns out of two hundred without decompressing the rest.
  • Better compression — a column of one type squeezes well.
  • Add a column by adding a file.

section-size= splits each column into chunks, so a tool can jump to row N without reading the whole column. All the metadata stays in the main file; the table directory holds only .col files.

Mixing

One archive can hold tables in all three forms: inline in the main file, as CSV/TSV next to it, and by column. A small lookup table inline, a big fact table by column.

Passwords and compression

Standard ZIP encryption works; the password is your tool's business and never written into the file. Deflate is the usual compression; ZIP64 handles large archives.

guide/archive.md on GitHub