Approximate Performance Optimizations

Some expensive reads do not need to be an exact, current statement of business truth. A person browsing recent orders usually values a fast next page more than snapshot-perfect page boundaries. A dashboard may value a recently cached aggregation more than making every visitor wait for the same calculation.

TeaQL treats these as explicit, approximate performance optimizations. They are disabled unless application code opts in. Opting in means the caller accepts that cached state can make a response temporarily stale, or that records can briefly overlap or move between pages while the underlying data changes.

For continuous browsing, the best experience normally comes from omitting an exact total count. A small indexed page can stay fast at great depth, while a separate exact count may still scan the entire matching set and dominate the response time. Browsing interfaces can stop on a short or empty page instead.

These optimizations do not weaken tenant, permission, purpose, comment, audit, or hard-limit enforcement. Trusted scope is still applied before an optimization is considered.

The boundary

Use approximate optimization for presentation and exploration:

• browsing recent orders, events, messages, logs, or activity;
• a human repeatedly choosing next page;
• dashboards whose freshness contract permits a documented cache duration;
• read-only screens that can be refreshed without changing a business outcome.

Do not use it when the returned rows or numbers drive business behavior:

• settlement, billing, accounting, inventory allocation, or payment decisions;
• approval, compliance, eligibility, fraud, or permission decisions;
• batch processing, migration, reconciliation, or an exact export;
• code that assumes every matching row was visited exactly once;
• a value used as a mutation precondition or optimistic-lock decision.

The useful test is not “is this screen important?” It is:

Would a small overlap, omission, or temporarily stale value change a business decision or cause an irreversible action?

If the answer is yes, run the exact query.

Optimization families

Optimization	Accepted approximation	Intended use
Continuous page fetch	Data changes can cause a small overlap or gap between pages	Human browsing with a unique ordered key, commonly id DESC
Aggregation result cache	A count, sum, facet, or other aggregation can be stale for its accepted cache lifetime	Dashboards and exploratory statistics

Java already exposes aggregation-cache controls. Availability and exact naming in other runtimes must be checked against that runtime's released API. Continuous page fetch is currently a design proposal; the proposed instruction must not be copied into application code until its runtime implementation is released.

Shared rules

Every approximate optimization should follow the same contract:

1. Application code opts in explicitly; dynamic client JSON cannot silently enable it.
2. The instruction describes an accepted trade-off, not a correctness guarantee.
3. A cache miss, invalid state, unsupported query, or provider error falls back to the exact existing path.
4. Cache keys and state are isolated by trusted tenant, merchant, user, and permission scope.
5. Runtime traces identify the selected plan, cache hit or miss, fallback reason, and a safe state identifier.
6. Cache state is bounded by TTL and capacity and can be replaced by an application-provided store.
7. No password, token, complete connection string, email, or raw sensitive filter value is written to cache metadata or ordinary logs.

Why this is explicit

TeaQL could turn these optimizations on automatically, but doing so would hide a meaningful semantic trade-off. Explicit opt-in keeps the fast path convenient without making approximate behavior look exact. It also gives code review a clear point at which to ask whether a query is for browsing or for business logic.

Read Continuous Page Fetch for the proposed deep-page optimization and its server-side Cursor design.