Working with Dates and Times

Seq works with event and time-series data, and has many features for working with date and time data.

Representation of timestamps and durations

Seq internally measures time in 100-nanosecond ticks. For example, Seq will represent a one-minute interval as 600000000.

Duration literals

Because durations in ticks are very large numbers, Seq provides a shorthand syntax for describing durations. One minute is written as 1m, which is just another way of saying 600000000 (but much easier on the eyes).

Duration literals can be specified as any whole number of days (d), hours (h), minutes (m), seconds (s) and milliseconds (ms), and these can be chained together to represent more complex durations such as 1h30m.

Durations can be formatted nicely using ToTimeString(): calling ToTimeString(1h30m) will return the string '1:30'.

Timestamps and datetimes

Seq represents timestamps and datetimes using the same 100-nanosecond ticks, from a zero value at midnight on January 1st on the year 0001.

Most often, datetime values will be encountered in the @Timestamp property on an event, but values of the same type can be created by calling the Now() function, or by parsing an ISO-8601 date/time string using DateTime("2021-03-16T14:37:45.001").

This means that dates and times support arithmetic operators like +, -, * and /, as well as comparisons =, <>, <, <=, >, and >=:

@Timestamp >= Now() - 1h

Adding or subtracting the value of two durations works as you'd expect: 1d + 30m will evaluate to 1d30m, for example.

Adding or subtracting a duration from a datetime produces another datetime: Now() - 7d will evaluate to the same instant seven days ago.

The OffsetIn(timezone, instant) function

Many Seq features work server-side, and sometimes unattended, so expressions in queries don't have a single notion of the current time zone, and instead rely on the OffsetIn() function to compute time zone offsets where required.

-- Prints 10:00
select ToTimeString(OffsetIn('Australia/Brisbane', Now())

OffsetIn() accepts an IANA time zone name.

Because of daylight savings time, OffsetIn(), also needs a point in time at which to compute the offset. This can be specified using an event's @Timestamp, by calling the Now() function, or by parsing an ISO-8601 date time string with DateTime("2021-03-16T14:37:45.001").

The DatePart(datetime, part, offset) function

DatePart() is used to break a datetime into its constituent parts. It can answer questions like:

Did the event occur on a Wednesday?

DatePart(@Timestamp, 'weekday', OffsetIn('Australia/Brisbane', @Timestamp)) = 3

In June?

DatePart(@Timestamp, 'month', OffsetIn('Australia/Brisbane', @Timestamp)) = 6

The DatePart() function needs a time zone offset, computed in these examples using OffsetIn(), because whether a point in time is a Tuesday or Wednesday depends on in which time zone it's being observed.

The examples above use OffsetIn() to compute an offset, but if you're working with a fixed offset you can specify it directly using a duration literal like 0h or 5h30m.

Parts