Specifying relative time

Relative time is time that is based on the current time, such as last 5 minutes and last hour.

You define relative time in your search by using time modifiers along with a time amount integer and unit. In addition, you can specify a "snap-to" time which takes the relative time and rounds down to the start of the time unit.

For example, if you specify the previous 1 hour -1h for the relative time, the search time is exactly 1 hour from the time you run the search. If you run the search at 3:45, the search looks for events with a timestamp of 2:45 or later.

You add a snap-to time using the @ symbol followed by a time unit. If you add a snap-to time unit of hours to the previous example, -h@h, the search rounds the time down to the hour. If you run the search at 3:45, the search looks for events with a timestamp that start at 2:00, which is the time of the search minus 1 hour and then round down to the beginning of the hour.

You can snap-to the beginning of any time unit, such as the beginning of the current hour, day, week, or month.

The syntax for using time modifiers is [+|-]<time_integer><time_unit>@<time_unit>

The steps to specify a relative time modifier are:

1. Indicate the time offset from the current time.
2. Define the time amount.
3. Optional. Specify a snap-to time unit.

1. Indicate the time offset

Begin your string with a plus (+) or minus (-) to indicate the offset from the current time.

For example to specify a time in the past, a time before the current time, use minus (-).

2. Define the time amount

Define your time amount with a number and a unit. The supported time units are listed in the following table.

Time unit	Valid unit abbreviations
second	s, sec, secs, second, seconds
minute	m, min, mins, minute, minutes
hour	h, hr, hrs, hour, hours
day	d, day, days
week	w, week, weeks
month	mon, month, months
quarter	q, qtr, qtrs, quarter, quarters
year	y, yr, yrs, year, years

For example, to start your search an hour ago, use either of the following time modifiers.

earliest=-h

or

earliest=-60m

Default time unit

If you specify a <timescale> without a time unit, the number one is implied. An 's' is the same as '1s', 'm' is the same as '1m', 'h' is the same as '1h', and so forth.

3. Specify a snap-to time unit

When you snap-to time unit, the time that you specify rounds down to the nearest or latest time value. You separate the time amount from the "snap-to" time unit with an "@" character. For example, @d snaps to the beginning of today which is 12:00 AM, or midnight.

You can use any time unit with snap to. For example:

• @w, @week, @w0, or @w7 for Sunday. For other days of the week use w1 (Monday), w2, w3, w4, w5 and w6 (Saturday).
• @month for the beginning of the month.
• @q, @qtr, or @quarter for the beginning of the most recent quarter (Jan 1, Apr 1, Jul 1, or Oct 1).

When snapping to the nearest or latest time, time always snaps backwards in time or rounds down to the latest time that is not after the specified time. For example, if the current time is 11:59:00 and you "snap to" hours, you will snap-to 11:00 not 12:00. 12:00 would be after the current time.

If you do not specify a time offset before the snap-to amount, the time used is the current time snapped to the specified amount. For example, if it is currently 11:59 PM on Friday and you use @w6 to "snap-to Saturday", the resulting time is the previous Saturday at 12:00 AM.

Specifying offsets from the snap-to time

You can also specify offsets from the snap-to-time or "chain" together the time modifiers for more specific relative time definitions. For example, you can specify @d+12h to snap-to the beginning of the day and then add 12 hours to use 12:00 PM or noon.

An offset before the snap-to time always applied first. In other words, the left-hand side of the @ symbol is applied before the right-hand side. For example, if you specify earliest=-5d@w1 the -5d is applied before the snap-to time @w1.

An offset after the snap-to time is always applied after the snap-to. For example, @d-2h snaps to the beginning of today (12:00 AM or midnight), and then applies the time offset of -2h, This results in a time of 10:00 PM yesterday.

See also

Related information

Timestamps and time ranges

Time modifiers

Using time variables

Time zones