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 + 1Parameters and arguments
valueA variable, a record field such as
Required: Yesitem.qty, a row column such ase.id, a literal, a function call, a computation such asp.price * p.qty, a comparison, or a??chain"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
| Error | What happened | How to recover |
|---|---|---|
HTQL-4012 | A list written directly after RETURN, for example RETURN [1, 2, 3] | Return a record: RETURN {"list": [1, 2, 3]} |
HTQL-2008 | true or null written directly after RETURN | Put it inside a record |
HTQL-4006 | A name in a returned record has a space or another character that is not a letter, digit, dot or underscore | Rename it |
HTQL-1003 | The statement is not written in HTQL's grammar | Check the record's braces, quotes and commas |
Limitations
- Not supported: a list,
true,nullor 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 < todayreads better than a bare true. - Read several tables in one round trip: one LOOKUP in each LET, then one RETURN that names them all.