Time and time zones
InfluxDB Clustered is currently only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.
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:
- Time syntax
- Query time range
- Query examples
- Time zone clause
- Notable behaviors
InfluxQL supports the following timestamp literal syntaxes:
'2006-01-02T15:04:05.00Z' -- RFC3339 date-time string '2006-01-02 15:04:05.00' -- RFC3339-like date-time string 1136189045000000000 -- Unix nanosecond epoch time 1136189045s -- Unix epoch time
- RFC3339 date-time string:
String literal using
the RFC3339 timestamp format,
- RFC3339-like date-time string:
String literal using
the RFC3339-like timestamp format,
- Unix nanosecond epoch time: Integer that represents the number of nanoseconds elapsed since the Unix epoch.
- Unix epoch time: Duration literal that represents the number of specified time units elapsed since the Unix epoch. View supported duration units.
Supported timestamp values
|RFC3339||Unix nanosecond time|
Add and subtract time values
Timestamp values support addition and subtraction operations with
+) or subtract (
-) a duration to or from a timestamp to return an
'2023-01-01T00:00:00Z' + 2h -- Resolves to 2023-01-01T02:00:00Z '2023-01-01 00:00:00' - 20h -- Resolves to 2022-12-31T04:00:00Z 1672531200000000000 + 1y -- Resolves to 2024-01-01T00:00:00Z
InfluxQL requires a whitespace between the
- and the duration literal.
Query time range
To specify the time range of a query, use conditional expressions in the
WHERE clause that
compare the value of the
time column to an absolute timestamp or a relative
Absolute time range: Define query time bounds with timestamp literals
WHERE time >= '2023-01-01T00:00:00Z' AND time <= '2023-07-01T00:00:00Z' WHERE time >= '2023-01-01 00:00:00' AND time <= '2023-07-01 00:00:00' WHERE time >= 1672531200000000000 AND time <= 1688169600000000000 WHERE time >= 1672531200s and time <= 1688169600000ms
Relative time range: Define query time bounds with a duration literal added to or subtracted from timestamp literals.
now()to return the current system time (UTC).
-- Query data from the last day WHERE time >= now() - 1d -- Query data from the previous week WHERE time >= now() - 1w AND time <= now() - 2w -- Query data relative to a specific time WHERE time >= '2023-01-01' - 1w AND time <= '2023-01-01' + 1w
Conditional expressions with time operands support the following comparison operators:
|not equal to|
|not equal to|
|greater than or equal to|
|less than or equal to|
Currently, InfluxQL supports the
AND logical operator to define query time bounds,
but does not support using the
OR logical operator to query multiple time ranges.
The following examples use the Get started home sensor sample dataset.
Time zone clause
InfluxQL in InfluxDB Clustered does not currently support the time zone clause, which applies a time zone offset to UTC timestamps in query results.
Tracking issue: influxdb_iox#6933
Cannot query multiple time ranges
InfluxDB does not support using
OR in the
WHERE clause to query multiple time ranges.
For example, the following query returns no results:
Querying future data with a
GROUP BY time() clause
Queries that do not specify time bounds in the
WHERE clause and do not include
GROUP BY time() clause use the minimum and maximum timestamps
as the default time range.
If the query includes a
GROUP BY time() clause, the default time range is
To query data with timestamps that occur in the future (after
provide an explicit upper bound in the
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.