Skip to content
Documentation

List Attributes

List attributes enable time series to store categorical or enumerated data by selecting from predefined sets of values organized in units.

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.

Entity relationship diagram: a list attribute is assigned to time series via attribute assignments and contains list attribute units via unit assignments; each unit defines list attribute values, and each attribute assignment selects one unit and stores values

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

Units must be assigned to list attributes before they can be used.

Assignment Process:

Flowchart: a unit can only be assigned to an attribute of type List that it is not already assigned to, otherwise an exception is thrown; once assigned, the attribute can be assigned to a time series and the unit selected for that assignment

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

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 value property is what gets written to assignment data.
  • Both value and description can be modified.
  • Modifying a value does update existing assignment data if the force parameter is set to true in 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 force parameter is set to true in 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.

When writing data to a list attribute assignment:

Flowchart: data can only be written to an assignment that has a selected unit, and only values that belong to the selected unit are written; otherwise UnrelatedDataCannotBeWrittenToListAttributeAssignmentsException is thrown

Writing Constraints:

  1. The assignment must have a selected unit
  2. The value must belong to the selected unit
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
  1. Assign LA to TS1 with unit U1

    • Unit U1 is assigned to LA ✓ → Assignment is created successfully
  2. Write values A or B

    • Both values exist in unit U1 ✓ → Data is written successfully
  1. Attempt to assign LA to TS1 with unit U2

    • Unit U2 is not assigned to LA ✗ → Throws InvalidListAttributeUnitAssignmentException
  2. Attempt to write value C

    • Value C does not exist in unit U1 ✗ → Throws UnrelatedDataCannotBeWrittenToListAttributeAssignmentsException
  3. Attempt to write value 1

    • Value 1 belongs to unit U2, not U1 ✗ → Throws UnrelatedDataCannotBeWrittenToListAttributeAssignmentsException

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=true in delete request)
  • ✓ The unit assignment of U1 to LA will be deleted, making U1 no longer selectable for LA

What fails:

  • ✗ Future attempts to write A or B will throw UnrelatedDataCannotBeWrittenToListAttributeAssignmentsException
  • ✗ New assignments of LA to time series cannot select U1
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
© 2026 Volue.Version v0.6.38017 November 2026