Virtual fields
Expression reference
Where JSONata expressions run in virtual fields and links, what each place can read, and every function Dynomatic adds to JSONata.
Virtual fields and table links use JSONata, a query and transformation language for JSON. The JSONata documentation is the reference for the language, its operators and its built-in functions.
Where expressions run
| Place | Typed in | Reads |
|---|---|---|
| Field expression | The field dialog’s Expression tab, or written by a preset | The current item |
| Link key expression | A key row of the link dialog, with ƒx | The source row. On a link that reads items from a list, each element as $value |
| Collection aggregate | Add Aggregate in the link dialog | The row’s related items, as $items |
| Across loaded rows | Value, Key and Within each (optional) on the Across loaded rows tab | Each loaded row, one at a time |
$related and $relatedAll work in a field’s expression. A link’s key expressions and a field computed across loaded rows cannot call them.
Read an attribute
Name an attribute by its path, with no $: status, orbit.periodMin, or a name in backticks when it holds a space or a dash, such as `order-id`. An attribute the item does not hold gives no value, so the cell is empty rather than an error.
Values arrive as plain JSON, not DynamoDB JSON, so orbit.periodMin reads a number inside a map.
A path can also start at $, the item at the top level and the current element inside a filter, or at $$, which is always the item.
Values Dynomatic supplies
| Name | Where | Holds |
|---|---|---|
$value |
A link key expression on a link that reads Items from a list | One element of the row’s list or set. Orbit’s stations link keys each station with $value |
$items |
A collection aggregate | The row’s related items, as a list. Over a partial read it holds only the first items, as many as the link reads per row |
$related and $relatedAll
$related("name") returns what the table’s link of that name reads for the row.
- On a link that reads One item, the item, or no value when nothing matched or the row has no key.
- On a link that reads Items from a list, a list of the items found.
- On a query link, the row’s first items as a list, as many as the link reads per row.
$relatedAll("name") reads a query link’s items for the row to the end before the field is computed, and returns every item. On any other link it returns what $related returns. A row with more than 1,000 items, or more than 16 MiB of them, gives an error, never part of the items.
Both take the link’s name as a string literal, so that Dynomatic knows every link a page reads before it evaluates. A field reads only the links its own text names.
The Orbit sample uses each one. On OrbitPasses, Share of onboard storage divides the pass’s data by its satellite’s storage.
bytesDown / $related("satellite").storageBytes
On OrbitGroundStations, Satellites served counts the distinct satellites across every pass of the station.
$count($distinct($relatedAll("passes").satelliteId))
On OrbitSatellites, the Data downlinked collection column adds up the passes read so far.
$sum($items.bytesDown)
Dynomatic functions
These functions work beside JSONata’s own in a field’s expression. Scripts cannot call them. The editor completes each one after $ with its signature and an example. The grid, export and agents return the same output for the same item.
| Function | Returns |
|---|---|
$itemSize() |
The item’s size in bytes, by DynamoDB’s rules, from the stored types |
$capacityUnits() |
{ read, write }, the strongly consistent read units (4 KB steps) and standard write units (1 KB steps) for one access to the item, each at least 1 |
$hash(value?) |
The lowercase hex SHA-256 of the item, or of a value when you pass one, with keys sorted first |
$decodeBase64(text) |
The UTF-8 text a base64 string holds. Unlike JSONata’s $base64decode, invalid input is an error |
$gunzip(text) |
Base64 gzip decompressed into text, up to 1 MiB |
$geohashDecode(geohash) |
{ lat, lon }, the center of the geohash cell |
$consoleUrl(arnOrS3Uri) |
The AWS console page for an ARN or an s3:// URI, in the ARN’s region. Unrecognized text gives no value |
$vectorNorm(numbers) |
The Euclidean length of a list of numbers |
$cosine(a, b) |
The cosine similarity of two lists of numbers of the same length |
$now() |
The current time in ISO 8601, fixed for one result set |
$millis() |
The current time in epoch milliseconds, fixed for one result set |
$var(name) |
The value of a plain environment variable for the table’s tier and workspace. Templated and secure(...) values are refused |
$indexes() |
The global secondary indexes the item appears in, from the table’s schema registry entry. Local secondary indexes are not listed |
$related(link) |
What the named link reads for the row. See above |
$relatedAll(link) |
Every item a query link reads for the row. See above |
$now() and $millis() give every row of one grid result the same time. Running the query again renews it. An export uses its start time, and an agent’s call uses its own.
The Orbit sample decodes a satellite’s telemetry with $eval($gunzip(telemetry)).tempC, and builds a station’s map coordinates with $geohashDecode(geohash). $eval is standard JSONata.
Function errors
A Dynomatic function that cannot answer gives the cell an error with one of these messages. Each has a code.
| Code | Message |
|---|---|
| VF001 | $name expects text. |
| VF002 | $name expects a list of numbers. |
| VF003 | The text is not valid base64. |
| VF004 | The decoded bytes are not UTF-8 text. |
| VF005 | The data is not gzip. |
| VF006 | The decompressed text is larger than 1 MiB. |
| VF007 | The geohash is empty or holds a character outside the geohash alphabet. |
| VF008 | $cosine needs two lists of the same length. |
| VF009 | $cosine needs lists that hold at least one number. |
| VF010 | $cosine has no answer for a list of zeros. |
| VF011 | $name overflowed to a number JSON cannot hold. |
| VF012 | No variable named stage is set for this table. |
| VF013 | The variable stage holds a template, and $var reads only plain values. |
| VF014 | The function cannot read the table’s variables or schema, and the message names why |
$name stands for the function that failed, and stage for the variable you named.
Link errors in an expression
These messages come from $related and $relatedAll in a field’s expression.
| Message | Cause |
|---|---|
$related takes its link's name as a string literal, such as $related("customer"), so every link a page reads is known before it evaluates. |
The name was passed another way, such as in a variable. Nothing is read for the field |
No link named customer was read for this row. Name a link of this table as a string literal: $related("customer"). |
The table has no link by that name, or the name reached $related only while the expression ran, such as through $eval |
Link passes has more than 1,000 items for this row, and a read of all of them stops at 1,000. |
$relatedAll passed the item cap |
Link passes has more than 16 MiB of items for this row, and a read of all of them stops there. |
$relatedAll passed the size cap |
Link satellite was throttled for this row. |
DynamoDB still throttled the key after retries |
Link satellite read too many keys for this row. |
The read passed a key cap, such as more than 100 elements in one row’s list |
A link that cannot read at all, because of credentials, a missing table, a changed key, a signed-out workspace, or a timeout, gives every cell of the link an error that names the cause. Cell states, limits, and reads lists those states.
An expression that runs past its time limit gives The expression did not finish before its time limit.
Last updated on