PERF-CAT-002 — Define bounded Sample and History execution
| Field | Value |
|---|---|
| Status | Open finding; source-verified, scale benchmarks pending |
| Severity | High |
| Affected surface | Catalog Sample Data and Delta History |
| Implementation issue | bff-api #233 |
| Code-change repository | sparqd/bff-api |
Where the problem appears
Open Sample and History for representative small, wide, fragmented, highly partitioned, and long-history Delta tables.
Concrete observed case
Sample returns ten rows but does not bound planning, file enumeration, columns, cell size, or response bytes. History returns twenty rows after ordering the Delta history but has no declared commit-count, timeout, cancellation, pagination, or slow-state contract. Both force synchronous execution.
Expected condition
Load on demand and enforce row, column, cell, response-byte, planning-time, and execution-time limits. Show elapsed slow state, propagate cancellation, distinguish timeout, prevent stale output, and offer an equivalent query in SQL Editor.
Cause and evidence
- Returned row limits do not bound upstream work or serialized value size.
- History scale follows transaction-log characteristics rather than table row count.
- The deployed async SQL capability is not used by these paths.
Why it matters
A small visible result can occupy Trino capacity, hold a request open, fail without actionable feedback, or deliver values large enough to destabilize the browser.
Existing controls and workarounds
Use SQL Editor with explicit columns and an approved partition predicate. Treat Sample as an arbitrary preview, not a random or representative sample.
Alternatives considered
- Recommended: bounded deterministic preview and paged History with cancellation/timeouts.
- Approximate TABLESAMPLE SYSTEM as an explicit option, with bias and count caveats.
- Cache results only with principal and table-version scoping; caching alone does not bound first execution.
Component involvement
- BFF owns execution budgets, cancellation, timeouts, and response limits.
- Oqullus owns slow/error/stale states and SQL Editor handoff.
- Operations establishes supported performance boundaries.
Reproduction and verification
Follow CAT-S022. Record the visible state, request outcome, effective identity, and recovery behavior relevant to this finding.
Resolution conditions
Close when the scale matrix, limits, p95 latency, timeout, cancellation propagation, stale-result prevention, and authorization-scoped cache behavior are verified.
Validation and blockers
BFF, Oqullus, Trino, and operations owners must validate. Benchmarks in w-t5e2kcxjd remain pending.