Calculated Fields

Calculated fields transform raw sensor data into actionable insights in real time. Instead of just storing telemetry, you define a calculation rule and ThingsBoard automatically generates derived values — stored as time series or attributes — the moment data arrives.

Calculations draw from multiple sources: incoming telemetry, entity attributes, or data from related assets and devices. Results are immediately ready for dashboards, alarms, and automation.

Executions can be chained: the output of one field triggers the next, enabling multi-step processing pipelines. ThingsBoard automatically prevents infinite loops — if the same calculated field appears twice in a single execution chain, the chain is stopped.

Calculated fields apply at two levels:

• Entity level — applied to a single Device or Asset.
• Profile level — defined in a Device profile or Asset profile and inherited by every entity using that profile.

If both an entity-level and a profile-level calculated field match the same entity, both run.

Available since ThingsBoard 4.0. The Aggregation and Geofencing types were added in 4.3.

Calculated fields can only be created and managed by Tenant Administrators. Customer-level users do not have access.

Type	Best for
Simple	Single math expression: +, -, *, /, sqrt, pow, abs, min, max
Script	Multi-step logic, conditionals, rolling windows, multiple outputs (TBEL)
Propagation	Copy or compute values and push them to related entities via relations
Geofencing	GPS zone detection — INSIDE/OUTSIDE status and ENTERED/LEFT events
Related entities aggregation	Avg, min, max, sum, count across multiple child or parent entities
Time series data aggregation	Hourly/daily/weekly KPIs from historical telemetry of the current entity

The creation process is identical for Devices, Assets, Device profiles, and Asset profiles.

1. Open the Calculated fields page.
2. Click the + Add calculated field ⇾ Create new calculated field in the top-right corner.
3. Configure the General, Arguments, Calculation, and Output sections.
4. Click Add to save.

Field	Description
Title	Descriptive name reflecting the field’s purpose
Entity type	The device, asset, or profile to which the field is applied
Type	The calculated field type — determines which configuration sections are available

Arguments define which data the calculated field reads and exposes as named variables for the calculation. Each argument maps a data source to a named variable. Choose the entity to read from (current entity, a specific Device/Asset, Customer, tenant, or owner), then select one of three types:

• Attribute — a single attribute value (Server, Client, or Shared scope) with an optional default fallback.
• Latest telemetry — the most recent value of a telemetry key, with an optional default fallback.
• Time series rolling (Available in Script and Propagation fields) — a sliding historical window of telemetry values, exposing aggregation methods (mean(), sum(), min(), max(), and more).
  For the full rolling argument API, see Script — Rolling Argument API.

The calculation block depends on the selected type:

Type	Calculation model
Simple	Single mathematical expression
Script	TBEL function returning a JSON object or array
Propagation	Arguments-only (direct copy) or TBEL script
Geofencing	Zone group configuration
Related entities aggregation	Aggregation metrics (avg, min, max, sum, count)
Time series data aggregation	Aggregation metrics over historical intervals

See each type’s page for full details and examples.

All field types store results on the same entity where the field is applied. The only exception is the Propagation type, which writes its output to related entities.

Results are stored as either time series or attributes:

Storage type	Content	Notes
Time series	JSON object or array, with or without a timestamp	Enable Use latest timestamp to align with argument data time
Attribute	JSON object without timestamp	Stored in Server or Shared scope

Controls how the result is processed after calculation.

Strategy	Behavior
Process right away (default)	Result is stored directly, bypassing Rule Chains with minimal latency
Process via Rule Chains	ThingsBoard generates a POST_TELEMETRY_REQUEST or POST_ATTRIBUTES_REQUEST message and routes it to the entity’s Default Rule Chain

Time series options:

Option	Description
Save to time series	Stores historical values in the time series database
Save to latest values	Updates the latest value store if the timestamp is newer
Send to WebSockets	Pushes updates to active WebSocket subscribers (no database write)
Send to Calculated fields	Forwards updates to other calculated fields, enabling chained dependent fields
Custom TTL	Sets a custom storage duration; if disabled, the Tenant Profile TTL applies

Attribute options:

Option	Description
Save to database	Writes the attribute to persistent storage
Send to WebSockets	Pushes updates to active WebSocket subscribers (no database write)
Send to Calculated fields	Notifies other calculated fields about attribute changes
Update attribute only on value change	Writes only when the value actually changes
Send attributes updates notification	Generates an “Attributes Updated” event

The result is not stored directly. Instead, ThingsBoard generates a POST_TELEMETRY_REQUEST or POST_ATTRIBUTES_REQUEST message and routes it to the entity’s Default Rule Chain.

Use this strategy when you need additional processing — filters, scripts, conversions, enrichment, routing, or forwarding. The Rule Chain must include a Save time series or Save attributes node to persist results.

Configure with AI lets you create and manage calculated fields by describing what you want in plain language, instead of manually configuring arguments, the calculation, and the output. It’s powered by the AI Assistant available throughout ThingsBoard — see that guide for how to write effective prompts and how the Assistant works in general.

It’s useful whenever you know what value you want to derive but don’t want to configure arguments and formulas by hand — for example:

• Aggregating a few of a device’s telemetry keys into a single derived value
• Getting suggestions for calculated fields that make sense for a given device or asset
• Computing values across related entities, such as parent/child aggregations
• Adjusting an existing calculated field’s arguments, formula, or output

Workflow

1. On the Calculated fields page, click Configure with AI to open the AI Assistant panel.
2. Describe the calculated field you want in the chat — the entity, the inputs, and how they should combine, e.g. “Pick one of my devices and set up a calculated field that aggregates a few of its telemetry keys.” Use the suggested prompts if you’re not sure where to start.
3. The Assistant inspects your entities and their telemetry, then explains its plan — including the entity it picked, the inputs, the formula, and the output — before creating anything. If a device isn’t reporting the data it expected, it says so and proposes a reasonable alternative instead of failing silently.
4. Confirm the proposal — either by replying in the chat or by clicking Approve on the approval card, depending on how the plan was presented — or Deny/describe what to change.
5. Keep the conversation open to refine the result — adjust the formula, add another input, or change the output — instead of starting over.

