List Attributes
List attributes enable time series to store categorical or enumerated data by selecting from predefined sets of values organized in units.
Overview
Section titled “Overview”In this article, the term unit always refers to a list attribute unit — not to measurement units for time series data (such as temperature, currency, or volume).
When a list attribute is assigned to a time series, a unit must be selected. The assignment can only contain values from that selected unit.
Core Concepts
Section titled “Core Concepts”List Attribute Units
Section titled “List Attribute Units”Units represent collections of values that can be assigned to list attributes.
Properties:
| Property | Description | Requirements |
|---|---|---|
| ID | Unique identifier | Must be unique across all units |
| Name | Human-readable name | Must be unique across all units |
| Data Type | Reference to attribute data type | Indicates the expected value type |
Assignment Rules:
- Each assignment of a list attribute to a time series must select exactly one unit
- All values in an assignment must reference the selected unit
- A unit must be assigned to an attribute before it can be selected for a time series assignment
- Units can be assigned to multiple attributes
- Attributes can have multiple units assigned to them
Unit-to-Attribute Assignments
Section titled “Unit-to-Attribute Assignments”Units must be assigned to list attributes before they can be used.
Assignment Process:
Key Constraints:
- Units can only be assigned to attributes with type
List - One unit can be assigned to multiple attributes
- One attribute can have multiple units assigned
- Only assigned units can be selected when assigning the attribute to a time series
List Attribute Values
Section titled “List Attribute Values”Each value within a unit has specific properties and constraints.
Properties:
| Property | Description | Uniqueness Constraint |
|---|---|---|
| Unit | Reference to parent unit | Required |
| Value | The actual data stored | Unique per unit |
| Description | Human-readable explanation | Unique per unit |
| Sort Order | Numeric ordering value | No constraint |
Data Behavior:
- The
valueproperty is what gets written to assignment data. - Both
valueanddescriptioncan be modified. - Modifying a value does update existing assignment data if the
forceparameter is set totruein the update request. Otherwise, update requests will fail if the value is in use in any assignment. - Deleting a value does also delete all assignment data that references it if the
forceparameter is set totruein the delete request. Otherwise, delete requests will fail if the value is in use in any assignment. - Deleted values cannot be used in future assignments.
Sort Order:
The sortOrder property is a numeric value used for display ordering of values in user interfaces.
Data Writing Rules
Section titled “Data Writing Rules”When writing data to a list attribute assignment:
Writing Constraints:
- The assignment must have a selected unit
- The value must belong to the selected unit
Complete Example
Section titled “Complete Example”| Component | Name | Description | Details |
|---|---|---|---|
| Time Series | TS1 |
Example time series | - |
| List Attribute | LA |
Attribute of type List |
- |
| Unit | U1 |
Assigned to LA |
Values: A, B |
| Unit | U2 |
Not assigned to LA |
Values: 1, 2 |
Scenario: Valid Operations
Section titled “Scenario: Valid Operations”-
Assign
LAtoTS1with unitU1- Unit
U1is assigned toLA✓ → Assignment is created successfully
- Unit
-
Write values
AorB- Both values exist in unit
U1✓ → Data is written successfully
- Both values exist in unit
Scenario: Invalid Operations
Section titled “Scenario: Invalid Operations”-
Attempt to assign
LAtoTS1with unitU2- Unit
U2is not assigned toLA✗ → ThrowsInvalidListAttributeUnitAssignmentException
- Unit
-
Attempt to write value
C- Value
Cdoes not exist in unitU1✗ → ThrowsUnrelatedDataCannotBeWrittenToListAttributeAssignmentsException
- Value
-
Attempt to write value
1- Value
1belongs to unitU2, notU1✗ → ThrowsUnrelatedDataCannotBeWrittenToListAttributeAssignmentsException
- Value
Scenario: Post-Deletion Behavior
Section titled “Scenario: Post-Deletion Behavior”After Deleting Unit Assignment or Unit
If we delete the assignment of U1 to LA, or delete U1 entirely:
What is deleted:
- ✓ All previously written data will be deleted (requires
force=truein delete request) - ✓ The unit assignment of
U1toLAwill be deleted, makingU1no longer selectable forLA
What fails:
- ✗ Future attempts to write
AorBwill throwUnrelatedDataCannotBeWrittenToListAttributeAssignmentsException - ✗ New assignments of
LAto time series cannot selectU1
Quick Reference Table
Section titled “Quick Reference Table”| Component | Can Have Multiple | Can Be Assigned To Multiple | Deletion Impact (force=false) |
Deletion Impact (force=true) |
|---|---|---|---|---|
| List Attribute | ✓ Multiple units ✓ Multiple assignments |
✓ Multiple time series | Deletes all assignments | Deletes all assignments |
| List Attribute Unit | ✓ Multiple values ✓ Multiple attribute assignments |
✓ Multiple attributes | Fails if referencing data exists Otherwise, removes from attributes |
Removes from attributes Deletes all referencing data |
| List Attribute Value | ✗ One unit only | ✓ Multiple time slots in assignments | Fails if referenced in data | Deletes all referencing data |
| Time Series Assignment | ✗ One unit only ✓ Multiple values over time |
N/A | Fails if assignment has data | Deletes all data |