Using Argus Search APIs - Time fields
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 supported 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.
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62 | InitialFunction +/- <amount> TemporalFunction (+/- <amount> TemporalFunction ...)
````
Examples
- `now - 2 hours`: 2 hours back from this instant
- `now - 2 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` :
```json
{
"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)
)
|