7.2.1.18. Version Strings¶
There are several places in the Dashboard API where version strings are required in order to specify an analysis version of a dashboard project. They can be specified in a lot of ways:
Specify by keyword¶
There exists the special keyword latest you can use to refer to the newest version.
Specify by ISO8601 Date String¶
A subset of ISO8601 Date Strings is accepted. Valid examples are 2008-03-01T13:00:00Z or simply 2008-03-01. Analysis version dates are stored with milliseconds granularity, however the date strings don’t need to match exactly, a given version string that doesn’t exactly match an analysis version is interpreted to match the first version chronologically before the given date string.
Some concepts of ISO8601 are not supported, but you probably would not want to use them anyway. They are week-dates, day-dates and fractions of hours and minutes. Also you need to specify at least YYYY-MM-DD.
Version strings without a time zone offset (e.g. Z, -05:00, +01:00) are treated as UTC.
Specify by Index or Reverse Index¶
You can also specify a version’s index, where 0 refers to the empty version which is required when specifying a version diff query baseline version. Thus the first actual analysis version has index 1, the seconds has index 2 and so on. -1 refers to the version before latest, -2 refers to the version before -1 and so on.
Specify by natural language expressions¶
- There are some natural language expressions you can use if you like to have easily readable version strings and don’t care about the exact selected version.
NOW refers to the date at query time
1 HOUR AGO means 1 hour before query time (1 hour means 3600 seconds)
YESTERDAY 24 hours before query time
2 DAYS AGO 2 days before query time (1 day means 86 400 seconds / 24 hours)
3 WEEKS AGO 3 weeks before query time (1 week means 604 800 seconds / 7 days)
1 MONTH AGO 1 month before query time (1 month means 2 629 746 seconds / 30.436875 days)
1 YEAR AGO you know the drill (1 year means 31 556 952 seconds / 365.2425 days)
(The durations are estimates from Java java.time.temporal.ChronoUnit.)
Specify by relative offset¶
You may combine all of the above with a relative offset which might be handy for example if you already have a version string for a specific version and now want to get a version diff with exactly the version before or after. In order to achieve this, it is possible to say, e.g. 2017-02-02 - 1 or 2017-02-02 + 1.