Queries in the document

A client calling allTasks wants to know which arguments it may pass, whether it can ask for page two sorted by title, and what shape the rows have. Arc describes each query as a GET operation with its arguments, the paging and sorting parameters the runtime honors, and the QueryResult envelope around the data.

One GET operation per query

The Tasks sample’s TaskItem.taskById query appears as GET /api/tasks/listing/task-by-id with operationId Tasks.Listing.TaskItem.taskById and tag Tasks.Listing. Queries accept HTTP QUERY too, but OpenAPI has no path item for that method, so the document lists GET only.

Each query argument becomes a query parameter. required comes from the input schema: an argument declared with argument(name, Type, { optional: true }), or a Zod field that accepts undefined, such as one with .optional() or .default(...), is not required. taskById(id: TaskId) has one required parameter, id, described as a UUID string.

Paging and sorting parameters

Arc adds four parameters to a query whose result pages:

Parameter	Schema
`page`	integer (`int32`), minimum 0
`pageSize`	integer (`int32`), minimum 1
`sortBy`	string
`sortDirection`	`asc`, `ascending`, `desc`, or `descending`

A query’s result pages when its return is declared as an array or a queryPage result, through generated metadata or generatedReturn on a low-level definition. A query declared to return one item, such as taskById, or nothing, gets no paging parameters, and neither does a query whose return Arc doesn’t know or a renderer-backed query: the runtime still pages those, but the document only advertises what it can prove. allTasks returns TaskItem[], so it lists all four. See Summaries and result types need generated metadata for declaring generatedReturn.

page, pageSize, sortBy, and sortDirection are reserved query-string names, compared case-insensitively: Arc reads them as paging and sorting and removes them before binding the query’s arguments, so a query argument with one of these names never receives the value. Name your own arguments differently.

These parameters describe what a client may send. How a query honors them depends on its result; see Paging.

Observable queries

An observable query, such as observeAllTasks, adds two parameters and three responses:

Addition	Meaning
`waitForFirstResult`	boolean; wait for the first value instead of answering 202
`waitForFirstResultTimeout`	number of seconds, greater than 0 and at most 120
200 `text/event-stream`	The Server-Sent Events stream, next to the JSON snapshot
202	No current value yet
408	The first-result wait timed out
503	The subscription limit was reached

WebSocket and multiplexed hub transports are not described. Using observable queries with curl shows each HTTP answer.

Responses

Every query documents 200, 400, 403, and 500, all with the QueryResult envelope, and 401 when authentication can reject the request (see 401 responses). It carries the same correlationId, isSuccess, isAuthorized, isValid, hasExceptions, validationResults, exceptionMessages, and exceptionStackTrace properties as a command’s envelope, plus:

Property	Type
`isReady`	boolean
`paging`	`{ page, size, totalItems, totalPages }`, all integers
`data`	The result type; 200 only, and only when generated metadata declares it

data follows the result’s cardinality. allTasks has an array of TaskItem objects. taskById returns TaskItem | undefined, so its data is anyOf the TaskItem object and null. Result object schemas set additionalProperties: false.

Error envelopes (400, 403, 500, and the observable 202, 408, and 503) never include data.

Differences from Arc on .NET

The sort parameter is sortBy. The .NET transformer names it sortby.
Required arguments are marked required: true. The .NET model-bound transformer marks every argument optional.
Paging parameters follow the declared result, not a runtime enumerable check.