Qirava DMS docs

Response: RETURN custom shaping

By default a SELECT returns each row as a flat object of its fields (or the projected subset). RETURN { ... } lets you reshape the output per row: rename fields, embed literals, nest objects, and call functions — producing exactly the JSON shape your client wants without post-processing. The shape is an ordered set of alias: value entries, where the value is a field reference, a literal, a nested shape, or a function call. This page covers the four value kinds and shows the resulting envelope.

RETURN syntax#

Append RETURN { alias: value, ... } to a SELECT. Each entry maps an output key (alias) to one of four value kinds. The aliases (and their order) define the shape of each row object in data. RETURN replaces the default projection for shaping; count still reflects the number of rows.

Field: a bare identifier — copies that field from the row (who: name). Missing fields become null.
Lit: a literal value — embeds a constant in every row (tag: "x", version: 2).
Nested: a nested { ... } shape — builds a sub-object per row (info: { years: age }).
Call: a function call — fee: myns.fee(2); the call's result is embedded (calls are evaluated once per query, see below).

Projection, rename, nest, embed#

Request

-- users has a row { _id: 1, name: "alice", age: 30 }
SELECT * FROM users RETURN { who: name, info: { years: age }, tag: "u" }

Response

{
  "error": null,
  "data": [ { "who": "alice", "info": { "years": 30 }, "tag": "u" } ],
  "root": { "count": 1 }
}

Function calls in a shape#

A shape value can be an inline function call (alias: ns.fn(args)). Inline calls take literal arguments and are CONSTANT per query: the engine evaluates each distinct call ONCE (pre-evaluating both projection calls and shape calls) and embeds the cached result into every row. The same mechanism powers calling imported function packages from a plain SELECT (e.g. SELECT math.double(21) FROM t).

Request

SELECT * FROM t RETURN { x: name, doubled: math.double(21) }

Response

// each row -> { "x": <name>, "doubled": 42 }

Notes#

Aliases preserve declared order in the output object.
A field reference to an absent field yields null.
RETURN composes with WHERE/SORT/LIMIT/JOIN — the shape applies to the final rows.
Aliases may be quoted strings if you need a key that isn't a bare identifier.