Queries

A frontend needs lists, lookups, and live views, and each one normally means a route, argument parsing, paging code, and a response shape to keep in step with the client. In Arc, a query is a static method on a read model. Arc supplies the route, binds the arguments, pages and sorts the result, and, for a live query, streams updates to every subscriber.

A query

@readModel()
export class TaskItem {
    @field(TaskId) id!: TaskId;
    @field(TaskTitle) title!: TaskTitle;

    @query(service(Tasks))
    static allTasks(tasks: Tasks): TaskItem[] { return tasks.all(); }
}

This excerpt is from the Tasks sample read model. GET /api/tasks/listing/all-tasks answers with a query result whose data holds the tasks.

A read model here is a class describing the shape of what you return. Where the data comes from is your choice: an in-memory service, MongoDB, SQL with Drizzle, or a Chronicle projection.

Find your way

Page	Use it when you want to
Model-bound queries	Declare read models, query methods, and their parameters
Query arguments	Bind named, optional, and repeated arguments from the query string
Paging and sorting	Page and sort in memory, or return a page your data source cut
Query validation	Validate arguments together with QueryValidator
Query pipeline	Understand the order of checks and result processing
Using the HTTP QUERY method	Send structured arguments in a body
Observable queries	Serve a snapshot and live updates from the same route
Subscribe to an observable query	Receive updates over SSE, a WebSocket, or the @cratis/arc client
Multiplexed observable queries	Share one WebSocket or SSE connection across many subscriptions
Observable emission guards	Re-check access for every emission
Query health	Inspect the caller’s own hub connections
Using observable queries with curl	Explore a live query from a terminal
Query renderers	Turn a provider-owned value into data or a page
Read-model interception	Transform read-model instances before they reach the wire