Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdataprime%2Fuser-guide%2Fusing-dataprime%2Ftime.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdataprime%2Fuser-guide%2Fusing-dataprime%2Ftime.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# Using DataPrime to track time and durations

## Goal[​](#goal "Direct link to 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`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/now/.md), [`diffTime`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/difftime/.md), [`addTime`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/addtime/.md), and [`formatInterval`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/formatinterval/.md).

## Why it matters[​](#why-it-matters "Direct link to 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()`[​](#getting-the-current-time-with-now "Direct link to getting-the-current-time-with-now")

### Description[​](#description "Direct link to Description")

The [`now()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/now/.md) 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[​](#syntax "Direct link to Syntax")

```
now(): timestamp
```

### Example: Add query time to each document[​](#example-add-query-time-to-each-document "Direct link to Example: Add query time to each document")

#### Query[​](#query "Direct link to Query")

```
source logs

| create query_time from now()

| choose query_time
```

#### Result[​](#result "Direct link to 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[​](#time-arithmetic-in-dataprime "Direct link to Time arithmetic in DataPrime")

### Description[​](#description-1 "Direct link to 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[​](#example-round-timestamps-to-the-hour "Direct link to Example: Round timestamps to the hour")

#### Sample data[​](#sample-data "Direct link to Sample data")

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

#### Query[​](#query-1 "Direct link to Query")

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

#### Result[​](#result-1 "Direct link to Result")

```
{ "hour_bucket": 1757404800000000000 }
```

***

## Measuring durations with `diffTime`[​](#measuring-durations-with-difftime "Direct link to measuring-durations-with-difftime")

### Description[​](#description-2 "Direct link to Description")

The [`diffTime()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/difftime/.md) function returns the interval between two timestamps. Unlike subtraction, it ensures the result is always an `interval`, which can be formatted or compared.

### Syntax[​](#syntax-1 "Direct link to Syntax")

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

### Example: Calculate time since event[​](#example-calculate-time-since-event "Direct link to Example: Calculate time since event")

#### Sample data[​](#sample-data-1 "Direct link to Sample data")

```
{ "timestamp": 1728760000000000000 } 
```

#### Query[​](#query-2 "Direct link to Query")

```
source logs

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

| choose time_since_event
```

#### Result[​](#result-2 "Direct link to Result")

```
{ "time_since_event": "5m1s870ms735us" }
```

***

## Adding time with `addTime`[​](#adding-time-with-addtime "Direct link to adding-time-with-addtime")

### Description[​](#description-3 "Direct link to Description")

Use [`addTime()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/addtime/.md) to shift a timestamp forward by a specific duration. It’s useful for deadline or expiration calculations.

### Syntax[​](#syntax-2 "Direct link to Syntax")

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

### Example: Compute when a job should finish[​](#example-compute-when-a-job-should-finish "Direct link to Example: Compute when a job should finish")

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

#### Sample data[​](#sample-data-2 "Direct link to Sample data")

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

#### Query[​](#query-3 "Direct link to 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[​](#result-3 "Direct link to 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`[​](#formatting-durations-with-formatinterval "Direct link to formatting-durations-with-formatinterval")

### Description[​](#description-4 "Direct link to Description")

The [`formatInterval()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/formatinterval/.md) 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[​](#syntax-3 "Direct link to Syntax")

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

### Example: Normalize durations to milliseconds[​](#example-normalize-durations-to-milliseconds "Direct link to Example: Normalize durations to milliseconds")

#### Sample data[​](#sample-data-3 "Direct link to Sample data")

```
{ "duration": "2s" }
```

#### Query[​](#query-4 "Direct link to Query")

```
source spans

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

| choose duration_ms
```

#### Result[​](#result-4 "Direct link to 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`[​](#formatting-timestamps-with-formattimestamp "Direct link to formatting-timestamps-with-formattimestamp")

### Description[​](#description-5 "Direct link to Description")

The [`formatTimestamp()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/formatinterval/.md) function converts a timestamp into a formatted string using either a format keyword or a strftime-style pattern.

### Syntax[​](#syntax-4 "Direct link to Syntax")

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

### Example: Format as human-readable date[​](#example-format-as-human-readable-date "Direct link to Example: Format as human-readable date")

#### Sample data[​](#sample-data-4 "Direct link to Sample data")

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

#### Query[​](#query-5 "Direct link to Query")

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

#### Result[​](#result-5 "Direct link to Result")

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

#### Common formats[​](#common-formats "Direct link to Common formats")

| Format              | Output Example             |
| ------------------- | -------------------------- |
| `'%F %T'`           | `2025-10-15 12:00:00`      |
| `'iso8601'`         | `2025-10-15T12:00:00.000Z` |
| `'timestamp_milli'` | `1728919200000`            |

For full formatting options, see the [timestamp format chart](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/timestamp_formats/.md).

***

## Common pitfalls or gotchas[​](#common-pitfalls-or-gotchas "Direct link to 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