Time and timezone queries
InfluxQL is designed for working with time series data and includes features specifically for working with time. You can review the following ways to work with time and timestamps in your InfluxQL queries:
- Configuring returned timestamps
- Time syntax
- Absolute time
- Relative time
- The Time Zone clause
- Common issues with time syntax
Configuring returned timestamps
The InfluxQL shell returns timestamps in
nanosecond UNIX epoch format by default.
Specify alternative formats with the
precision <format> command.
If you are using the InfluxQL shell, use the precision helper command precision rfc3339 to view results in human readable format.
The InfluxDB API returns timestamps
in RFC3339 format by default.
Specify alternative formats with the
epoch query string parameter.
Time syntax
For most SELECT statements, the default time range is between 1677-09-21 00:12:43.145224194 and 2262-04-11T23:47:16.854775806Z UTC.
For SELECT statements with a GROUP BY time() clause,
the default time range is between 1677-09-21 00:12:43.145224194 UTC and now().
The following sections detail how to specify alternative time ranges in the SELECT
statement’s WHERE clause.
Other supported features include:
Absolute time
Relative time
Absolute time
Specify absolute time with date-time strings and epoch time.
Syntax
SELECT_clause FROM_clause WHERE time <operator> ['<rfc3339_date_time_string>' | '<rfc3339_like_date_time_string>' | <epoch_time>] [AND ['<rfc3339_date_time_string>' | '<rfc3339_like_date_time_string>' | <epoch_time>] [...]]
Supported operators
| Operator | Meaning |
|---|---|
= | equal to |
<> | not equal to |
!= | not equal to |
> | greater than |
>= | greater than or equal to |
< | less than |
<= | less than or equal to |
Currently, InfluxDB does not support using OR with absolute time in the WHERE
clause. See the Frequently Asked Questions
document and the GitHub Issue
for more information.
rfc3339_date_time_string
'YYYY-MM-DDTHH:MM:SS.nnnnnnnnnZ'
.nnnnnnnnn is optional and is set to .000000000 if not included.
The RFC3339 date-time string requires single quotes.
rfc3339_like_date_time_string
'YYYY-MM-DD HH:MM:SS.nnnnnnnnn'
HH:MM:SS.nnnnnnnnn.nnnnnnnnn is optional and is set to 00:00:00.000000000 if not included.
The RFC3339-like date-time string requires single quotes.
epoch_time
Epoch time is the amount of time that has elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970.
By default, InfluxDB assumes that all epoch timestamps are in nanoseconds. Include a duration literal at the end of the epoch timestamp to indicate a precision other than nanoseconds.
Basic arithmetic
All timestamp formats support basic arithmetic.
Add (+) or subtract (-) a time from a timestamp with a duration literal.
Note that InfluxQL requires a whitespace between the + or - and the
duration literal.
Examples
Relative time
Use now() to query data with timestamps relative to the server’s current timestamp.
Syntax
SELECT_clause FROM_clause WHERE time <operator> now() [[ - | + ] <duration_literal>] [(AND|OR) now() [...]]
now() is the Unix time of the server at the time the query is executed on that server.
The whitespace between - or + and the duration literal is required.
Supported operators
| Operator | Meaning |
|---|---|
= | equal to |
<> | not equal to |
!= | not equal to |
> | greater than |
>= | greater than or equal to |
< | less than |
<= | less than or equal to |
duration_literal
- microseconds:
uorµ - milliseconds:
ms - seconds
s - minutes
m - hours:
h - days:
d - weeks:
w
Examples
The Time Zone clause
Use the tz() clause to return the UTC offset for the specified timezone.
Syntax
SELECT_clause FROM_clause [WHERE_clause] [GROUP_BY_clause] [ORDER_BY_clause] [LIMIT_clause] [OFFSET_clause] [SLIMIT_clause] [SOFFSET_clause] tz('<time_zone>')
By default, InfluxDB stores and returns timestamps in UTC.
The tz() clause includes the UTC offset or, if applicable, the UTC Daylight Savings Time (DST) offset to the query’s returned timestamps. The returned timestamps must be in RFC3339 format for the UTC offset or UTC DST to appear.
The time_zone parameter follows the TZ syntax in the Internet Assigned Numbers Authority time zone database and it requires single quotes.
Examples
Common issues with time syntax
Using OR to select time multiple time intervals
InfluxDB does not support using the OR operator in the WHERE clause to specify multiple time intervals.
For more information, see Frequently asked questions.
Querying data that occur after now() with a GROUP BY time() clause
Most SELECT statements have a default time range between 1677-09-21 00:12:43.145224194 and 2262-04-11T23:47:16.854775806Z UTC.
For SELECT statements with a GROUP BY time() clause,
the default time range is between 1677-09-21 00:12:43.145224194 UTC and now().
To query data with timestamps that occur after now(), SELECT statements with
a GROUP BY time() clause must provide an alternative upper bound in the
WHERE clause.
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.