> ## Documentation Index
> Fetch the complete documentation index at: https://new.docs.falkordb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# date.format

> Formats a date/time value using a token-based pattern, with optional timezone offset adjustment.

## Description

Formats a date/time value using a simple token-based pattern. Supports common date/time tokens and optional timezone offset adjustment.

## Syntax

```cypher theme={null}
flex.date.format(datetime, pattern, timezone)
```

## Parameters

| Parameter  | Type               | Required | Description                                                       |
| ---------- | ------------------ | -------- | ----------------------------------------------------------------- |
| `datetime` | Date/number/string | Yes      | The date/time value to format                                     |
| `pattern`  | string             | No       | Format pattern using tokens (default: `'YYYY-MM-DDTHH:mm:ss[Z]'`) |
| `timezone` | string             | No       | Timezone offset like `"+02:00"` or `"-05:00"`                     |

### Supported Pattern Tokens

| Token  | Description            | Example |
| ------ | ---------------------- | ------- |
| `YYYY` | 4-digit year           | `2024`  |
| `MM`   | 2-digit month (01-12)  | `03`    |
| `DD`   | 2-digit day (01-31)    | `15`    |
| `HH`   | 2-digit hour (00-23)   | `14`    |
| `mm`   | 2-digit minute (00-59) | `30`    |
| `ss`   | 2-digit second (00-59) | `45`    |
| `SSS`  | 3-digit milliseconds   | `123`   |
| `[Z]`  | Literal `Z` character  | `Z`     |

## Returns

**Type:** string

A formatted date/time string according to the pattern. Returns `null` if the input date is invalid.

## Examples

### Example 1: Basic Date Formatting

```cypher theme={null}
WITH datetime('2024-03-15T14:30:00Z') AS dt
RETURN flex.date.format(dt, 'YYYY-MM-DD') AS date
```

**Output:**

```text theme={null}
date
----------
2024-03-15
```

### Example 2: Full DateTime with Time

```cypher theme={null}
WITH datetime('2024-03-15T14:30:45Z') AS dt
RETURN flex.date.format(dt, 'YYYY-MM-DD HH:mm:ss') AS formatted
```

**Output:**

```text theme={null}
formatted
-------------------
2024-03-15 14:30:45
```

### Example 3: Custom Format with Timezone

```cypher theme={null}
WITH datetime('2024-03-15T14:30:00Z') AS dt
RETURN flex.date.format(dt, 'DD/MM/YYYY HH:mm', '+02:00') AS localTime
```

**Output:**

```text theme={null}
localTime
-----------------
15/03/2024 16:30
```

(Adjusted for +02:00 timezone)

### Example 4: Formatting Node Timestamps

```cypher theme={null}
MATCH (e:Event)
RETURN e.name, flex.date.format(e.timestamp, 'YYYY-MM-DD') AS eventDate
ORDER BY e.timestamp DESC
```

## Notes

* Returns `null` for invalid date inputs
* Default pattern is ISO8601-like: `'YYYY-MM-DDTHH:mm:ss[Z]'`
* Timezone parameter adjusts the displayed time for the given offset
* All calculations are UTC-based internally
* Milliseconds are optional in the pattern

## See Also

* [date.parse](/udfs/flex/date/parse) - Parse string to date
* [date.truncate](/udfs/flex/date/truncate) - Truncate date to specific unit
* [date.toTimeZone](/udfs/flex/date/toTimeZone) - Convert date to timezone

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What format tokens does flex.date.format support?">
    Common tokens include `yyyy` (year), `MM` (month), `dd` (day), `HH` (hour), `mm` (minute), `ss` (second). The function uses token-based pattern formatting.
  </Accordion>

  <Accordion title="Can I include a timezone offset in the format?">
    Yes. Pass an optional timezone offset parameter to adjust the output before formatting.
  </Accordion>
</AccordionGroup>