> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Datetimes

SurrealDB has native support for datetimes with nanosecond precision. SurrealDB is able to parse datetimes from strings.

SurrealDB has native support for datetimes with nanosecond precision. A datetime is written as a string with a `d` prefix, or cast from a string with `<datetime>`, and the string must be in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format. A string without the prefix or the cast stays a string, even when its contents look like a datetime, so it cannot be used in datetime arithmetic.

```surql
"2022-07-03T00:00:00Z" + 18y;
//- "Cannot perform addition with 'string' and 'duration'"

d"2022-07-03T00:00:00Z" + 18y;
//- d'2040-06-28T00:00:00Z'
```

Datetimes are represented by and can be created using a `d` prefix in front of a string.

```surql
CREATE event SET time = d"2025-07-03T07:18:52Z";
```

SurrealDB handles all datetimes with nanosecond precision.

```surql
CREATE event SET time = d"2025-07-03T07:18:52.841147Z";
```

A datetime can be created with a timezone, which will be converted and stored as a UTC date.

```surql
d"2025-07-03T07:18:52.841147+02:00";

-- Output:
d'2025-07-03T05:18:52.841147Z';
```

A `datetime` can also be created by using `<datetime>` to cast from a string.

With correct input:

```surql
CREATE event SET time = <datetime>"2025-07-03T07:18:52.841147Z";
```

```surql title="Output"
[
    { 
        id: event:jwm8ncmfi30nrxdf24ws, 
        time: d'2025-07-03T07:18:52.841147Z' 
    }
]
```

With incorrect input (missing final Z):

```surql
CREATE event SET time = <datetime>"2025-07-03T07:18:52.841147";
```

```surql title="Output"
"Expected a datetime but cannot convert '2025-07-03T07:18:52.841147' into a datetime"
```

As a convenience, a date containing a year, month and day but no time will also parse correctly as a datetime.

```surql
CREATE event SET time = <datetime>"2024-04-03";
```

```surql title="Output"
[
    { 
        id: event:4t50wjjlne9v8km2qcwq, 
        time: d'2024-04-03T00:00:00Z' 
    }
]
```

## Datetime types in `DEFINE FIELD` statements

Defining a field with a set `datetime` type will ensure that datetimes are properly formatted and not passed on as simple strings.

```surql
DEFINE FIELD time ON event TYPE datetime;
// highlight-next-line
CREATE event SET time = "2025-07-03T07:18:52.841147";
```

```surql title="Output"
"Couldn't coerce value for field `time` of `event:qv8qcjf0w9oowekl36w6`:
Expected `datetime` but found `'2025-07-03T07:18:52.841147'`"
```

The above query will fail because the datetime is not cast as a datetime type. The correct input is:

```surql
DEFINE FIELD time ON event TYPE datetime;
// highlight-next-line
CREATE event SET time = d"2025-07-03T07:18:52.84114Z";
```

```surql title="Output"
[
    { 
        id: event:w2lhv58f7c9z7xo4nqkq, 
        time: d'2025-07-03T07:18:52.841140Z' 
    }
]
```

### Datetime comparison
A datetime can be compared with another using SurrealDB operators.

```surql
d"2025-07-03T07:18:52Z" < d"2025-07-03T07:18:52.84114Z";
```

```surql title="Output"
true
```

## Durations and datetimes

A duration can be used to alter a datetime.

```surql
CREATE event SET time = d"2025-07-03T07:18:52Z" + 2w;
```

```surql title="Output"
[
    { 
        id: event:`9ey7v8r0fd46xblf9dsf`, 
        time: d'2025-07-17T07:18:52Z' 
    }
]
```

Multi-part durations can also be used to modify datetimes.

```surql
CREATE event SET 
    time = d"2025-07-03T07:18:52.841147Z" + 1h30m20s1350ms;
```

```surql title="Output"
[
    { 
        id: event:5uuzy32t48yutxyszi7p, 
        time: d'2025-07-03T08:49:14.191147Z' 
    }
]
```

## Altering datetimes

_(since v3.0.2)_

Each value in a datetime can be set by using one of seven `time::set_` functions. Each of these function names ends with the part of the datetime that is modified, such as `time::set_year()` or `time::set_hour()`.

```surql
d'1970-01-01T00:00:00.000000100Z'.set_year(1914);
-- Output
d'1914-01-01T00:00:00.000000100Z'
```

As these functions do not modify an existing datetime but return a new one, they can be chained one after another.

```surql
d'1970-01-01T00:00:00.000000100Z'
    .set_year(1914)
    .set_month(6)
    .set_day(28);

-- Output
d'1914-06-28T00:00:00.000000100Z'
```

## See also

* [time](/docs/reference/query-language/functions/database-functions/time.md) functions, which enable extracting, altering, rounding, and grouping datetimes into specific time intervals

## Learn more about this topic

- [2: Improving the existing data](https://surrealdb.com/learn/movies/page-02#released) (SurrealDB University, section "Released")