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("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.

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