Calculated Fields

Celiq has two distinct calculated-field mechanisms. They look similar but live in different places and behave differently. This page explains both so you pick the right one and know where each value comes from.

Overview

A calculated field takes an expression like [revenue] / [orders], substitutes the values of the referenced fields, and evaluates simple arithmetic to produce a new number. The reference syntax is square brackets around a field name, and the supported operators are +, -, *, /, and parentheses.

The two mechanisms are:

Both produce extra numeric columns in your results. The difference is durability and scope: one is part of the model, the other is a throwaway helper for a single exploration.

When to use it

• Use a Discover session calculated field when you are exploring and want a quick derived number — a ratio, a difference, a per-unit value — for this result set only. It is the fastest path and needs no modeling permissions.
• Use a node-persisted calculated field when the derived value belongs to the data model itself and should travel with the node. Because it is stored on the node and clears the query cache on save, treat it as a modeling change, not an exploration tweak.

Concepts

• Expression — the formula, e.g. [revenue] / [orders]. Field references use [field_name] and are replaced with the numeric value before evaluation.
• Label — the human-readable name shown as the column header (e.g. Revenue per Order).
• Format — how the value is displayed: Number, Currency ($), or Percent (%).
• Selected vs defined — in Discover you can define several calculated fields but only the ones you select (toggle on) are added to the result. Defining a field does not automatically add it to your output.
• calculated_fields (node column) — a JSONB array on the nodes table holding the persisted definitions for that node.

Getting started

• A connected warehouse and at least one domain and reveal you can explore (see Discover).
• For node-persisted fields: a Weaver, or higher, role.

For Discover session calculated fields, open Discover, choose a domain and reveal, and look at the field panel on the left. Below the dimensions and metrics you will see a CALCULATED section header (marked with an ƒ badge) and a count of how many calculated fields you have defined.

Node-persisted calculated fields are not authored through a screen in the field catalog — there is no dedicated calculated-fields catalog tab. They are written by sending the definitions to the node via the semantic API.

Step-by-step

For node-persisted calculated fields, a Weaver sends the full array of definitions for a node to PATCH /api/semantic/nodes/:id/calculated-fields. The body must contain a calculated_fields array; a non-array body is rejected with 400. On success the definitions are stored on the node and the query cache is invalidated so later queries reflect the change.

Examples

A Discover session calculated field for revenue per order, formatted as currency:

{
  "label": "Revenue per Order",
  "expression": "[revenue] / [orders]",
  "format": "currency"
}

How it evaluates per row: each [field] reference is replaced with that row's numeric value, then the arithmetic runs. A row with revenue = 12000 and orders = 300 yields 40, displayed as $40 under a Revenue per Order column.

A node-persisted set of calculated fields sent to the semantic API:

{
  "calculated_fields": [
    { "label": "Revenue per Order", "expression": "[revenue] / [orders]", "format": "currency" },
    { "label": "Return Rate", "expression": "[returns] / [orders]", "format": "percent" }
  ]
}

Best practices

• Reference only fields present in the result. The expression evaluates against the current row; a referenced field that is not in the result resolves to 0.
• Keep expressions arithmetic. Only digits, whitespace, and + - * / ( ) are allowed. Anything else (functions, text, comparisons) is rejected and the field shows no value.
• Match the format to the meaning. Use Currency for money, Percent for ratios you want shown as a percentage, Number for plain counts and rates.
• Prefer a metric for shared, durable logic. If many people need the same derived number across many charts, model it as a Metric instead of recreating a session field each time.
• Treat node-persisted edits as modeling changes. Saving them clears the query cache for the workspace, so coordinate with other Weavers as you would any model change.

Tips

Common mistakes

Troubleshooting

Related pages

• Metrics
• Dimensions
• Discover
• Forge