guide/introduction
Introduction
You open a CSV someone sent you. Which column is the amount? Is 01720 a ZIP code or the number 1720? Is 2026-01-02 the 2nd of January or the 1st of February? Are these all the rows, or just the first thousand your viewer loaded? What's the total — do you trust it, or add the column up yourself? And what about the other three files that came with it — how do they connect?
The answers usually live somewhere else: a README, a chat thread, someone's memory. Text Tables puts them back in the file. Column types and units, what one row means, pre-computed totals, where the data came from, the CREATE TABLE that would recreate it — written as lines that start with a prefix (usually #) which CSV tools already know how to skip.
txtab
# texttables=0.1 delim=comma
# meta-source crm export
# table name=orders rows=2
# column name=id type=long role=id
# column name=amount type=decimal unit=USD role=measure agg=sum
# agg-sum ,1050.50
id,amount
1,500.00
2,550.50Below the system lines it's ordinary CSV. Tell pandas, R or DuckDB that # starts a comment and they read it as before.
It describes; it never changes your data
Reading a Text Tables file never rewrites a value, never fills a blank, never "corrects" anything. What's in the rows is what's there. A few explicit commands do write data — materializing a computed column, slicing a table — but they are deliberate edits, never a side effect of opening a file.
What you can add
Every layer is optional. Start with the first line, then name your tables, then add types, then totals, then SQL — and stop wherever it's useful enough.
- The first line — names the format and the CSV dialect: delimiter, quote, header row, encoding.
- Tables (
table) — each table declares how many rows it has, optionally a name, and where its data is. - Columns (
column) — types, units and currencies, formats, allowed values, analytical roles (id, measure, time), relations to other tables, computed columns. - Aggregates (
agg-*) — sum, average, min, max, counts — written down, so the total is a fact in the file. - Metadata (
meta-*) — source, author, license, the date the data is current as of, and what one row is. - SQL (
sql-*) — the DDL to recreate the tables, split likepg_dumpinto before-data and after-data, and queries for provenance. - Notes, links and charts — remarks on cells and rows, clickable values, suggested views.
One file, many tables
A file can hold several tables, each starting with its own table line. Their data can sit right in the file, in ordinary CSV/TSV files next to it (which stay untouched), or column by column inside a .txtab.zip. One .txtab can describe a whole folder of exports.
A new take on ExCSV
Text Tables grew out of ExCSV 0.6. It keeps ExCSV's idea — CSV that describes itself — and reworks the syntax: a configurable prefix, keywords instead of sigils, several tables per file, one archive form. It is a new format: Text Tables tools don't read ExCSV files.