Skip to content

Query Semantics

This document defines how Apistry interprets and executes query parameters. These rules are enforced consistently and are observable by clients.

Offset & Limit

  • offset represents item skip, not page number
  • limit defines the maximum number of items returned
  • Paging is not supported on sub-resources

Defaults may be applied by the runtime.

Pagination Metadata and Count Behavior (Important)

Apistry computes pagination metadata based on the expected response shape.

Count Computation

When pagination metadata is implied, Apistry performs:

  1. A data fetch (get)
  2. A total count (count)

This results in two database operations.

This behavior is deterministic and intentional.

Why Count Is Always Evaluated

The runtime treats pagination as active when:

  • limit is defined, or
  • offset is defined

Because limit is always defined internally, pagination metadata is always implied unless explicitly avoided by response design.

As a result: - a total count query is executed - even if the client does not explicitly request it

Performance Implications

  • Count queries may be expensive on large collections
  • Count queries require an additional database round trip
  • For high-throughput read APIs, this may be undesirable

This is not a bug — it is a tradeoff in favor of response completeness.

Avoiding Count Overhead

If a response does not require pagination metadata, teams should:

  • design a response schema that does not include paging wrappers
  • avoid contracts that imply total-count semantics
  • treat pagination metadata as an explicit cost

Apistry does not attempt to infer intent dynamically.

Supported Operators

  • eq, neq
  • gt, gte
  • lt, lte
  • in, nin
  • isNull, isNotNull
  • wildcard matching (when enabled)

Operators are evaluated per-field and validated against schema.

Constraints

  • Queries are schema-validated
  • Only fields explicitly marked queryable may be filtered
  • Type coercion applies only to query parameters

Delete-many uses GET filters

Delete-many operations reuse the same query filter semantics as GET for selecting items. This means the same operators, coercion rules (for query params), and field allowlists apply.

Duplicate handling (cross-reference)

Duplicate behavior is explicit and schema-driven:

  • Primitive arrays: uniqueItems: true rejects duplicates; otherwise duplicates are allowed.
  • Object arrays: no implicit duplicate detection without explicit alternate keys.
  • Top-level resources: uniqueness is typically enforced by database indexes (if present).

Summary

  • Pagination implies total count
  • Total count implies an additional database call
  • This behavior is deterministic and response-driven
  • Performance tradeoffs are explicit and opt-in by design
  • Queries are declarative and validated.