Description
Nightly Knowledge Graph Precompute prepares the expensive derived views needed by Dots graph experiences before a user asks for them. At 02:00 each night, the registered job computes database-grouped two- and three-dimensional node layouts, per-Dotabase rollups, cross-Dotabase super-edge aggregates, property-cluster values and flows, and a cached graph summary.
The handler is strictly tenant-scoped. It refuses to reshape graph tables without a company id, then adapts the Jobs database seam into the knowledge-graph precompute transaction contract. The same registered job can be queued manually through dots jobs run graph-precompute after a large import or graph change.
Selling Points
- Moves expensive graph layout and aggregation work off the interactive read path.
- Produces both two-dimensional and three-dimensional coordinates from one scheduled refresh.
- Prepares Dotabase-level and cross-Dotabase rollups for overview and drill-down experiences.
- Keeps destructive clear-and-rewrite operations inside the requesting company boundary.
- Returns structured counts and a diagnosable failure instead of hiding database-driver detail.
User Story
After a workspace imports thousands of related rows, the nightly job rebuilds its graph coordinates and aggregate summaries in the background. The next morning, the graph overview can load cached totals and layouts instead of recomputing them in the browser. If the team needs the refresh sooner, an owner queues the same job manually.
Extension Surface
The feature is automatable because its stable registered id supports both cron and CLI triggering. packages/jobs/src/catalog/foundation-cron.ts defines cadence, timeout, priority, and non-overlap behavior. packages/jobs/src/catalog/graph-precompute.ts delegates the domain computation through the exported runGraphPrecompute seam, so scheduler concerns remain separate from graph metrics.
Capabilities & Limits
The job computes node and edge counts, Dotabase counts, cross-database edge counts, coordinates, cluster aggregates, and cached summaries inside one company scope. It reports a completed degraded result when row-grain layout is over the supported node cap while still producing rollups and summary data.
It is a periodic cache and projection refresh, not the source of truth for rows or edges. A null company scope fails closed. The default retry policy has zero retries, and concurrency is skip, so a missed or failed nightly run relies on the next schedule or an explicit operational rerun. Very large graphs may intentionally omit individual node layout.
Implementation Map
packages/jobs/src/catalog/foundation-cron.tsgraph-precompute0 2 * * *packages/jobs/src/catalog/graph-precompute.tspackages/knowledge-graph/src/metrics/precompute.tspackages/jobs/src/scheduler.tspackages/cli/src/commands/jobs.ts