Page tree
Skip to end of metadata
Go to start of metadata

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.


Time formats

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

2016-11-30T15:47:00Z

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 ...) 

Examples

  • 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:

  • now
  • startOfDay
  • startOfWeek
  • startOfMonth
  • startOfYear

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.

{
  "startTimestamp" : 1483225200000
  "endTimestamp" : 1488322800000,
  "timeFieldStrategy" : ["createdTimestamp","lastUpdatedTimestamp"],
  "timeMatchStrategy" : "any"
}

This example could be expressed in SQL as 

... WHERE
(
  ( 1483225200000 <= createdTimestamp <= 1488322800000)
  OR
  ( 1483225200000 <= lastUpdatedTimestamp <= 1488322800000) 
)

Changing the timeMatchStrategy to "all"

{
  "startTimestamp" : 1483225200000
  "endTimestamp" : 1488322800000,
  "timeFieldStrategy" : ["createdTimestamp","lastUpdatedTimestamp"],
  "timeMatchStrategy" : "all"
}

Changes the SQL to

... WHERE
(
  ( 1483225200000 <= createdTimestamp <= 1488322800000)
  AND
  ( 1483225200000 <= lastUpdatedTimestamp <= 1488322800000) 
)


  • No labels