WeaveKit Docs

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:

KeyDefaultBounds
maxRows1000rows returned by a list/find
maxDepth10GraphQL selection depth
maxJoins8JOINs in a restricted SQL query
maxFilters50filter conditions (each $or member counts)
maxSorts8sort keys
maxSqlLength20000restricted SQL length (characters)
statementTimeoutMs5000database statement_timeout per query

Behavior

  • A request that exceeds a limit fails closed with query.budget.exceeded (the offending limit and max are 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_DEFAULTS are exported for hosts that build data-access directly.
  • Per-context override — DataAccessContext.budget overrides 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 by ANALYZE).
  • none — skip counting entirely; total is omitted and hasMore is 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.

On this page