Skip to content

Bounded history pages and an entity-attribute history index (#72) - #115

Draft
bjacobso wants to merge 1 commit into
mainfrom
triplex/bounded-reads
Draft

bjacobso wants to merge 1 commit into
mainfrom
triplex/bounded-reads

Conversation

@bjacobso

Copy link
Copy Markdown
Owner

Refs #72. This covers history only: bounded match, entity and entities are not here. It is kept small so it can be reconciled with the design/bounded-reads design work. The issue asks for a separate API review before implementation, so this is a draft for that review.

What changes

  • Triples.historyPage(entityId, { attribute?, limit?, cursor?, recordedPosition? }).
    • Order and contents: oldest first by (commit position, fact ID), retracted assertions included.
    • Page size: 100 by default, at most 1,000, with limit+1 detection, so a full last page has no cursor.
    • Stable continuation: the first page captures the head (or recordedPosition), and every continuation reads at that position. Writes between pages neither repeat nor skip facts. A later assertion is not shown, and a fact retracted after the snapshot is shown unretracted, as it was then.
    • Cursors: opaque and bound to the database scope, entity, attribute and position. A mismatch fails with PaginationCursorError (scope_mismatch, query_mismatch, basis_mismatch or malformed).
    • Sensitive values: the Sensitive layer passes the call through, so sealed values stay sealed.
    • history(entityId) is unchanged.
  • Backends.
    • SQL (SQLite, PostgreSQL, Cloudflare): one shared statement that seeks idx_entity_recorded_position, or the new idx_entity_attribute_history for one attribute.
    • KV and FoundationDB: new (entity, position, ID) and (entity, attribute, position, ID) keys, written on assert and backfilled once in bounded, resumable batches.
  • Host protocol: a HistoryPage operation.
  • Migrations.
    • SQL migration 2 and Cloudflare migration 8 add idx_entity_attribute_history ON triples(entity_id, attribute, recorded_position).
    • checkSchemaHistory now accepts a prefix of this release's migrations as "pending". runMigrations and the migrating layers upgrade a 0.5.0 file in place.
    • The read-only and non-migrating layers refuse a 0.5.0 file with SchemaVersionError { pending: true } until migrations run. This is a behavior change for hosts that run migrations themselves.
  • Optional projections: the same index lets each row's optionalProjection subquery look up one entity's attribute directly. Before, SQLite planned it on idx_attribute_valid_from_history and scanned every entity's values for each row.

Evidence

History, one entity among 10,000 others, median of 7 runs (ms):

Backend Facts on entity history() historyPage 100 page 2 one attribute, 100
SQLite 10 0.18 0.36 — 0.27
SQLite 10,000 46.9 0.97 1.02 0.72
KV 10 0.15 0.10 — 0.04
KV 10,000 47.8 0.28 0.21 0.24

Optional projection on the explorer's 1,200-worker demo database (seed), 50-row queryPage sorted by an optional attribute:

Sort Before After Join (unchanged)
:worker/hourly-rate 7.4–7.8 s (page 2: 8.5–8.7 s) 39–51 ms (page 2: 49–53 ms) 12–14 ms
:worker/email 6.2–6.4 s (page 2: 7.2–7.8 s) 39–41 ms (page 2: 52–67 ms) 11–15 ms
:worker/manager 6.1–6.7 s 38–39 ms (page 2: 54–56 ms) 11–12 ms

The explorer still uses joins. Switching it to optional projections is a separate choice.

Plans (SQLite): the history page seeks idx_entity_recorded_position (entity_id=? AND recorded_position>? AND recorded_position<?), or idx_entity_attribute_history (entity_id=? AND attribute=? AND recorded_position<?) for one attribute.

Tests

  • Shared conformance case (historyPageConformanceCases, run on KV, SQLite, the Cloudflare harness, and PostgreSQL in CI):
    • Equivalence with the unpaged history oracle for every attribute filter at limits 1, 2, 7 and 1000, covering ties within a transaction and retractions.
    • No fact repeated across pages, commit order, and the exact page count (limit+1).
    • Assertions and retractions between pages.
    • Position 0.
    • Cross-entity, cross-attribute, cross-position and malformed cursors.
    • Out-of-range limits.
  • Host: decoded HistoryPage requests, including a cursor and a recorded position.
  • SQLite: a 0.5.0 baseline file is refused by the read-only layer as pending, then upgraded in place, and its facts are still read.
  • Local runs: pnpm check and pnpm pack:check pass, and the Cloudflare workerd suite passes. The PostgreSQL and FoundationDB suites were not run locally (they need external services) and are left to CI.

Not in this PR

  • Bounded match, entity and entities, and byte bounds on a page.
  • A history page at an explicit recordedAt instant (it takes a position).

Triples.historyPage reads one entity's history, or one attribute's, in
index-seek pages pinned to the first page's commit position, with an opaque
cursor bound to scope, entity, attribute and position. KV gets entity and
entity-attribute history keys with a bounded one-time backfill; SQL backends
seek idx_entity_recorded_position or the new idx_entity_attribute_history.
The host protocol gains a HistoryPage operation.

The new index (SQL migration 2, Cloudflare migration 8) also serves Datalog
optional projections, which SQLite planned on an attribute-wide index: a
50-row explorer page sorted by an optional attribute drops from 6.2-8.7 s to
38-56 ms. runMigrations upgrades a 0.5.0 database in place; non-migrating
layers report the pending migration.

Refs #72.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1f02a-e1b5-7578-bc7a-392b7507001f
Co-authored-by: Amp <amp@ampcode.com>
@github-actions

Copy link
Copy Markdown
Contributor

Documentation preview: https://triplex-docs-pr-115.bjacobso.workers.dev

Commit: 7c155bd

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants