# SQL

Table definitions for the database form of packages, a team's store, and the bundle.

| File | Holds | Runs on |
| --- | --- | --- |
| `doc.sql` | Documents: works, documents, witnesses, nodes, pages, locations, references, citations, corrections, IDs, receipts, revocations, suspects and package files. | SQLite, Dolt, PostgreSQL |
| `store.sql` | What a team adds: roster keys, projects, members, reading paths, layers, annotations, datasets, digitizations, views, policies, submissions and grades. Load `doc.sql` first. | SQLite, Dolt, PostgreSQL |
| `bundle-sqlite.sql` | The bundle's extra tables: metadata, a full-text index (FTS5) and room for embeddings. Load both files above first. | SQLite |

## Creating a database

```sh
sqlite3 lab.db < sql/doc.sql && sqlite3 lab.db < sql/store.sql
psql -d lab -f sql/doc.sql && psql -d lab -f sql/store.sql
dolt sql < sql/doc.sql && dolt sql < sql/store.sql
```

To load packages into SQLite with nothing installed, use `python3 tools/load.py --sqlite lab.db PACKAGE…`; [docs/examples.md](../docs/examples.md#load-packages-into-sqlite) has queries to try.

## Conventions

- No foreign keys: validators check references, so the same file runs everywhere.
- Enumerations are `VARCHAR` with a `CHECK`; JSON values are canonical JSON in `TEXT`; booleans are `INTEGER` 0 or 1.
- No table, column or index name is reserved in any of the three engines, so the formats' `key`, `index`, `at`, `by`, `before` and `after` become `doc_key`, `idx`, `made_at`, `signer`, `before_hash` and `after_hash`.
- Each row keeps every property of its record, so a package loaded into the tables unloads back to the same bytes.
- `citations`, `receipt_nodes` and `annotation_targets` are derived on load, for queries.

## A first query

Every sentence that cites a given reference, which is the citation's context:

```sql
SELECT c.sentence
FROM citations c
JOIN refs r ON r.doc_key = c.doc_key AND r.node = c.ref_node
WHERE c.doc_key = 'hale2026harmonic' AND r.label = '2';
```

[Chapter 13](../spec/13-database.md) defines the mapping from files to tables.