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 = valueParameters and arguments
nameA letter or an underscore, then letters, digits and underscores:
Required: Yestotal,_draft,order2. A name that starts with a digit is refusedvalueAny of the forms below
Required: Yes
| Value | Example | What the name holds |
|---|---|---|
| A literal | 42, "Perth", true, null | That 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 computation | price * qty + shipping | The result. ^ comes first, then * and /, then + and -; brackets decide otherwise. A whole number stays whole: 3 * 4 is 12 |
| A function | ABS(total - 3) | The function's result. Its arguments may compute |
| A variable or a path into one | order.lines.0.price | A copy of that value |
| A LOOKUP | LOOKUP(entries, FILTER(…), SHOW(…)) | The rows found, as a list of records |
| A default | user.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 list | Example | Gives |
|---|---|---|
| A number | order.lines.0.street | The item at that position, counting from 0, and the path goes on into it. Past the end, null |
| A field name | order.lines.street | That field from every item, as a list |
| A value the list holds | user.tags.vip | That 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
| Error | What happened | How to recover |
|---|---|---|
HTQL-1003 | The statement is not in HTQL's grammar, often a name that starts with a digit | Start the name with a letter or an underscore |
HTQL-2008 | RETURN name on its own, and no LET bound that name | Bind it with LET above the RETURN. Inside a value, an unbound name is null instead |
| A function's own error | A function in the value was given a type it does not take | Give 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.
| Written | Worked out | Example |
|---|---|---|
| Before a read, or in a statement with no read | Once | LET kind = "navLink", then FILTER(contentType = kind) |
| As a LOOKUP that names no row | Once; every row of a read reads the same rows | A list of reference values shared by every row |
After GET(table, alias), over the row | Once for each row | LET label = CONCAT(e.id, " v", e.version) |
| After a GET or in a FOR body, as a LOOKUP filtered by the row's key | Once for each row: that row's child rows | LET items = LOOKUP(entries, FILTER(contentType = t.id)) |
| After a GET, with an aggregate of the alias | Once, over the rows kept so far; the alias stands for all of them | LET newest = MAX(e.version) |
| In a FOREACH body | Once for each row of the loop | See 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.