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 CSVThe 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.zipThe 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=10000storage=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.