DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS /// DOCS
TABLES·FORMULAS AND AI FIELDS

Formulas and AI fields

Two field types compute their value automatically: FORMULA fields evaluate a deterministic expression synchronously whenever a dependency changes; AI fields send an instruction to an AI model and receive a result asynchronously. Both are read-only in the grid — you can't type into them directly.

Formula fields

A FORMULA field holds the result of an expression over other fields in the same table. The expression is evaluated on the Vercel backend every time a record is saved — the result lands back in the cell in under a second.

FORMULA fields have two required settings:

  • expression — the formula string, using {{Column Name}} placeholders to reference other fields.
  • display_as — how to render and filter the result: TEXT, NUMBER, DATETIME, or BOOLEAN. This also determines which filter operators are available on the column.

Optional formatting settings:

  • When display_as = 'NUMBER', all NUMBER formatting options (currency, separators, decimal places) are available.
  • When display_as = 'DATETIME', all DATETIME formatting options (date format, time format, timezone) apply.

If a formula fails for a specific record, the cell shows a red Error indicator. Hover to see the error message.

Formula syntax

Formulas use a small expression language with the operators and functions listed below. References to other columns go inside double curly braces: {{Column Name}}. Names are case-sensitive; leading and trailing whitespace inside the braces is tolerated.

null or missing dependency values coerce to 0 — arithmetic over empty cells short-circuits instead of throwing.

A concat() function is registered for string concatenation.

{{Price}} * {{Quantity}}
{{Status}} == "Approved" ? {{Budget}} : 0
concat({{First Name}}, " ", {{Last Name}})
({{End Date}} - {{Start Date}}) / 86400000

Available operators and constructs: standard arithmetic (+, -, *, /, %, ^), comparisons (==, !=, <, <=, >, >=), logical (and, or, not), ternary (a ? b : c), and the built-in functions abs, ceil, floor, round, min, max, pow, sqrt, log, ln, exp, if, concat, substr, length, lower, upper, trim, replace, indexOf, and slice.

Dependency rules

The dependency graph is validated at save time:

  • A FORMULA column cannot reference itself.
  • Circular dependencies are rejected (FORMULA A → FORMULA B → FORMULA A is invalid).
  • Dependency chains deeper than 3 levels are rejected.
  • Referencing a column name that doesn't exist on the table is rejected.

When you rename a column that other formulas reference, every dependent {{Old Name}} placeholder is rewritten to {{New Name}} in the same database transaction — no manual edits needed.

AI fields

An AI field holds a value generated by an AI model. You write an instruction (a prompt) in plain text, reference other fields using {{Column Name}}, and the model fills in the cell based on the record's data.

AI fields have these settings:

  • instructions — the prompt sent to the model. Use {{Column Name}} to include field values. For example: Summarize the following support ticket in one sentence: {{Description}}.
  • auto_update — when enabled (default), the field re-evaluates automatically whenever a dependency changes. Disable this if you want to trigger regeneration only manually.
  • output_schema — an optional structured-output JSON schema. When set, the model returns a JSON object instead of plain text; the cell displays the JSON in monospace, truncated to 80 characters.

AI fields and FORMULA fields cannot reference each other. Cross-runtime dependencies are rejected at save time.

AI field types

The instructions field is free-form, so you're not limited to a fixed list — you can ask the model to do anything. Common patterns:

PatternExample instruction
SummarizeWrite a one-sentence summary of: {{Notes}}
ClassifyClassify this support ticket as Bug, Feature Request, or Question. Reply with one word only. Ticket: {{Body}}
ExtractExtract the company name from this email signature: {{Signature}}. Reply with only the company name.
TranslateTranslate the following text to English: {{Content}}
ScoreRate the sentiment of this review from 1 (very negative) to 5 (very positive). Reply with a single digit. Review: {{Review Text}}
Structured outputUse output_schema to get a JSON object back — for example, extract multiple named fields from unstructured text in one pass.

For structured output, set output_schema to a JSON Schema object. The model is instructed to match the schema; the cell value is stored as a JSON object.

When AI fields recompute

An AI field evaluates in two situations:

Automatic (when auto_update is true):

When a record is saved and any field that the AI column depends on has changed, the database trigger (trg_enqueue_ai_field_generation) inserts a job into the ai_field_generation_jobs queue and sends a fire-and-forget push to the onnie-engine. The engine claims the job, resolves placeholders, calls the model, and writes the result back. The cell shows a pulse icon while the job is pending.

If the initial push is missed (network failure, etc.), a pg_cron sweep runs every minute to pick up unclaimed pending jobs older than 30 seconds.

Manual (always available):

Hovering a pending or completed AI cell reveals a Regenerate button. Clicking it enqueues a new job regardless of the auto_update setting. If a job is already in flight for that cell, the button returns the existing job rather than creating a duplicate.

Bulk recompute:

Bulk recompute on instruction changes is not currently implemented for AI fields. To refresh a cell's value after updating instructions or output_schema, use the per-row Regenerate button. (Formula bulk recompute, triggered by column renames, is handled separately and runs automatically.)

//NOTE

The auto_update = false setting only suppresses the automatic trigger. The manual Regenerate button always works regardless of this setting.

Cost and credit accounting

AI field evaluations consume workspace credits. Each model call for an AI field deducts from your workspace's credit balance. The number of credits per call depends on the model tier and the length of the resolved instruction.

Plan limits:

  • Workspaces on free plans have a monthly credit cap. When the cap is reached, AI field evaluations stop enqueuing until the next billing cycle (or until you upgrade).
  • Paid plans have higher caps or unlimited evaluations depending on the tier.

Bulk recomputes can consume a large number of credits quickly if the table has many records.

//WATCH OUT

Disabling auto_update on a high-cardinality AI column is a good way to control credit usage — you regenerate only when you need fresh values.