Searching for time
Most search endpoints for objects with time fields time will have a "startTimestamp" and "endTimestamp", specifying the period to search in.
If startTimestamp is not specified, the search will have no lower limit on the timestamp.
If endTimestamp is not specified, the search will have no upper limit on the timestamp.
If the entity being searched has multiple time fields, the search can be specified on one or a set of fields using the "timeFieldStrategy" (see below).
Some endpoints may not support searching without a clear startTimestamp, as we want to force the user to select an appropriate search period.
This may greatly affect search performance, depending on the underlying service implementation.
All timestamp fields in the API are in milliseconds since epoch, both in input and output values.
From Q1 2020, we have started to introduce support for more time formats in most APIs.
This allows using more human readable, and more flexible ways of specifying time in the API.
Millis since epoch
This is the default and underlying format; all timestamps are in milliseconds since epoch, which is not relative to timezone or daylight saving.
This is a good default to use for all API usage, when time is already parsed from the user/application in any way, as this is unambiguous.
ISO8601 time string
The ISO-8601 time format allows using a standard, machine readable, but yet human readable time format, on the form
Please note that this time format is ONLY suppored for the UTC timezone (denominated by "Z"), so specifying any other time zone is not allowed.
Going forward, this time format will also be a standardized output format, to improve human readability for timestamps.
Relative time format
The relative time format allows specifying a time relative to now, taking into account the current time/time of day/day of month/month of year, etc, in addition to the current users time zone.
The format is on the form
InitialFunction +/- <amount> TemporalFunction (+/- <amount> TemporalFunction ...)
now - 2 hours # 2 hours back from this instant
now - 4 days - 2 hours # 50 hours back from this instant
startOfDay # midnight at the start of this day, relative to the current users time zone
startOfDay - 1 hour. # 23:00 the previous day, relative to the current users time zone
startOfMonth - 1 week # 7 days before 00:00 on the 1st of the current month, relative to the current users time zone
now - 1 month. # same date and time of day of the previous month, relative to the current users time zone
startOfMonth - 1 month # 00:00 on the 1st of the previous month, relative to the current users time zone
startOfYear - 1 year # 00:00 on January 1st of the previous year, relative to the current users time zone
Valid InitialFunctions are:
Valid TemporalFunctions are:
- hour (h, hr, hours)
- minute (m, min, minutes)
- second (s, sec, seconds)
- week (w, weeks)
- month (months)
- year (y, yr, years)
If no InitialFunction is specified, the default initial function is "now".
This means that a time string such as "-1month" means "one month from now".
Also, If no amount is specified, the default amount is "1".
This means that "startOfDay - hour" means "23:00" (relative to the current users time zone).
Time field strategies
Using the "timeFieldStrategy" parameter allows you to specify which time fields to search in.
A "timeMatchStrategy" will specify if the range limitation should apply to any of the listed fields, or if it must apply to all of them.
This example will search for all objects where createdTimestamp OR lastUpdatedTimestamp has a value between startTimestamp and endTimestamp.
This example could be expressed in SQL as
... WHERE ( ( 1483225200000 <= createdTimestamp <= 1488322800000) OR ( 1483225200000 <= lastUpdatedTimestamp <= 1488322800000) )
Changing the timeMatchStrategy to "all"
Changes the SQL to
... WHERE ( ( 1483225200000 <= createdTimestamp <= 1488322800000) AND ( 1483225200000 <= lastUpdatedTimestamp <= 1488322800000) )