What is the benefit of using ExactDimensionTimedValue


While reviewing some types in the platform, I’ve come across the use of ExactDimensionTimedValue.

When I look more into it, it seems it just declares a single field datetime.

In what situations would I use datetime vs. ExactDimensionTimedValue?





A datetime is a primitive value, whereas an ExactDimensionTimedValue is a type with two fields:

type ExactDimensionTimedValue {
  value: ExactDimension
  timestamp: datetime

So you would use an ExactDimensionTimedValue when you want to keep a record of an ExactDimension at a specific point in time.

(For those of you who do not recognize ExactDimensionTimedValue, it is introduced in v7.7 in an application-specific base package)



Hi Matt,

Thanks for chiming in. I’m not sure your response quite clarifies for me when I should use ExactDimensionTimedValue – however, I’ve recently learned something new about the purpose of ExactDimension. And perhaps this will help with the type of answer I’m looking for.

It was explained to me that if I am storing a value of say, “inventory level”, I could store the value as an INTEGER. Or, I could store the value in an ExactDimension type.

The difference is as follows:

Say we’re dealing with eggs… with INTEGER, we could store the value (e.g. 12) and always use it at face value without knowing the unit of measure.

However, if we store the value as ExactDimension type, we could store it as 12 as follows:

  "type": "ExactDimension",
  "value": 12,
  "unit": {
    "id": "single"

In other data sets, perhaps quantities are counted as per “dozen”. We might then store the value as follows:

  "type": "ExactDimension",
  "value": 1,
  "unit": {
    "id": "dozen"

By the way, for those reading, you can find out all the supported Units by doing c3Grid(Unit.fetch()). Notice that the multiplier of “dozen” is 12 “single”

So the BENEFIT of using ExactDimension is that, if we choose to store the data with Unit of Measure, we can have the platform convert between units of measure for us… and provide answers back with unit of measure (e.g. How many dozens of eggs do we have?). The platform, when aggregating across types that use different units of measure, can automatically compensate/convert between different stored values of Exact Dimension to give correct results.

So, using the above as an example explanation – it would be very helpful if you/someone could provide a concrete use case for ExactDimensionTimedValue.



I have some new information and will attempt to answer my own question.

ExactDimensionTimedValue is used to track how a value changes over time. It is often used with another type, TimedValue history. So here is an example use case:

Consider an example where you’re trying to record the temperature of a room. The measurements are recorded as the data arrives.

entity type Room schema name 'ROOM' {

    currentTemp : ExactDimensionTimedValue

    tempHistory : [TempHistory] (parent)

and here is the definition of TempHistory type:

entity type TempHistory mixes TimedValueHistory<Room> schema name 'TEMPHISTORY' {
	value 			: ExactDimension

A couple of observations for this setup:

  1. Through the life of the application, as new temperature readings are recorded, they should be recorded against/updated to the field: ROOM.currentTemp … overwriting the prior value.

  2. Looking at just the Room type – notice the annotation @db(timeValueHistoryField='tempHistory') just above currentTemp. This creates a relationship between currentTemp and tempHistory fields within the type. As currentTemp takes on new values, copy is also appended in tempHistory.

  3. TempHistory type “mixes” TimedValueHistory<Room> – which means that it takes Room type as an input. The field “value” is inherited from TimedValueHistory – and is where past values of temperature are stored.

  4. Use of ExactDimension here allows you to specify along with the temperature value, the Unit of Measure - such as fahrenheit or celcius – because this bit of information is probably important to associate with the value :grinning:

In a nutshell, for those coming from a BI / traditional RDBMS background, this setup is similar to how we use slowing changing dimension (SCD) tables to not lose past values – except I’d argue this is quite slick in that we don’t need any 3rd party ETL tools or write any fancy triggers. And, it is optimized for big data use cases (imagine taking a million readings for a million devices and trying to maintain that in a SCD table - won’t work)