Timestamps in Riak TS are a critical data type, nearly always a part of partition key. They are often leveraged with the quantum function to group data by 15 minute clumps, or 10 second clumps, or 60 day clumps, et cetera, depending on how quickly your time series data come in and how you need to analyze them.
Structure of Timestamps
Unix Epoch Time
Timestamps in Riak TS are stored as positive integers representing the number of UTC milliseconds since January 1st, 1970 (UNIX epoch time).
As an example: midnight GMT, August 1st 2016, would exist in
the database as the integer
You can read more about UNIX epoch time here.
For INSERT and SELECT statements, Riak TS supports ISO 8601 strings which are converted to UTC milliseconds.
ISO 8601 support is useful for casual interactions via riak shell, but we do NOT recommend using ISO 8601 in production applications. Instead, use the TS-supported client libraries to pass timestamps as integers for better performance and correctness.
Strings that do not include seconds are referred to as reduced accuracy representations.
Ambiguity can arise with reduced accuracy representations. For instance, what do the comparisons
time > '2015' or
time <= '2003-05-01T05:10'
mean when translated to epoch time value as stored in Riak TS?
To resolve those ambiguities, Riak TS expands the reduced accuracy
value to the lowest date/time which matches the specification.
For inserting data, that’s the full story. The expanded date/time value will be converted to epoch milliseconds and stored in the database.
For querying data, there are two important exceptions to the simple expand and convert sequence above.
1. Strictly greater than (>) and greater-than/equal-to (>=) queries involve incrementing the original reduced accuracy representation before expansion.
time > '2015' becomes in effect,
time >= '2016-01-01
time <= '2003-05-01T05:10' becomes
time < '2003-05-01T05:11:00'.
Thus, querying for timestamp values greater than
will ignore any values which fall between 9pm and 9:01pm, while using
a fully-specified string
'1970-12-18 21:00:00' will include them.
2. Fractional times are not considered reduced accuracy, so selecting for
timestamps greater than
2016-08-03 15:00 will give different
2016-08-01 15.0 (or
Time Zone FAQs
Why can’t Riak TS default to the operating system’s time zone instead of GMT if
riak-adminis not used to set a time zone?
It is critically important that all servers in the cluster agree on the time zone to be used for translating time strings into timestamps. Defaulting to the operating system’s time zone is only safe if all servers in the cluster are guaranteed to be configured identically.
Why can’t I specify my time zone symbolically so I don’t have to change my default time zone when DST begins and ends?
Effectively for the same reason as question 1. Politicians love to mess with DST and time zones, and if one server in the cluster fails to get the latest time zone file updates, timestamps may be inconsistent depending on which server handles the translation from text to timestamp.
Can I set a different time zone for different tables?
riak-shelldisplay the results from
Riak TS does not yet expose the default time zone to clients.
ISO 8601 includes three notable syntaxes which are not yet supported in Riak TS:
- expanded representation (years outside the range 0000-9999),
- time intervals (a range of times), and
- week dates (a week or day expressed as a number of weeks into the year).