Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 39 ยท Concepts and Data Model

Timestamps, Precision and Time Zones

Understand InfluxDB timestamps: nanosecond epoch values, write precision, RFC 3339 in queries, the duplicate-point rule and how to handle time zones.

Time is the one piece of an InfluxDB point you cannot leave out of your thinking. Every point has a timestamp; if you do not supply one, the server stamps the point with the time it received it. Getting timestamps right avoids three classic problems: points in the year 1970, points overwriting each other and dashboards that are off by exactly your time-zone offset.

This lesson explains how InfluxDB stores time, how precision works on writes, how the "same timestamp" rule behaves and what to do about time zones.

Time is stored in UTC with nanosecond resolution

InfluxDB stores timestamps as the number of nanoseconds since the Unix epoch (1970-01-01T00:00:00Z) in UTC. Queries and the UI show them in RFC 3339 form, for example 2026-03-01T10:00:00Z. There is no time-zone stored with the data: the instant is absolute, and converting to local time is a display concern.

Unit 2026-03-01T10:00:00Z as an integer
Seconds 1772359200
Milliseconds 1772359200000
Microseconds 1772359200000000
Nanoseconds 1772359200000000000

Write precision

Line protocol timestamps are integers, and the server must know their unit. The default is nanoseconds. If your integers are seconds and you do not say so, the server reads 1772359200 as 1.77 seconds after the epoch, and your data lands in January 1970.

You state the unit with the precision parameter of the write:

Terminal
# 2.x HTTP API: precision can be ns, us, ms or s
curl --request POST \
  "http://localhost:8086/api/v2/write?org=my-org&bucket=my-bucket&precision=s" \
  --header "Authorization: Token $INFLUX_TOKEN" \
  --data-binary 'room,name=kitchen temp=21.5 1772359200'

# 3.x: the accepted values include auto, nanosecond, microsecond, millisecond, second
influxdb3 write --database home --precision second \
  'room,name=kitchen temp=21.5 1772359200'

When you omit the timestamp entirely, the server uses its own clock at the time of arrival, in nanoseconds. That is fine for live metrics collected right now, but wrong for imports of historical data and for batches that may be delayed.

This stand-in converts between units and shows what happens with the wrong precision. It is plain JavaScript; the arithmetic is the same the server does.

JS Reading an integer timestamp with the wrong unit (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Only precision=s gives the intended date; the other readings produce 1970. Make a habit of always passing precision explicitly when you write timestamps yourself.

The same-timestamp rule

A point's identity is measurement + tag set + timestamp. If you write a second point with exactly that identity, it does not create a new row: the new field values are merged into the existing point. Fields present in both are overwritten by the newer write; fields only in the old point stay.

TEXT
room,name=kitchen temp=21.5,humidity=48 1772359200
room,name=kitchen temp=22.0            1772359200
-> one point: temp=22.0, humidity=48

This gives you idempotent writes: replaying the same batch after a network failure produces no duplicates. It also means that two different readings stamped with the same second and same tags will silently collapse into one. If your data can have several distinct events per timestamp and series (for example log lines), add a tag or a timestamp with enough precision to tell them apart, or use a sequence field.

JS Merge-on-write for equal timestamps (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Querying time

Time ranges are the first filter of every query. Flux and InfluxQL accept relative times (-1h, now() - 1h) and absolute times in RFC 3339 (2026-03-01T00:00:00Z) or as epoch integers. SQL in InfluxDB 3 uses timestamp literals and intervals:

TEXT
SELECT * FROM room
WHERE time >= now() - INTERVAL '1 hour'

SELECT * FROM room
WHERE time >= '2026-03-01T00:00:00Z' AND time < '2026-03-02T00:00:00Z'

Use half-open ranges (>= start AND < end) so that adjacent windows never count a boundary point twice. The next block demonstrates that idea in SQLite.

SQL Half-open ranges avoid double counting (SQLite stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Two hours of data from 10:00 to 12:00 hold exactly 3 events; the closed version counts the 11:00 point twice.

Time zones

Because storage is UTC, time-zone handling is for presentation and for day boundaries.

  • Write in UTC, always. Convert device-local times before sending.
  • For "per day" reports, windows must align with local midnight, not UTC midnight. Flux has timezone and location options; InfluxQL accepts tz('Europe/Berlin'); SQL in 3.x can use AT TIME ZONE.
  • Daylight saving makes some local days 23 or 25 hours long. Fixed-length windows in UTC avoid this; calendar-aware windows need time-zone support.
TEXT
-- InfluxQL: daily means in Berlin time
SELECT mean("temp") FROM "room" WHERE time >= '2026-03-01T00:00:00Z'
GROUP BY time(1d) tz('Europe/Berlin')

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the default unit of a line protocol timestamp?

    Unless you pass a precision, the integer is read as nanoseconds since the epoch.
  2. 2. You write 1772359200 without a precision parameter. Where does the point land?

    The integer is interpreted as nanoseconds, so it is a time in January 1970.
  3. 3. Two writes have the same measurement, tags and timestamp. What happens?

    Point identity is measurement, tag set and timestamp, so later field values overwrite or add to the existing point.
  4. 4. In which time zone does InfluxDB store timestamps?

    Timestamps are absolute instants in UTC; zones are applied only for display and calendar windows.

Summary

  • Timestamps are nanoseconds since the epoch in UTC; queries show RFC 3339 times.
  • Always pass the write precision that matches your integers; the default is nanoseconds.
  • Same measurement, tags and timestamp means the same point: writes merge, which makes retries safe.
  • Use half-open time ranges and write in UTC, applying time zones only for display and daily windows.

Next: Buckets, Organizations and Tokens