• /
  • EnglishEspañol日本語한국어Português
  • Log inStart now

Set a query's time range

We created NRQL to query telemetry data, and every query made with NRQL only considers telemetry data that falls within a specified time range. If a query request doesn't specify a time range, it defaults to reporting the last hour of telemetry data by default. Fortunately, we have multiple ways to set time ranges for your query so that you can get exactly the data you need from precise buckets of time.

Specify a time range

You can use two methods to specify the time range in your queries:

  • Use the dashboard time picker. When viewing a dashboard, the time picker's range supersedes a query's SINCE and UNTIL clauses, unless you've configured the dashboard widgets to disable the time picker.

  • Include SINCE and/or UNTIL. For example:

    FROM Foo SELECT * SINCE 2 days ago UNTIL 1 day ago

See the Specifying a time section below for a list of supported time formats.

Use time range snapping

You can sometimes adjust the specified SINCE and UNTIL times depending on the type of query you run with either metric or TIMESERIES range snapping.

Metric query snapping

Queries with metric events and some sample event types may need to adjust the time range based on the metric's roll-up time aggregations. For example:

FROM Metric SELECT sum(foo.count) SINCE '2023-12-20T00:04Z' UNTIL '2023-12-22T00:03Z'

Looking at the JSON response to this query, this 47-hour-and-59-minute time range resolves to 5-minute metric time aggregations, so the actual time range snaps to nearby aggregation boundaries: "beginTime": "2023-12-20T00:00:00Z", "endTime": "2023-12-22T00:00:00Z".

TIMESERIES query snapping

Queries with TIMESERIES may need to adjust the time range so the results do not include a partial time series bucket. For example:

FROM Foo SELECT count(*) TIMESERIES 5 minutes SINCE '2023-12-20T00:04:59Z' UNTIL '2023-12-21T00:03:12Z'

Looking at the JSON response to this query, the time series buckets base themselves on the end of the time range, and the start time is adjusted so the first bucket in the response covers a full 5 minutes: "beginTime": "2023-12-20T00:08:12Z", "endTime": "2023-12-21T00:03:12Z".

Specify a time with SINCE and UNTIL

You have a few ways to specify time in the SINCE and until UNTIL clauses.

Tip

For each of the options listed below, the default timezone is UTC. Note that the user's preferred timezone isn't used for query execution: the user timezone preference only displays DateTime values.

If you want to specify a timezone other than UTC for the time range, you can include it in the DateTime string option, or you can use NRQL's WITH TIMEZONE clause.

Unix time (Epoch Milliseconds)

The time can be referenced as Unix time in milliseconds. This is the number of milliseconds since 1970-01-01T00:00:00Z, or midnight on the 1st of January, 1970. For example:

FROM Foo SELECT * SINCE 1702899296789 UNTIL 1702902896789

These timestamp values resolve to a time range starting at 2023-12-18T11:34:56.789Z and ending at 2023-12-18T12:34:56.789Z.

Relative time (n [time units] ago)

Relative time can be referenced as n [time units] ago with the following components:

  • n: A positive integer value.
  • [time units]: Available time units include milliseconds, seconds, minutes, hours, days, weeks, months (defined as 30 days), quarters (defined as 91 days), or years (defined as 365 days). Time unit pluralization is optional, so you can leave the "s" off the end of the unit. 2 day ago and 2 days ago have the same meaning.

The time is relative to the time you run the query. For example, assume that you ran a query at 2023-12-18T12:34:56.789Z. You would get different results depending on what relative time value you used:

Relative time reference

Resolved time (UTC)

NOW (query execution time)

2023-12-18T12:34:56.789Z

2 milliseconds ago

2023-12-18T12:34:54..787Z

2 seconds ago

2023-12-18T12:34:54.789Z

2 minutes ago

2023-12-18T12:32:56.789Z

2 hours ago

2023-12-18T10:34:56.789Z

2 days ago

2023-12-16T12:34:56.789Z

2 weeks ago

2023-12-04T12:34:56.789Z

2 months ago

2023-10-19T12:34:56.789Z

2 quarters ago

2023-06-19T12:34:56.789Z

2 years ago

2021-12-18T12:34:56.789Z

Relative temporal time

You can also use relative time using temporal time references. These relative time references resolve to the beginning of the temporal time interval. A relative temporal time reference will honor a WITH TIMEZONE clause. Select a collapser below to see more information on specific temporal time references:

Use a DateTime string

You can specify a time range time using a DateTime string. The parser generally supports the ISO 8601 DateTime format: '2023-12-18T12:34:56.789-06:00'. But, the DateTime parser can also recognize variants of the ISO standard format, like '2023-12-18 12:34'. The parser also supports date-only ('2023-12-18') and time-only ('12:34:56') strings. We have the options and examples for using a DateTime string below:

Field

Details

Overall structure

[Date][TimeSeparator][Time][TimeZone][AM/PM]

Date

Year-Month-Day

  • Year - (required) 4-digit year value.

  • Month - (required) 2-digit month value.

  • Day - (optional) 2-digit day value.

    A DateTime string can include a Date without a Time, with the time value defaulting to midnight at the start of the given date. The dashes between date elements are optional (but recommended), so '20231218' is equivalent to '2023-12-18'.

TimeSeparator

Separates the date and time in a full DateTime string. Valid separating values are the capital letter T or a single space.

Time

Hour:Minute[[:Second].FractionalSecond]

  • Hour - (required) 1- or 2-digit hour value, 00-23. 2-digits is recommended, per the ISO 8601 specification.

  • Minute - (required) 2-digit minute value, 00-59.

  • :Second - (optional) 2-digit seconds value, 00-59.

  • [.FractionalSecond] - (optional) 1 to 3-digit fractional second (milliseconds) value, 000-999. Only available when a :Second value is included.

    A DateTime string can include a Time without a Date, with the date value defaulting to the current day. When a time is given without a date in the SINCE clause, if the time is in the future, the previous day will be used for the date.

    When a Time follows a T, the colons are optional (but recommended). If the colons are excluded, the Hour must include 2 digits and AM/PM is not allowed. So, '20231218T123456.789' is equivalent to '2023-12-18T12:34:56.789'.

TimeZone

Optional - If TimeZone is not included in a DateTime string, the time zone indicated in the query's WITH TIMEZONE clause will be used if present, otherwise the UTC timezone will be used.

The TimeZone value can optionally be preceded by a space. It can be indicated in various formats.

  • Offset - Indicates the timezone hours and minutes relative to UTC.

    (+|-)Hours[:]Minutes - i.e. Plus or minus, 2 digit hours, an optional colon, and finally 2 digit minutes. The letter Z is also supported, representing UTC, or an offset of zero.

    Examples: -0600, Z, +0530, +05:30

  • Zone ID in square brackets - A Zone ID is a textual name of a timezone. Most (but not all) Zone IDs consist of a region followed by a slash and then a subregion. An advantage of using a region based Zone ID is that the DateTime parser will automatically adjust for the zone's daylight saving time rules.

    Examples: [America/Los_Angeles], [Etc/GMT-6], [UTC]

    See the available Zone IDs list.

    Note, Zone IDs do not work when using AM/PM.

AM/PM

AM or PM can be added to the end of a DateTime string. If present, the Hour value is interpreted as a 12 hour value rather than a 24 hour value, with a range of 01-12 instead of 00-23.

Note, AM/PM is not supported with the Zone ID TimeZone format.

Timezones

Zone IDs

The following Zone IDs are valid for the WITH TIMEZONE clause, or as a bracketed timezone reference in a datetime string (ex. '2023-12-18T12:34 [America/Los_Angeles]').

Copyright © 2024 New Relic Inc.
CareersTerms of ServiceDMCA PolicyPrivacy NoticeCookie PolicyUK Slavery Act

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.