Query

In Wow, “Query” covers query models, the server-side Query Gateway, JVM query backends, HTTP/OpenAPI contracts, and remote API clients. Together they form the read path, while retaining separate model, policy, execution, protocol, and caller responsibilities.

Choose a Query Model and Result

Choose by data source and result shape first, then select an entry point:

Model and capability	JVM	HTTP / OpenAPI	API Client
Snapshot data query	Supported	Supported	Supported
Snapshot aggregation query	Supported	Supported	Supported through a separate aggregation API
Event-stream data query	Supported	list, paged, count, and load by version only	Not supported
Event-stream aggregation query	Supported	Supported with JSON/SSE	Not supported

Data queries return snapshot or event-stream documents. Aggregation queries return dynamic tabular rows composed from groups and metrics. See Data Queries and Aggregation Queries for the two result contracts.

Three Entry Points

1. Query Gateway: the server-side policy entry point for query rewriting, filter chains, and result handling.
2. Query Backend: the trusted low-level SPI for aggregate-bound ObjectNode Backends and Factories.
3. Query API Client: the remote snapshot-query entry point with reactive and synchronous interfaces; it currently has no event-stream client.

Execution Chain

The Gateway is the policy boundary for managed queries; calling a Factory directly bypasses it. See Query Gateway for filter applicability, the WebFlux request context, and bypass conditions.

FilterExpression

FilterExpression describes predicates with logical fields; backend adapters own physical paths and capabilities:

{"op": "EQ", "field": "state.status", "value": "CREATED"}

See Filter Expressions for all operators, Element scope, relative time, and backend differences.

Kotlin DSL

val query = pagedQuery {
    filter { pathState { "status" eq "CREATED" } }
    pagination { index(1); size(20) }
}

See Data Queries for query DTOs, projection, sort, pagination, and count. Model-specific paths are documented in Snapshot Queries and Event Stream Queries.

REST API

Snapshots publish data queries and snapshot/aggregation. Event streams publish list, paged, count, load by version, and JSON/SSE event/aggregation. Use the running instance's OpenAPI document for exact paths and scope variants.

POST /sales-order/snapshot/paged
Content-Type: application/json

See Snapshot Queries, Event Stream Queries, Snapshot Aggregation, and Event Stream Aggregation for their routes.

Compatibility and Migration

The canonical V9 JVM contract is FilterExpression and FilterDsl. V9.x temporarily retains deprecated Condition/Operator, ConditionDsl, legacy query constructors, and count client overloads, all normalized to FilterExpression; these compatibility APIs are scheduled for removal in 10.0.0. REST condition/operator input remains compatible during the same window. See V9 Query Migration for the breaking Gateway/Backend JVM mapping, compatibility boundary, and binding migration.

JSON Schema

Generic JSON Schema defines the wire protocol, OpenAPI describes published requests, and runtime Query Model Schema proves logical-field backend capabilities. Snapshots and event streams publish snapshot/schema and event/schema, plus their refresh routes. See Query Model Schema for sources, validation modes, and Provider differences.

Query Gateway Registrars

SnapshotQueryGatewayRegistrar registers SnapshotQueryGateway<STATE> by state type. EventStreamQueryGatewayRegistrar registers aggregate-scoped Gateways without a state type parameter, so multiple candidates are distinguished by Bean name. See Query Backend for exact naming, Backend binding, and raw Factory boundaries.

Next Steps

1. Query Gateway
2. Query Backend
3. Query API Client
4. Filter Expressions
5. Data Queries
6. Snapshot Queries
7. Event Stream Queries
8. Aggregation Queries
9. Snapshot Aggregation
10. Event Stream Aggregation
11. V9 Query Migration
12. Query Model Schema