Skip to main content

Limits and count

Low-level defaults are:

query.Limits{
MaxQueryBytes: 16 << 10,
MaxFilterBytes: 8 << 10,
MaxTokens: 512,
MaxLiteralBytes: 4 << 10,
MaxInValues: 100,
MaxLimit: 100,
MaxOffset: 100_000,
MaxSortTerms: 5,
MaxSearchBytes: 256,
MaxExpressionDepth: 16,
MaxNodes: 100,
MaxPathDepth: 8,
MaxQuantifierDepth: 4,
MaxCursorBytes: 4 << 10,
}

All custom values passed to WithLimits are positive. Engine additionally requires a positive DefaultLimit, MaxLimit, and MaxOffset; an omitted list limit can therefore never produce an unbounded query.

Decoded query bytes include parameter names and values, even for unknown parameters. Filter bytes are rejected before lexing; token and literal bounds then constrain parser allocations and work. Each in or not in list is independently bounded by MaxInValues. Cursor bytes are rejected before base64url/JSON decoding.

Engine.Apply and Session.Apply enforce the receiving endpoint's limits, including for a manually constructed Query or a query parsed by another engine. If the original parser had stricter limits, those remain in force. Original decoded HTTP size (including unknown parameters), filter bytes, and tokens are checked when transferring a parsed query to a stricter endpoint. For a hand-built AST there is no original HTTP representation: AST depth, nodes, paths, sets, literal values, and other structured limits apply instead. Package-level Apply continues to use parser limits or the low-level defaults.

Default sort​

Set Config.DefaultSort to the same syntax as the HTTP sort parameter, for example "-createdAt,name". Every field must be explicitly sortable. New and ValidateConfig reject unknown fields, to-many sort paths, duplicate terms, and sort/path limit violations during startup with invalid_schema.

The default applies to List and engine/session Apply when no client sort was provided. An explicit client sort (including enabled orderby aliases) replaces the default completely. An empty DefaultSort preserves the existing primary-key order. Describe().DefaultSort and the OpenAPI sort schema expose the configured default using only public names.

List fetches one extra row to calculate hasMore. Count is disabled unless AllowCount is true and runs only for count=true. It includes base scope, filter, and search while excluding query sort, limit, and offset. It also excludes cursor position, so every continuation can report the same complete filtered total. Relationship filters use correlated subqueries, so matching child rows do not multiply the root count.

limit=0 executes no data query but may still execute count. Most endpoints should rely on hasMore and enable exact count only when clients need it. When hasMore is true, nextCursor continues after the last returned item.

Stable benchmark baseline​

On the published local reference host (AMD Ryzen 5 2600, Linux amd64, Go 1.26.5), representative v1.0 results were:

Operationns/opB/opallocs/op
parse HTTP query2,5671,74413
parse maximum valid filter53,61176,608158
parse + apply engine plan9,2156,36864
relationship parse + apply15,5339,13583
cursor parse + apply21,69314,106102
SQLite list345,91131,489699

Benchmarks are regression checks, not latency promises. The full command, environment, and additional cases are in the benchmark record.