# `.txtab.zip` and column storage

## Layout

```
sales.txtab.zip
├── sales.txtab          ← main file: first entry, named after the archive (or data.txtab)
├── orders/              ← table with storage=columns
│   ├── 00-id.col
│   └── 01-amount.col
└── customers.csv        ← table with reference=customers.csv
```

The main file is an ordinary `.txtab` describing every table; `reference=` resolves inside the archive.

## Peek without extracting

```sh
unzip -z sales.txtab.zip                     # comment = main file without data rows
unzip -Z1 sales.txtab.zip | head -1          # main file name
unzip -p sales.txtab.zip sales.txtab | head  # main file
```

- The comment keeps line 1 and every `table` line. If it contains `P meta-comment-truncated` (right after line 1), lower-priority lines were dropped — columns, aggregates, SQL, metadata, charts, notes in that order of keeping. Read the main file for the rest.
- `data-size=` on each `table` is the approximate unpacked size of its data; sum them to estimate the whole.

## Column storage

```
# table name=orders reference=orders/ storage=columns rows=3 columns=2 section-size=10000
```

- One file per physical column: `<index>-<name>.col`, one value per line in record order, an empty line is an empty field, the table's `null=` marker applies, no quoting.
- Every `.col` file has exactly `rows` lines. There is no header row: names come from the file names and `column` lines.
- With `section-size=N`, each column is a directory `<index>-<name>/` of files `<start>.col` (zero-padded first record). Record `n` is in section `⌊n/N⌋·N`, line `n − start`.

Rebuild rows from columns:

```sh
unzip -q sales.txtab.zip -d /tmp/s && paste -d, /tmp/s/orders/00-id.col /tmp/s/orders/01-amount.col
```

```python
import pandas as pd, pathlib
d = pathlib.Path('/tmp/s/orders')
df = pd.DataFrame({p.stem.split('-', 1)[1]: p.read_text(encoding='utf-8').splitlines()
                   for p in sorted(d.glob('*.col'))})
```

Read only the columns you need — that is what column storage is for.
