# `formatTimestamp`

## Description

Returns a timestamp formatted as a string, with optional control over the output format and time zone.

## Syntax

Like many functions in DataPrime, `formatTimestamp` supports [two notations](https://coralogix.com/docs/dataprime/language-reference/functions-reference/index.md), **function** and **method** notation. These interchangeable forms allow flexibility in how you structure expressions.

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

```dataprime
(timestamp: timestamp).formatTimestamp(format?: string, tz?: string): string
```

## Arguments

| Name      | Type      | Required  | Description                                                  |
| --------- | --------- | --------- | ------------------------------------------------------------ |
| timestamp | timestamp | **true**  | The timestamp to format                                      |
| format    | string    | **false** | The format specification. Defaults to `iso8601`              |
| tz        | string    | **false** | A valid time zone string (see Time Zone section for details) |

## Example 1

Print a timestamp with a +5h offset using the default format\*\*

### Example query

```dataprime
choose formatTimestamp($m.timestamp, tz='+05') as ts
```

```dataprime
choose $m.timestamp.formatTimestamp(tz='+05') as ts
```

### Example output

```json
{
    "ts": "2023-08-29T19:08:37.405937400+0500"
}
```

## Example 2

**Use case 2: Print only the year and month**

### Example query

```dataprime
choose formatTimestamp($m.timestamp, '%Y-%m') as ym
```

```dataprime
choose $m.timestamp.formatTimestamp('%Y-%m') as ym
```

### Example output

```json
{
    "ym": "2023-08"
}
```

## Example 3

**Use case 3: Print only the hours and minutes**

### Example query

```dataprime
choose formatTimestamp($m.timestamp, '%H:%M') as hm
```

```dataprime
choose $m.timestamp.formatTimestamp('%H:%M') as hm
```

### Example output

```json
{
"hm": "14:11"
}
```

## Example 4

**Use case 4: Print a timestamp in milliseconds (13 digits)**

### Example query

```dataprime
choose formatTimestamp($m.timestamp, 'timestamp_milli') as ms
```

```dataprime
choose $m.timestamp.formatTimestamp('timestamp_milli') as ms
```

### Example output

```json
{
    "ms": "1693318678696"
}
```