Virtual fields

Cell states, limits, and reads

What each computed, related and collection cell can show, the partial-value marks, preview outcomes, limits, time limits, read accounting, storage and plans.

Plan availability

Plan Virtual fields and table links Applies to, Describe it, suggested query links
Free No No
Pro, Team, and a trial Yes Yes
Sample mode, on any plan Yes Yes

Virtual fields need the virtualFields gate. Applies to, Describe it and suggested query links also need the dataModel gate, and Describe it needs an AI provider for completions. Both gates come with every paid plan and the trial. On a plan without the gate, such as one that lapsed, the stored fields and links stay saved, the grid shows none of them, and each entry point shows a lock and opens the upgrade page. Until entitlements load, the grid offers neither.

Where definitions are stored

Field and link definitions live in Dynomatic’s local SQLite database, dynomatic.db, beside the rest of its settings. See Security and data for where that file is. Nothing is written to DynamoDB.

  • A field is stored with its name, its scope (one table, one workspace, or every workspace), its expression, preset or loaded-rows settings, the items it applies to, and its display format.
  • A link is stored with its source table, its name, its target workspace and table, the target’s key schema, and how it reads.
  • A column’s position and visibility are saved in the table’s settings. Dismissed suggestions are saved per table.
  • Deleting a workspace deletes its fields and links, and the links from other workspaces’ tables into it. Those links’ related columns stay, with Link missing.

Computed cells

State What the cell shows
Value The value, drawn like an attribute or in the field’s display format
No value An empty cell. The expression returned nothing for the item
Does not apply A dimmed dash. The field applies to another Data Model entity
Error An error icon and Error. The tooltip holds the message
Not evaluated yet A muted ellipsis

A pending edit to an attribute re-evaluates the row’s cells from the edited item before you commit. A cell that ran past its time limit keeps its error until the query runs again or the field’s expression changes.

State What the cell shows
Value The attribute’s value from the related item. A found item without the attribute gives an empty cell
Loading A small spinning mark
No match A dimmed No match. The key was read and no item has it
No key An empty cell, and nothing is read. A mapped attribute is missing, has another type than the key, is an empty string, or is longer than DynamoDB allows in a key, or a key expression gave no value
Throttled or capped A warning mark. DynamoDB still throttled the key after retries, or the read passed a cap. The tooltip says which
Link error A red error mark. The tooltip names the cause: credentials that may not read the table, a table missing from the account and region, a key that changed since the link was saved, a failed key expression, a target workspace that cannot be read, a timeout, or another read failure

A related column whose link is gone says Link missing under its name, and each cell shows an error. A collection cell’s timeout is an error, never a count of 0.

Sort, search, the loaded-rows filter and Copy Value treat No match and No key as no value, and the warning states as errors.

Partial-value marks

A collection cell over a query link covers only the row’s first items, as many as the link reads per row. When the row has more, the cell carries a mark until Compute Exact reads them all.

Mark Display Meaning
10+ Count At least this many items. The number is the link’s items per row
+ Chips The row has items the cell has not read
≥ Aggregate The full value can only be larger. Used when the expression’s outermost call is $count or $max, or $sum over terms that are all zero or more
~ Aggregate Any other value over the first items only

In a currency format, a total over the first 10 lines that sums to 412 shows ≥$412.00. The cell’s tooltip says how many items the value covers.

Preview outcomes

Outcome What the preview shows Save
A value The row’s value in the chosen format. 0 and false are values Allowed
No value No value. The expression returned nothing for that item Allowed
Compile error The engine’s message under the editor, and The expression does not compile. Blocked
Runtime error on a row That row’s message, and a count such as 3 of 20 previewed rows give an error. Allowed
No rows loaded No rows loaded. The expression compiles. Allowed

When more than half the previewed rows have no value, the status line says how many, as in No value on 15 of 20 previewed rows. 5 of the 100 loaded rows checked give a value.

Where computed values appear

Surface What it shows
Results grid Every field as a read-only column after the attributes
Item view A read-only Computed group after the attributes, in Document mode only. It follows your draft before Save. Fields computed across loaded rows are left out
Compare A Computed group that compares stored values. Fields computed across loaded rows are left out
Export A Computed section of fields to export. See Export computed columns
MCP See below

Agents over MCP

  • query, scan and get_item take includeVirtualFields: true and return each item’s computed values under virtual, beside the items. Without the flag the answer is unchanged. batch_get_items does not take it.
  • list_virtual_fields lists a table’s fields, its links, and the fields a narrower one hides. It reads no items and needs the Inspect capability.
  • A collection field comes back as { kind: "collection", items, more }, the row’s first items and whether it has more. $relatedAll reads every item, up to 1,000.
  • Before a link’s first read, Dynomatic judges the agent’s read of the target table as the tool’s own read, in the target workspace. A link to a table the agent may not read items from gives its cells the withheld error and sends nothing to that table.
  • A field computed across loaded rows is listed with no key and never computed.
  • includeVirtualFields and list_virtual_fields need the Virtual Fields gate.

Limits

Limit Value
Rows the field preview evaluates The first 100, or up to 100 selected rows. It lists 20
Suggested fields Up to 6, from the first 500 loaded rows
Fields in one Copy fields as JSON 100
Items per row on a query link 1 to 25. The default is 10
Chips shown in a chips column 1 to 10. The default is 3
Items read for one row by Compute Exact, Read every value, $relatedAll, an export, or One row per related item 1,000 items or 16 MiB
Keys in one BatchGetItem request 100
Unique keys in one batch of rows 1,000
Elements read from one row’s list 100
Key length 2,048 bytes for a partition key, 1,024 for a sort key
Distinct key conditions in one read 100. Rows past that wait for a later read
Queries running at once against one target table 4, across the whole app
Retries for unprocessed or throttled keys 8 rounds, with backoff
Results whose related items Dynomatic holds The 32 most recently used, each with up to 8 MiB of linked items and 16 MiB of query-link items. The oldest drop first, and a dropped item costs one read again
Text $gunzip returns 1 MiB
Sub-grid 10 item rows before it scrolls, and up to 12 columns
Suggested links The top 3 candidates, each confirmed with a read of at most 10 rows, shown when at least 8 found an item
Suggested query links The top 3 candidates, each confirmed with a read of at most 5 rows

Time limits

Time limits apply to a batch of rows, not to one cell. The time is shared among the fields still to run, and a field that runs out gives its remaining rows The expression did not finish before its time limit.

Surface Limit
Results grid 250 ms per batch of up to 100 rows, after up to 10 s for related reads
Export 10 s per page to compute, and 30 s per page for related reads
MCP call 10 s. When the call reads links, 7 s go to reads and 3 s to computing
Link dialog preview 10 s

Because each surface has its own limit, a slow field can time out in the grid and finish in an export.

The cost strip under the Filters builder shows Related reads beside Actual, such as Related reads: 4 RCU in 2 requests. When no response reports consumed capacity, it counts requests only, as in Related reads: 2 requests, no capacity reported.

The cost strip with Actual and Related reads

The figure adds up every related read the tab made since its last refresh:

  • related columns and $related expressions in the grid, the item view and compare
  • query links, from collection cells, $related and $relatedAll, Compute Exact, the peek, the sub-grid and One row per related item
  • the field dialog’s and the link dialog’s previews
  • the checks that confirm suggested links

A refresh starts the figure over. Related reads never add to Actual or to Command history. An export’s row in the Transfers panel shows its own related reads, such as Related reads: 3 RCU. Reading a target table’s key schema with DescribeTable reads no items and is not counted. Why related values can be partial explains which reads a link issues.

Last updated on