Using DataPrime to track time and durations

Goal

By the end of this guide you should be able to compute durations between timestamps, add or subtract time intervals, and format those durations for display using functions like now, diffTime, addTime, and formatInterval.

Why it matters

Time is one of the most critical dimensions in log analysis. Whether you're debugging latency issues, monitoring job runtimes, or visualizing trends over time, being able to work with time accurately is essential. This guide shows you how to transform raw timestamps into meaningful durations and formatted outputs using DataPrime’s built-in time functions.

Getting the current time with now()

Description

The now() function returns the current timestamp at the moment the query is executed. This is useful when measuring how recent an event is or marking the exact query runtime. The value is fixed across the entire query execution.

Syntax

now(): timestamp

Example: Add query time to each document

Query

source logs
| create query_time from now()
| choose query_time

Result

{
  "query_time": 1728764342873000000
}

Because now() always returns the same value across the entire query, it's safe to reuse it in multiple expressions without inconsistency.

Time arithmetic in DataPrime

Description

DataPrime supports rich arithmetic between timestamp and interval types, enabling powerful workflows for measuring durations, calculating deadlines, and rounding time buckets.

Supported operations:

Expression	Description	Result type
timestamp - timestamp	Time difference between two timestamps	interval
timestamp + interval	Adds time to a timestamp	timestamp
timestamp - interval	Subtracts time from a timestamp	timestamp
timestamp / interval	Rounds down a timestamp to a fixed time window	timestamp
interval + interval	Adds two durations	interval
interval - interval	Subtracts one interval from another	interval
interval * number	Scales an interval by a numeric factor	interval

Example: Round timestamps to the hour

Sample data

{ "timestamp": 1757404820349995300 }  // 2025-10-15T12:00:00Z

Query

create hour_bucket from $m.timestamp / 1.toInterval('h')

Result

{ "hour_bucket": 1757404800000000000 }

Measuring durations with diffTime

Description

The diffTime() function returns the interval between two timestamps. Unlike subtraction, it ensures the result is always an interval, which can be formatted or compared.

Syntax

diffTime(to: timestamp, from: timestamp): interval

Example: Calculate time since event

Sample data

{ "timestamp": 1728760000000000000 } 

Query

source logs
| create time_since_event from diffTime(now(), $m.timestamp)
| choose time_since_event

Result

{ "time_since_event": "5m1s870ms735us" }

Adding time with addTime

Description

Use addTime() to shift a timestamp forward by a specific duration. It’s useful for deadline or expiration calculations.

Syntax

addTime(ts: timestamp, delta: interval): timestamp

Example: Compute when a job should finish

Scenario: Each job takes 30 seconds, and you want to compute when it should complete.

Sample data

{ "timestamp": 1757404799999636000, "duration": 344 }

Query

source spans
| create expected_end_time from addTime($m.timestamp, duration.toInterval('s'))
| choose 
    duration,
    $m.timestamp.formatTimestamp('iso8601') as start,
    expected_end_time.formatTimestamp('iso8601') as end

Result

{
    duration: 344
    end: 2025-09-09T08:05:43.999636+0000
    start: 2025-09-09T07:59:59.999636+0000
    timestamp: 1757404799999636000
}

Formatting durations with formatInterval

Description

The formatInterval() function formats an interval in a specific unit like "ms", "s", or "h". This is useful when you care about displaying durations in a uniform and human-readable way.

Syntax

formatInterval(interval: interval, unit?: string): string

Example: Normalize durations to milliseconds

Sample data

{ "duration": "2s" }

Query

source spans
| create duration_ms from formatInterval(duration:interval, 'ms')
| choose duration_ms

Result

{ "duration_ms": "2000ms14us" }

This will return the spans with ms as the largest unit. This function is most helpful when comparing across documents with variable interval formats.

Formatting timestamps with formatTimestamp

Description

The formatTimestamp() function converts a timestamp into a formatted string using either a format keyword or a strftime-style pattern.

Syntax

formatTimestamp(timestamp: timestamp, format: string): string

Example: Format as human-readable date

Sample data

{ "timestamp": 1728919200000000000 }  // 2025-10-15T12:00:00Z

Query

create readable_time from formatTimestamp($m.timestamp, '%F %H:%M:%S')

Result

{ "readable_time": "2025-10-15 12:00:00" }

Common formats

For full formatting options, see the timestamp format chart.

Common pitfalls or gotchas

• Direction matters in diffTime — if to < from, you’ll get a negative interval.
• Always use .toInterval('s') or similar when your duration field is a number.
• formatInterval does not cascade across units. It shows only the specified unit (e.g., 300s, not 5m0s).
• Double check the output type when doing time-based arithmetic