Returning results (RETURN)

Say exactly what you want back.

Syntax

Write RETURN and the value to answer with: a variable, a row column, a computation, or a record of names and values.

RETURN variable
RETURN alias.column
RETURN {
  "name": value,
  "other": {"nested": value}
}
RETURN a * 2 + 1

Parameters and arguments

  • value

    A variable, a record field such as item.qty, a row column such as e.id, a literal, a function call, a computation such as p.price * p.qty, a comparison, or a ?? chain

    Required: Yes
  • "name"

    In a record, the key a value appears under in the answer. Letters, digits, dots and underscores

    Required: In a record

A value in a record may itself be a record or a list, nested as deep as you need, and a list item may be any value including a computation. In a GET, a row column is written alias.column, and a dot goes on into a JSON column: e.fields.title.

Examples

Three values under the names you choose.

Return type and behaviour

RETURN with a variable returns its value as it is: after LET name = "Ada", RETURN name answers "Ada", and a variable holding a record, a list or rows answers with them. RETURN with a record returns that record, and a record with a single field keeps the whole value of that field: {"o": o} answers the whole of o.

Several RETURN statements in one request answer with a list holding one result for each. In a GET, RETURN shapes each row. In a FOREACH loop, RETURN shapes each row of the loop.

RETURN with a single column and no braces, RETURN e.id, answers a plain list of that column's values. RETURN with a bare computation, such as RETURN 3 * 4, answers {"result": 12}.

Names you choose come back in camelCase. See Identifiers.

Errors and exceptions
ErrorWhat happenedHow to recover
HTQL-4012A list written directly after RETURN, for example RETURN [1, 2, 3]Return a record: RETURN {"list": [1, 2, 3]}
HTQL-2008true or null written directly after RETURNPut it inside a record
HTQL-4006A name in a returned record has a space or another character that is not a letter, digit, dot or underscoreRename it
HTQL-1003The statement is not written in HTQL's grammarCheck the record's braces, quotes and commas
Limitations
  • Not supported: a list, true, null or text written directly after RETURN. Put it in a record, RETURN {"ok": true}, or hold it in a variable and return the variable.
  • Not supported: a ?? chain written directly after RETURN. Put it inside a record: RETURN {"v": a ?? "x"}.
  • A record's names are quoted text made of letters, digits, dots and underscores.
Best practices
  • Return one variable on its own; give values keys when the caller reads several by name.
  • Build the nested shape your code expects in the RETURN, so the response needs no reshaping.
  • Return only the fields you need.
  • Name the question in the key: "isOverdue": due < today reads better than a bare true.
  • Read several tables in one round trip: one LOOKUP in each LET, then one RETURN that names them all.