Best Practices

• Describe the outcome you want to compute, not the formula itself — let the Assistant pick the arguments and expression.
• Name the device, asset, or profile clearly, or let the Assistant choose one and confirm its plan before it creates anything.
• Include the specific telemetry keys or attributes when you already know them, to skip a round of clarifying questions.
• Review the proposed inputs, formula, and output before confirming, especially when the Assistant had to infer missing details.

Limitations

• Changes are proposed, not applied silently: the Assistant explains its plan and asks for confirmation before creating or updating a calculated field.
• If your entities don’t yet report the expected telemetry, the Assistant may propose the field using placeholder key names — verify these match your actual data before relying on the result.

Each calculated field has a Debug toggle. When enabled, ThingsBoard records execution details for every run — the resolved argument values and timestamps that triggered execution, plus the result or any error.

Enable debug mode during field creation or toggle it on an existing field using the Debug button in the row.

Click the Events icon in the calculated field row to inspect recorded events:

Field	Description
Entity ID	The entity where the field executed
Message ID	Unique execution identifier
Message type	What triggered the execution (telemetry update, attribute update, etc.)
Arguments	Resolved argument values and timestamps
Result	Output generated by the field
Error	Failure reason (only shown when execution failed)

For Script and Propagation (Calculation result mode) fields, click Test with this message in an event row to open the interactive testing panel:

• Left panel — TBEL script editor; modify the script without saving changes
• Top-right panel — Argument list; adjust values and timestamps to simulate different inputs
• Bottom-right panel — Execution output or error

1. Modify the script or argument values as needed.
2. Click Test to execute the function with the provided inputs.
3. Review the output JSON structure and values.
4. Click Save to keep changes.
5. Apply the changes to the calculated field configuration to activate the updated logic.

Calculated fields integrate with the ThingsBoard Rule Engine. Execution is triggered automatically whenever telemetry or attributes are processed by:

• Save Time Series node — triggers when new telemetry is persisted
• Save Attributes node — triggers when client, shared, or server-side attributes are updated
• Calculated Fields node — dedicated node for manual invocation or complex chaining

Calculated fields execute on each incoming data update. There are no additional per-field rate limits — the effective execution rate is bounded by the device’s incoming telemetry rate.

Calculated field reprocessing applies the current calculation logic to historical telemetry. Use it to backfill results for data that arrived before the field was created, or to regenerate historical results after modifying an existing field.

1. Go to the Calculated fields page.
2. Click the Reprocess calculated field icon next to the desired field.
3. Define the time interval for reprocessing.
4. Click Reprocess — the system recalculates and updates historical telemetry.
5. Click Finish when the process completes.

Example: A Smart Device has been sending temperature and humidity for weeks. You add a dewPoint calculated field today. Without reprocessing, dewPoint appears only from this moment. After reprocessing, dewPoint is backfilled for the entire selected historical period.

The Task Manager is accessible from the left navigation menu under Advanced features ⇾ Task Manager. It lists all background processing tasks, including calculated field reprocessing jobs.

Column	Description
Created time	When the task was initiated
Type	Task type — e.g. “Calculated field reprocessing”
Entity	The device or asset the task ran against
Status	Current state: pending, running, completed, or failed
Progress	Completion percentage

Each row also provides action icons to view task details, inspect results, or delete the record.

Calculated field configurations can be exported as JSON and imported into any ThingsBoard instance.

Export:

1. Go to the Calculated fields page.
2. Click the Export icon in the calculated field row.

Import:

1. Go to the Calculated fields page.
2. Click the + Add calculated field ⇾ Import calculated field.
3. Upload the JSON configuration file and click Import.
4. Specify the entity or profile to which the field will be applied.
5. Review any highlighted argument errors.
6. Click Add to complete the import.

1. In the calculated field row, click the Delete (trash) icon.
2. In the confirmation dialog, click Yes to confirm.

All calculated field limits are configurable per tenant in Tenant Profiles → Calculated fields. The table below lists the default values:

Limit	Default	Description
Calculated fields per entity	100	Maximum number of calculated fields on a single entity or profile
Arguments per calculated field	10	Maximum number of arguments per field
Data points per rolling argument (tenant limit)	1000	Upper bound on the Max values field of a “Time series rolling” argument. The argument’s own Max values field — pre-filled at 1/10 of this value (100 by default) — is the effective cap: it always fetches raw (unaggregated) values, and once the window holds more points than that field’s value, the oldest points are silently dropped, so the effective window can be shorter than configured.
State size	512 KB	Maximum total state stored per calculated field (geofencing zone state, rolling window cache, etc.)
Single value argument size	32 KB	Maximum size of a single attribute or latest telemetry argument value
Max relation levels (Related entities)	2	Maximum depth of a relation path when resolving related entities
Min update interval (Related entities)	10 s	Minimum allowed refresh interval for zone or entity relation caches
Min aggregation interval	60 s	Minimum allowed aggregation interval (Time series data aggregation type)
Min deduplication interval	10 s	Minimum allowed deduplication interval (Related entities aggregation type)
Intermediate aggregation interval	300 s	How often intermediate (in-progress interval) aggregation results are stored
Reevaluation check interval	60 s	How often the system checks for and processes missed aggregation intervals
Relation search entity limit	1000	Maximum entities resolved at the last level of a relation path

Video: https://www.youtube.com/watch?v=wBUcWMSH4QI