Calculated fields

Sometimes the value you need is not already on the model — for example area in a different unit, a simple “yes / no” label, or a custom group such as “small / medium / large”. Calculated fields let you create that value once, then use it in charts, tables, filters, and colour-by — the same way you pick Category or Level. In this section:

• Create a calculated field
• Who can use the field
• Choose what the field should do
• Use the field in your dashboard
• Build one field on top of another
• Things to watch out for

​

Create a calculated field

Open a dashboard in edit mode. In the left sidebar, open Calculated Fields (calculator icon). Outcome: The new value is available to pick in widgets and filters, without republishing the model.

​

Who can use the field

When you save a field, you choose how widely it is shared:

• Remove from this dashboard — stop using a shared field here; it stays in the library.
• Delete from library — remove a shared field so others cannot use it either.
• Delete field — remove a field that only exists on this dashboard.

​

Choose what the field should do

You do not need to know formulas or spreadsheet functions. Pick the option that matches what you want the dashboard to show. These names match the tabs in the editor.

​

Arithmetic

Add, subtract, multiply, or divide values from the model — for example combine two areas, or check whether one number is larger than another. You write a short formula with letters such as a and b, then tell Speckle which model property each letter means. If a value is missing, the result is blank.

​

Aggregate

Get one figure for the whole data set — for example a total area or an average height — not a different number on every element. Choose All data for a fixed total, or Current view if the number should follow dashboard filters. That figure is useful when you later divide each element’s value by the total (for example to show a share of the whole). For a full walkthrough, see Show each element’s share of the whole.

​

Unit conversion

Show a number in a different unit — for example feet to metres, or square feet to square metres. Pick the property, then choose a ready-made length or area conversion, or enter your own multiplier. The unit label is for display only.

​

Grouping

Inside Grouping, choose Range groups or Value groups. Use Range groups when you have a number and want labels such as “under 10”, “10 to 50”, and “over 50”. Use Value groups when you have text (for example type names) and want to roll several values into one label, such as “external walls”. Anything outside your groups gets the fallback label you set.

​

Null fallback

Use this when a property is sometimes blank and you still want a usable value in charts and filters — for example show “Not set” when fire rating is missing. Keep the property when it has a value. When it is empty or missing, show the replacement you choose.

​

Map lookup

Turn a code or short name on the model into a clearer label using a lookup table. Pick the model property, the table, the column to match, and the column to show. Unmatched values use your fallback. You can import a CSV or Excel file from this dialog (Import new table if tables already exist), or manage tables from Lookup tables in the sidebar.

​

Logical

Label each element with your own words — for example “Compliant” / “Needs review” — based on rules you set (the same kind of conditions you use in filters). The element gets the pass label only when every condition is met. Otherwise it gets the fail label. For full rulesets and detailed results, use Validation widgets instead.

​

Coalesce

Use this when the same idea might live in different properties on different elements — for example one model stores area under one name, another under a different name. List the properties in order. Speckle uses the first one that has a value.

​

Use the field in your dashboard

Once the field is on this dashboard, treat it like any other property:

• Pick it when you set up a chart or table (what to total, what to group by, and so on)
• Use it in filters
• Use it to colour the model

Nothing is written back to Revit, Rhino, or the Speckle model. The value only exists while you work in the dashboard.

​

Build one field on top of another

You can create a second calculated field that uses the first one — for example convert units first, then put the result into ranges. If two fields depend on each other in a loop, Speckle will not let you save that setup.

​

Things to watch out for

Calculated fields are still being exercised against every widget type. A field can look fine in a table and look wrong in another widget. When something seems off, check the combination below before trusting the number.

​

Ratios and totals can “count twice”

Some widgets (including Ratio Value and Ratio Value by Property) work by adding up a number once per element, then dividing. An Aggregate calculated field already is a total — and that same total is written onto every element. If a ratio widget adds it up per element, the result can be far too large (roughly the real total multiplied by how many elements you have). Safer patterns today:

• For “share of the whole”, use Aggregate + Arithmetic as in Show each element’s share of the whole — not an Aggregate field inside a Ratio widget.
• For a simple ratio of two model properties, use the Ratio widgets with the original model properties (or a Unit conversion / per-element Arithmetic field), not an Aggregate field as numerator or denominator.

Total property value has special handling for Aggregate fields so it does not sum the same total once per element. Do not assume every other widget does the same yet.

​

Charts that group by an Aggregate field

Because every element shares the same Aggregate value, a chart grouped by that field usually shows one bar or category. That is expected. Group by a normal property (or a Grouping / Map lookup field) instead.

​

Totals do not cross between models yet

On a dashboard with more than one model (more than one Model Viewer / data source), an Aggregate is calculated inside each model separately. You cannot yet take a total from model A and use it in a calculated field on model B — for example “this room’s area as a share of the other building’s total”. For now, keep share-of-whole and similar maths within a single model. Cross-model totals need a different approach until this is supported.

​

Renames break existing widgets

Charts, filters, and colour-by remember the field name. Rename the field, and those widgets need to be pointed at the new name again.

​

Not for writing back to the model

Calculated fields are analysis-only. They do not appear as editable parameters in Parameter Updater.

​

Check the numbers

Until the Beta settles, spot-check important dashboards: compare a calculated total to Total property value on the same property, or to a known figure from the model. If a ratio or total looks impossibly large or tiny, look for an Aggregate field used where a per-element value was expected.

​

FAQ

​

See also

• Filters — Focus the dashboard on part of the model
• Lookup tables — Import lists for Map lookup and validation
• Common workflows — Share of the whole with Aggregate and Arithmetic
• Common workflows — Codes to clear labels with lookup tables and Map lookup
• Intelligence Dashboards — Overview and widgets