- Equipment states:
ON/OFF,OPEN/CLOSED,IDLE/RUNNING/ERROR/MAINTENANCE - Process states:
HEATING/COOLING/STABLE,WARMING_UP/ACTIVE/STANDBY/COOLING_DOWN/OFF - Network equipment:
UP/DOWN/DISABLE/ERROR - Environmental conditions:
SUNNY/OVERCAST/NIGHT(for solar panels),CLEAR/RAINY/SNOWY(for weather stations) - Quality grades:
A/B/C/D/E/F,PASS/FAIL,EXCELLENT/GOOD/FAIR/POOR
Core concepts
State time series build on two concepts: state sets, which define the valid states, and state transitions, which track how equipment moves between states over time.State sets
A state set is a named collection of valid state value pairs (integer, string) that defines the possible states for a time series. State sets are managed through the data modeling API and enable:- Shared definitions: Multiple time series can reference the same state set.
- Validation: Data points are validated against the state set during ingestion.
- Meaningful labels: Numeric state codes are automatically mapped to human-readable strings.
Example state set
description field. Descriptions are stored in the data modeling service and are not returned by the time series API.
State constraints
State sets have the following constraints:- Maximum 100 unique states per state set. Fewer states present in aggregate periods result in smaller response payloads and faster retrieval.
- Numeric values must be 32-bit integers (-2,147,483,648 to 2,147,483,647).
- String values must be up to 255 UTF-8 characters.
- Both numeric and string values must be unique within a state set.
State transitions
A state transition occurs when equipment changes from one state to another. During aggregation, the system tracks the number of transitions into each state. To retrieve the exact timestamps when state changes occurred or to determine which state the equipment transitioned from, fetch the raw data points directly.API usage
You create state time series and state sets as instances with the data modeling API, and ingest and retrieve state data points with the time series data points API. The following examples show how to work with state time series and state sets.Create state time series
To create a state time series, set thetype property to state and link to a state set:
Example: create state time series
Example: create state time series
Create state sets
State sets are created through data modeling using theCogniteStateSet view:
Example: create state set
Example: create state set
Ingest state data
State data points can include both numeric and string values. If both are provided, they must correspond to the same state:Example: ingest state data points
Example: ingest state data points
Retrieve raw data points
When retrieving raw data points, thenumericValue is returned if present. For data points with a Bad status, the numericValue may be null or omitted. If the numeric value exists in the current state set, the response also includes the stringValue:
Example: retrieve raw state data points
Example: retrieve raw state data points
Retrieve state aggregates
State time series support the common aggregates and the state aggregates. This example requests both:Example: retrieve state aggregates
Example: retrieve state aggregates
State set management
State sets can be modified after creation, but changes to state definitions affect how historical data is interpreted in queries and aggregates. Understanding these implications is important when managing state sets over time.Update state sets
To update a state set, update thestates property through the CogniteStateSet view:
Example: update state set
Example: update state set
- Adding states: New states can be added without affecting existing data points.
- Removing states: Historical data points with removed states retain their numeric values but may not have string values in queries.
- Changing mappings: If you change the string value for a numeric value, historical data displays with the new string value.
Delete state sets
Deleting a state set through data modeling causes all time series referencing it to have an empty state set. The time series and data points remain intact. Without a state set, the only data points that can be ingested are those with aBad status and a null numeric value.