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.

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.

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	5	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	1000	Maximum number of { ts, value } records in a time series rolling window
State size	32 KB	Maximum total state stored per calculated field (geofencing zone state, rolling window cache, etc.)
Single value argument size	16 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)	0 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