Skip to main content

Time Format

The Lacework API requires use of RFC 3339 format when referencing dates and times. The Lacework CLI, however, adds features that make specifying dates and times easier and more flexible: relative time specifiers and natural time ranges.

Relative Time Specifiers for LQL Queries​

Relative times allow you to represent time values dynamically, using specifiers that represent an offset from the current time. For instance, a relative time of -24h produces a date/time that is 24 hours less the current time. Relative times can also snap to a particular time. For instance, a relative time of @d would represent the start of the current day.

For example, the following command specifies a time range (using a start and end time) that represents the previous day:

lacework query run [query_id] --start -1d@d --end @d

A relative time has three components:

  • A signed (+/-) integer
  • A relative time unit
  • A relative time snap

Lacework supports the following relative time units:

  • y - year
  • mon - month
  • w - week
  • d - day
  • h - hour
  • m - minute
  • s - second

Additional considerations include:

  • To represent the current time, you can specify either now or +0s.
  • When specifying an integer and relative time unit, snaps are optional.
  • When specifying a snap, the integer and relative time unit are optional. For instance, @d is actually interpreted as +0s@d.

Natural Time Ranges​

Natural time ranges allow you to represent time range values using natural language in CLI commands and LQL queries. For instance, a natural time range of yesterday represents a relative start time of -1d@d and a relative end time of @d.

For example, the following command specifies a time range of this month:

lacework query run --range "this month"

A natural time has three components:

  • An adjective
  • A positive number (only when using the last adjective)
  • The full text representation of a relative time unit (i.e., year/years)

Lacework supports the following adjectives (disambiguating previous and last by design):

  • this/current
  • previous
  • last

Additional considerations include:

  • last implies "in the last". So last week reads as "in the last week" and represents a start time of -1w and an end time of now.
  • previous always snaps. So "previous week" represents a start time of -1w@w and an end time of @w.
  • yesterday is a valid natural time and is equivalent to previous day.
  • today is a valid natural time and is equivalent to this day or current day.
Last updated on