Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

Tip

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.

...

  • hour (h, hr, hours)
  • minute (m, min, minutes)
  • second (s, sec, seconds)
  • week (w, weeks)
  • month (months)
  • year (y, yr, years)


Tip

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

...