Timestamps

Both vertex and edge graph elements can have multiple timestamps.

The following formats apply across all Topology APIs when specifying timestamps:

• Millisecond Epoch

  Example:

  date "+%s%3N"
  1655991641000
  

• RFC-3339 / ISO-8601

  Format:

  YYYY-MM-DDThh:mm:ss.sssZ
  

  Example:

  date --universal "+%FT%T.%3NZ"
  2022-06-23T13:40:41.000Z
  

• beginTime - The beginTime timestamp records the beginning of a period of time for which the resource was valid, with endTime marking the end of that period.

  Tip: A resource can have multiple begin times in its historic record, and gaps can happen in that record if the resource was offline for periods.

  • All resources and historic resources that are representations of the same thing have a distinct beginTime

  • Resource beginTime together with endTime is used in historic graph traversals, that is, when the _at parameter is supplied. The period during which a resource is valid is defined as:

    atTime >= beginTime && atTime < endTime
    

  • A vertex or edge, which has the beginTime equal to the endTime, can be used to store audit information, such as the provider which deleted a resource. However, because it takes up zero time it does not form part of the history and is ignored by the preceding equation.

• prevBeginTime - If history exists for a resource, then this property is set to the beginTime of the most recent historical resource.

• changeTime - The changeTime timestamp records when the properties of the element last changed. The value can be less than the observedTime, which is updated on a POST or PUT even if no property values have changed.

• createTime - The createTime timestamp records when the element was first created in the topology service.

  • Historical resources do not store createTime, as it is shared with the anchor.
  • createTime is needed when looking for something older than 30 days – that is, when there is no beginTime this old because the historical resources have timed out.

• endTime - The endTime timestamp records when the element was deleted.

  • All resources and historic resources that are representations of the same thing have a distinct endTime.
  • Resource endTime is used in historic graph traversals, that is, when the _at parameter is supplied.
  • For current resources, endTime is LONG _MAX. This is sometimes hidden through the REST API.

• observedTime - The observedTime timestamp records when the element was last observed, that is, when data was last input to the topology service for the element.