41 lines
2.0 KiB
Markdown
41 lines
2.0 KiB
Markdown
# 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.
|