Variables (LET)

Name a value once and use it wherever the statement needs it.

Syntax

Write LET, a name, an equals sign and a value, one LET to a line. Every statement after it can read the name.

LET name = value

Parameters and arguments

  • name

    A letter or an underscore, then letters, digits and underscores: total, _draft, order2. A name that starts with a digit is refused

    Required: Yes
  • value

    Any of the forms below

    Required: Yes
ValueExampleWhat the name holds
A literal42, "Perth", true, nullThat value. A quoted text keeps every character between the quotes, spaces included
A record{"name": "Ada", "tags": ["vip"]}The record, nested as deep as written
A list[price * 2, 4, "x"]The list; an item may itself be a computation, a record or a variable
A computationprice * qty + shippingThe result. ^ comes first, then * and /, then + and -; brackets decide otherwise. A whole number stays whole: 3 * 4 is 12
A functionABS(total - 3)The function's result. Its arguments may compute
A variable or a path into oneorder.lines.0.priceA copy of that value
A LOOKUPLOOKUP(entries, FILTER(…), SHOW(…))The rows found, as a list of records
A defaultuser.nickname ?? user.name ?? "Guest"The first value that is not empty. ? is the same operator. After a LOOKUP, LOOKUP(…) ?? fallback gives the fallback when no row matches

Reading a variable. A dot follows a path into it, as deep as it goes. After a record, a name is that field: user.address.city. After a list:

After a listExampleGives
A numberorder.lines.0.streetThe item at that position, counting from 0, and the path goes on into it. Past the end, null
A field nameorder.lines.streetThat field from every item, as a list
A value the list holdsuser.tags.vipThat item when the list holds it, otherwise null

Examples

A name held once and read by two values in the answer.

Return type and behaviour

LET returns nothing itself. RETURN name answers the value exactly as it is held: a record stays a record, a list stays a list, a whole number stays whole. A LET that holds a LOOKUP holds a list of records; LENGTH(name) counts them.

Errors and exceptions
ErrorWhat happenedHow to recover
HTQL-1003The statement is not in HTQL's grammar, often a name that starts with a digitStart the name with a letter or an underscore
HTQL-2008RETURN name on its own, and no LET bound that nameBind it with LET above the RETURN. Inside a value, an unbound name is null instead
A function's own errorA function in the value was given a type it does not takeGive it the type it takes, or guard the value with ??
Placement and context

Where a LET is written decides when its value is worked out.

WrittenWorked outExample
Before a read, or in a statement with no readOnceLET kind = "navLink", then FILTER(contentType = kind)
As a LOOKUP that names no rowOnce; every row of a read reads the same rowsA list of reference values shared by every row
After GET(table, alias), over the rowOnce for each rowLET label = CONCAT(e.id, " v", e.version)
After a GET or in a FOR body, as a LOOKUP filtered by the row's keyOnce for each row: that row's child rowsLET items = LOOKUP(entries, FILTER(contentType = t.id))
After a GET, with an aggregate of the aliasOnce, over the rows kept so far; the alias stands for all of themLET newest = MAX(e.version)
In a FOREACH bodyOnce for each row of the loopSee FOREACH

Warning

LETs bind in the order written. A statement reads the names written above it; a name read before its LET is null, never the name's own spelling:

LET a = "person"
LET c = b
LET b = "animal"

Here c is null, because b had no value when c was bound. Write the LET a value depends on first.

Limitations
  • A name is bound once for its stage. Not supported: a LET that reads a value a later LET binds; order the LETs so each reads only what is above it.
  • An aggregate after a GET reads the table's columns. A value another LET computed for each row is not part of it.
  • Not supported: a hyphen in a name or a path step, such as fields.name.en-US. Names hold letters, digits and underscores.
Best practices
  • Use a LET for a value two statements read, or one that drives a LOOKUP. A value read once belongs where it is used: RETURN {"share": 10 / 3} needs no LET.
  • Name a variable for what it holds: navLinks, subtotal, newest.
  • Write the LET a value depends on above it.