Splunk® Cloud Services

SPL2 Search Manual

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.

Examples of relative time modifiers

For these examples, the current time is Wednesday, 05 June 2024, 01:37:05 P.M.

24h is usually but not always equivalent to 1d because of Daylight Savings Time boundaries.

Time modifier Description Resulting time Equivalent modifiers
now Now, the current time Wednesday, 05 June 2024, 01:37:05 P.M. now()
-60m 60 minutes ago Wednesday, 05 June 2024, 12:37:05 P.M. -60m@s
-1h@h 1 hour ago, to the hour Wednesday, 05 June 2024, 12:00:00 P.M.
-1d@d Yesterday Tuesday, 04 June 2024, 12:00:00 A.M.
-24h 24 hours ago (yesterday) Tuesday, 04 June 2024, 01:37:05 P.M. -24h@s
-7d@d 7 days ago, 1 week ago today Wednesday, 29 May 2024, 12:00:00 A.M.
-7d@m 7 days ago, snap to minute boundary Wednesday, 29 May 2024, 01:37:00 P.M.
@w0 Beginning of the current week Sunday, 02 June 2024, 12:00:00 A.M.
+1d@d Tomorrow Thursday, 06 June 2024, 12:00:00 A.M.
+24h 24 hours from now, tomorrow Thursday, 06 June 2024, 01:37:05 P.M. +24h@s

See also

Related information
Timestamps and time ranges
Time modifiers
Using time variables
Time zones
Last modified on 10 June, 2024
Time modifiers   Specifying time spans

This documentation applies to the following versions of Splunk® Cloud Services: current


Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters