7.2.1.18. Version Strings

Several locations in the Dashboard API require version strings to specify the analysis version of a dashboard project. These can be specified in several ways:

Specify by keyword

The special keyword latest can be used to refer to the newest version.

Specify by ISO 8601 Date String

A subset of ISO 8601 date strings is accepted. Valid examples include 2008-03-01T13:00:00Z or simply 2008-03-01. While analysis version dates are stored with millisecond granularity, the date strings do not need to match exactly; if a version string does not exactly match an analysis version, it is interpreted as the first version chronologically preceding the specified date string.

Certain ISO 8601 concepts are not supported, such as week-dates, ordinal dates, and fractions of hours and minutes. Additionally, you must 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 by its index. Index 0 refers to the empty version, which is required when specifying a baseline version for a version diff query. Consequently, the first actual analysis version has index 1, the second has index 2, and so on. Index -1 refers to the version before latest, -2 refers to the version before -1, and so on.

Specify by natural language expressions

Several natural language expressions can be used for improved readability when the exact version is not critical:

  • NOW refers to the date at the time of the query

  • 1 HOUR AGO refers to one hour before the query time (1 hour = 3,600 seconds)

  • YESTERDAY refers to 24 hours before the query time

  • 2 DAYS AGO refers to two days before the query time (1 day = 86,400 seconds / 24 hours)

  • 3 WEEKS AGO refers to three weeks before the query time (1 week = 604,800 seconds / 7 days)

  • 1 MONTH AGO refers to one month before the query time (1 month = 2,629,746 seconds / 30.436875 days)

  • 1 YEAR AGO refers to one year before the query time (1 year = 31,556,952 seconds / 365.2425 days)

(The durations are estimates from Java java.time.temporal.ChronoUnit.)

Specify by relative offset

All of the above can be combined with a relative offset. This is useful, for example, if you have a version string for a specific version and wish to obtain a version diff with the immediately preceding or succeeding version. For example: 2017-02-02 - 1 or 2017-02-02 + 1.