# 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`](https://coralogix.com/docs/dataprime/language-reference/functions-reference/time/now/index.md), [`diffTime`](https://coralogix.com/docs/dataprime/language-reference/functions-reference/time/difftime/index.md), [`addTime`](https://coralogix.com/docs/dataprime/language-reference/functions-reference/time/addtime/index.md), and [`formatInterval`](https://coralogix.com/docs/dataprime/language-reference/functions-reference/time/formatinterval/index.md).

## 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()`](https://coralogix.com/docs/dataprime/language-reference/functions-reference/time/now/index.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

```dataprime
now(): timestamp
```

### Example: Add query time to each document

#### Query

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

#### Result

```json
{
  "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

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

#### Query

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

#### Result

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

______________________________________________________________________

## Measuring durations with `diffTime`

### Description

The [`diffTime()`](https://coralogix.com/docs/dataprime/language-reference/functions-reference/time/difftime/index.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

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

### Example: Calculate time since event

#### Sample data

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

#### Query

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

#### Result

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

______________________________________________________________________

## Adding time with `addTime`

### Description

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

### Syntax

```dataprime
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

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

#### Query

```dataprime
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

```text
{
    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()`](https://coralogix.com/docs/dataprime/language-reference/functions-reference/time/formatinterval/index.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

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

### Example: Normalize durations to milliseconds

#### Sample data

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

#### Query

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

#### Result

```json
{ "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()`](https://coralogix.com/docs/dataprime/language-reference/functions-reference/time/formatinterval/index.md) function converts a timestamp into a formatted string using either a format keyword or a strftime-style pattern.

### Syntax

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

### Example: Format as human-readable date

#### Sample data

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

#### Query

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

#### Result

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

#### 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://coralogix.com/docs/dataprime/language-reference/functions-reference/time/timestamp_formats/index.md).

______________________________________________________________________

## 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