Configure Time-Series Data Retention

ThingsBoard automatically deletes time-series records older than a configured Time-to-Live (TTL). By default TTL is disabled — records are kept forever. How you configure it depends on the storage backend.

PostgreSQL applies a single global TTL to all time-series data across all tenants and entities. A background cleanup job runs periodically and removes expired records.

ENV Variable	Default	Description
SQL_TTL_TS_ENABLED	true	Enable automatic TTL cleanup
SQL_TTL_TS_EXECUTION_INTERVAL	86400000 (1 day)	How often the cleanup job runs, in milliseconds
SQL_TTL_TS_TS_KEY_VALUE_TTL	0 s (never)	Retention period in seconds; 0 means records never expire

Cassandra supports granular TTL at three levels, from broadest to most specific:

1. System level — the maximum TTL cap for the entire platform, set via TS_KV_TTL. No entity can have a longer retention than this value.

2. Tenant level — a maximum TTL per tenant, configured in the tenant profile. Overrides the system default for that tenant.

3. Entity level — a specific TTL per entity. Two options let you configure it:

   • Rule Chain: The Save Time Series rule node in your rule chain writes raw telemetry to the database. Its Default TTL field determines how long each record lives, and the TTL message-metadata property can override it on a per-message basis. Set a shorter TTL here when raw readings are only useful for a short operational window. See Save Time Series, Advanced settings for the full option set.
   • Calculated Fields: Any calculated field can carry its own TTL for the values it produces. The TTL property is exposed on the field when Output type is set to Time series and Output strategy is set to Process right away. See Calculated Fields, Output strategy for details.

   Together these enable multi-level retention. Raw telemetry can expire quickly, while derived values produced by calculated fields live on independently, each with the TTL that matches its own analytical purpose. Read more in the Efficient Aggregation and Data Retention in ThingsBoard blog post.

ENV Variable	Default	Description
TS_KV_TTL	0 s (never)	Maximum system-level TTL in seconds; 0 means records never expire
TS_KV_PARTITIONING	MONTHS	Time-series partition granularity (DAYS, MONTHS, YEARS, INDEFINITE)

For a detailed overview of all TTL settings including events, audit logs, and notifications, see the Database Layer architecture reference.