> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://rivet.chrisboulton.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://rivet.chrisboulton.com/_mcp/server.

# Date and time functions

> Signatures, behavior, examples, and Rivet compatibility boundaries.

All timestamps are RFC 3339 strings you supply. These functions never read the current clock.

| Function                         | Result and rules                                                      |
| -------------------------------- | --------------------------------------------------------------------- |
| `formatdate(pattern, timestamp)` | Format a timestamp with the tokens below.                             |
| `timeadd(timestamp, duration)`   | Add a signed duration; returns RFC 3339 with whole-second formatting. |
| `timecmp(left, right)`           | Compare instants; -1 if left is earlier, 0 if equal, 1 if later.      |

`timeadd` accepts signed combinations of `h`, `m`, `s`, `ms`, `us`, `µs`, `μs`, and `ns`, including fractional units and bare `0`. Duration arithmetic is bounded to signed 64-bit nanoseconds; nonrepresentable timestamps fail. Output formatting omits subsecond precision. Resource timeout and schedule fields use their own duration rules.

| Token                    | Meaning                                           |
| ------------------------ | ------------------------------------------------- |
| `YYYY`, `YY`             | Four-/two-digit year.                             |
| `MMMM`, `MMM`, `MM`, `M` | Full/short month name, padded and unpadded month. |
| `DD`, `D`                | Padded/unpadded day.                              |
| `EEEE`, `EEE`            | Full/short weekday name.                          |
| `hh`, `h`                | Padded/unpadded 24-hour hour.                     |
| `HH`, `H`                | Padded/unpadded 12-hour hour.                     |
| `mm`, `m`, `ss`, `s`     | Padded/unpadded minute or second.                 |
| `AA`, `aa`               | AM/PM in upper-/lowercase.                        |
| `ZZZZZ`, `Z`             | Colon-separated offset; Z renders `Z` at UTC.     |
| `ZZZZ`, `ZZZ`            | Compact offset; ZZZ renders `UTC` at UTC.         |

Quote literal alphabetic text with single quotes; doubled single quotes emit a quote. Unknown tokens fail. Clock/random functions such as `timestamp` and `plantimestamp` are unavailable.

## Example

```hcl
locals {
  times = {
    date = formatdate("YYYY-MM-DD", "2026-01-01T00:00:00Z")
    later = timeadd("2026-01-01T00:00:00Z", "1h30m")
    order = timecmp("2026-01-01T00:00:00Z", "2026-01-02T00:00:00Z")
  }
}
output "times" {
  type  = string
  value = jsonencode(local.times)
}
```

All calls obey the [function limits and annotation rules](/language/functions).