Skip to content

Commit adfee9b

Browse files
Add the file_sizes table for SQL benchmark file sizes (#221)
* Add the file_sizes table for SQL benchmark file sizes The monorepo's PR benchmark comments compare against baselines from this database, and SQL benchmark file sizes were never stored, so the comments lost their file-size section. Migration 014 adds `file_sizes`, keyed by (commit_sha, benchmark, scale_factor, format, file), with an index on the dims the CI baseline lookup filters on. The default privileges from 004, 005 and 011 grant the ingest, read and CI-read roles their access. Signed-off-by: Joe Isaacs <joe.isaacs@live.co.uk>
1 parent ebe59ad commit adfee9b

6 files changed

Lines changed: 42 additions & 6 deletions

File tree

‎db/migrations/014_file_sizes.sql‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
-- SPDX-License-Identifier: Apache-2.0
2+
-- SPDX-FileCopyrightText: Copyright the Vortex contributors
3+
4+
-- The on-disk size of each Vortex file a SQL benchmark writes, per commit.
5+
CREATE TABLE IF NOT EXISTS file_sizes (
6+
measurement_id BIGINT PRIMARY KEY NOT NULL,
7+
commit_sha TEXT NOT NULL,
8+
benchmark TEXT NOT NULL,
9+
scale_factor TEXT NOT NULL,
10+
format TEXT NOT NULL,
11+
file TEXT NOT NULL,
12+
value_bytes BIGINT NOT NULL
13+
);
14+
15+
-- CI reads one commit's files per benchmark scope.
16+
CREATE INDEX IF NOT EXISTS idx_file_sizes_baseline
17+
ON file_sizes (benchmark, scale_factor, format, commit_sha);

‎db/migrations/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,9 @@ lexicographic order, which equals numeric order under this convention.
8484
connections at most, and by default read-only transactions, a 30 s statement timeout and a
8585
60 s idle-in-transaction timeout. Only the connection limit is enforced; a session can change
8686
the defaults. The RDS master applied it in production on 2026-11-03.
87+
- `014_file_sizes.sql` — adds the `file_sizes` table for the on-disk size of each Vortex file a SQL
88+
benchmark writes, which PR benchmark comments compare against develop. The default privileges from
89+
004, 005 and 011 grant the three login roles their access. `migrator` applies it.
8790

8891
This README + the runner ship in PR-1.2; `001`/`002` land in PR-1.3, `003` in
8992
PR-1.4, `004` in PR-2.1, `005` in the Phase-4 operator-gate work (the v4

‎docs/bench/CONTRACT.md‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ A `SCHEMA_VERSION` bump must be coordinated with them in the same logical change
4646

4747
The monorepo emitter `vortex-bench --gh-json-v3 <path>` writes **JSONL of bare records only** —
4848
one JSON object per line, no envelope. `records` are discriminated by a `kind` field
49-
(snake_case). The five kinds and their destination fact tables:
49+
(snake_case). The six kinds and their destination fact tables:
5050

5151
| `kind` | Destination table |
5252
|----------------------|-----------------------|
@@ -55,6 +55,7 @@ one JSON object per line, no envelope. `records` are discriminated by a `kind` f
5555
| `compression_size` | `compression_sizes` |
5656
| `random_access_time` | `random_access_times` |
5757
| `vector_search_run` | `vector_search_runs` |
58+
| `file_size` | `file_sizes` |
5859

5960
Each record's fields are defined by the producer structs in the monorepo's
6061
`vortex-bench/src/v3.rs` and match the column names of its fact table (see
@@ -71,6 +72,12 @@ Its `uncompressed_bytes` is the column's canonical Arrow `Utf8View` size. The si
7172
rows in the `String Encoding` groups and compares each encoder with `fsst`, so the prefix and the
7273
`fsst` label are part of the contract.
7374

75+
`file_size` records are not written by `vortex-bench`: the monorepo's
76+
`scripts/capture-file-sizes.py` writes one per Vortex file a SQL benchmark leaves on disk, with
77+
`benchmark` (the `vx-bench` subcommand), `scale_factor`, `format`, `file` (the path below the format
78+
directory) and `value_bytes`. The read service does not chart them; CI reads them back as the develop
79+
baseline for the PR comment's file-size section.
80+
7481
`random_access_time` records include `open_mode`. The value is `cached` for a reused accessor
7582
or `reopen` when each timed take includes a new accessor. Historical rows use `cached`.
7683
The `reopen` mode does not clear the OS page cache.
@@ -119,7 +126,9 @@ measurement, which silently duplicates or collides rows instead of upserting.
119126
The freeze is pinned by golden vectors, not by trust. The monorepo's
120127
`scripts/measurement_id_golden.json` holds `(input → hash)` cases covering empty/Unicode
121128
strings, `i32` bounds, and `f64` edges, generated by the original Rust implementation (the
122-
retired v3 server, which wrote the production rows) and **never regenerated**; the monorepo's
129+
retired v3 server, which wrote the production rows) and **never regenerated**. The `file_sizes`
130+
vectors postdate that server: `scripts/_measurement_id.py` generated them when the table was
131+
added (migration 014), and they are frozen the same way. The monorepo's
123132
`scripts/tests/test_measurement_id.py` asserts every vector byte-for-byte in CI. The golden
124133
vectors ARE the contract.
125134

@@ -149,3 +158,8 @@ logical change:
149158

150159
For wire/record *shape* changes, also update the producer snapshot fixtures in the monorepo in
151160
the same commit.
161+
162+
A new record kind with its own table, as `file_size` was in migration 014, changes no existing
163+
shape, so it needs no bump: the read service never reads the new table, and older writers never
164+
send the kind. Its migration must be applied before a writer sends it, because each JSONL file
165+
lands in one transaction and an unknown table fails the whole file.

‎docs/bench/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,8 @@ the site reads straight from it.
5151

5252
**Emit.** Each benchmark CI run in the monorepo writes JSONL measurement records
5353
(`vortex-bench --gh-json-v3`), and `scripts/post-ingest.py` delivers them. Every measurement is
54-
one of five kinds — query time, compression time, compression size, random-access time, and
55-
vector search — each carrying a commit SHA plus the dimension tuple that identifies its chart.
54+
one of six kinds — query time, compression time, compression size, random-access time, vector
55+
search, and SQL benchmark file size — each carrying a commit SHA plus the dimension tuple that identifies its chart.
5656
The versioned wire format is this repo's [`CONTRACT.md`](CONTRACT.md).
5757

5858
**Store.** One AWS RDS Postgres database holds one fact table per measurement kind plus a

‎docs/bench/architecture/data-pipeline.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ v2→v3→v4 migration a faithful copy rather than a re-derivation.
2929

3030
## The record model
3131

32-
Every measurement is one of **five kinds**, each routed to its own fact table:
32+
Every measurement is one of **six kinds**, each routed to its own fact table:
3333

3434
| `kind` | Fact table | Dimension tuple (besides `commit_sha`) |
3535
|---|---|---|
@@ -38,6 +38,7 @@ Every measurement is one of **five kinds**, each routed to its own fact table:
3838
| `compression_size` | `compression_sizes` | dataset, dataset_variant, format |
3939
| `random_access_time` | `random_access_times` | dataset, format |
4040
| `vector_search_run` | `vector_search_runs` | dataset, layout, flavor, threshold |
41+
| `file_size` | `file_sizes` | benchmark, scale_factor, format, file |
4142

4243
Plus one **dimension table**, `commits`, keyed by `commit_sha` (40-hex), carrying
4344
the commit timestamp, message, author/committer, tree SHA and URL. The commit row

‎infra/RESTORE.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,8 @@ UNION ALL SELECT 'query_measurements', count(*), max(measurement_id)::text FROM
153153
UNION ALL SELECT 'compression_times', count(*), max(measurement_id)::text FROM compression_times
154154
UNION ALL SELECT 'compression_sizes', count(*), max(measurement_id)::text FROM compression_sizes
155155
UNION ALL SELECT 'random_access_times', count(*), max(measurement_id)::text FROM random_access_times
156-
UNION ALL SELECT 'vector_search_runs', count(*), max(measurement_id)::text FROM vector_search_runs;
156+
UNION ALL SELECT 'vector_search_runs', count(*), max(measurement_id)::text FROM vector_search_runs
157+
UNION ALL SELECT 'file_sizes', count(*), max(measurement_id)::text FROM file_sizes;
157158
```
158159

159160
- The ledger must list every file in [`../migrations/`](../db/migrations/).

0 commit comments

Comments
 (0)