Query budget
One budget that bounds what any single read or query may cost — across every protocol.
The query budget is one object that caps the cost of a single read/query. It is enforced in the shared data-access layer, in restricted SQL, and in the protocol adapters, so a caller cannot bypass a limit by switching protocol (REST → MCP → GraphQL).
// weavekit.config.ts
export default {
// ...
queryBudget: {
maxRows: 500, // list/find row cap (REST / MCP / GraphQL)
maxDepth: 8, // GraphQL selection depth
maxJoins: 5, // restricted SQL joins
maxFilters: 20, // filter conditions (incl. $or members)
maxSorts: 4, // sort keys
maxSqlLength: 10_000, // restricted SQL statement length (chars)
statementTimeoutMs: 3_000, // per-query statement_timeout
},
};Every key is optional; absent keys fall back to QUERY_BUDGET_DEFAULTS:
| Key | Default | Bounds |
|---|---|---|
maxRows | 1000 | rows returned by a list/find |
maxDepth | 10 | GraphQL selection depth |
maxJoins | 8 | JOINs in a restricted SQL query |
maxFilters | 50 | filter conditions (each $or member counts) |
maxSorts | 8 | sort keys |
maxSqlLength | 20000 | restricted SQL length (characters) |
statementTimeoutMs | 5000 | database statement_timeout per query |
Behavior
- A request that exceeds a limit fails closed with
query.budget.exceeded(the offendinglimitandmaxare in the error params) — never a silent truncation. - Resolution is centralized:
resolveQueryBudget(partial)merges your config over the defaults and rejects non-positive/invalid values.resolveQueryBudget/QUERY_BUDGET_DEFAULTSare exported for hosts that build data-access directly. - Per-context override —
DataAccessContext.budgetoverrides the instance budget for one operation (e.g. a trusted internal job), without changing global config.
List total (count cost)
A list response carries total (the full count, not just the page). Exact counting is a second query;
on large tables you can trade it for speed with EngineConfig.query.total (default exact):
export default { query: { total: 'estimate' } }; // or 'none'exact—SELECT COUNT(*)with the same filter/scope (default).estimate—pg_class.reltuples(table-level, ignores the filter; approximate, refreshed byANALYZE).none— skip counting entirely;totalis omitted andhasMoreis derived by fetching one extra row.
A request can override it per call: REST ?total=none, GraphQL total: ESTIMATE, MCP total: "none"
(client FindParams.total). With none, total is absent from the REST envelope and null in GraphQL.
This is deliberately not the same as Quotas: quotas are durable, cross-request
usage counters (weavekit_counters); the query budget is a per-query structural cap.
Related
- Quotas — durable usage budgets
- RBAC — what a scoped read is allowed to see
- GraphQL — depth/complexity hardening at the adapter
- Public API & dependency budget