# Duration

Duration type with nanosecond precision and unit conversion properties.

A `Duration` stores a time duration with nanosecond precision. It supports parsing from human-readable strings (including compound formats like `"1h30m"`) and provides properties for converting to common time units.

`Duration` is a Python dataclass.

```python title="Import"
from surrealdb import Duration
```

---

## Fields {#fields}

| Field | Type | Description |
|---|---|---|
| `elapsed` | `int` | The duration in nanoseconds. |

---

## Constructor {#constructor}

```python title="Syntax"
Duration(elapsed)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>elapsed</code> _(required)_</td>
            <td><code>int</code></td>
            <td>The duration in nanoseconds.</td>
        </tr>
    </tbody>
</table>

```python
d = Duration(5_000_000_000)
print(d.seconds)  # 5.0
```

---

## Static methods {#static-methods}

### `Duration.parse()` {#parse}

Parses a duration from a string or integer value. String values support SurrealDB duration syntax, including compound durations.

```python title="Syntax"
Duration.parse(value, nanoseconds=0)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>value</code> _(required)_</td>
            <td><code>str | int</code></td>
            <td>A duration string (e.g. <code>"1h30m"</code>, <code>"500ms"</code>) or an integer in nanoseconds.</td>
        </tr>
        <tr>
            <td><code>nanoseconds</code> _(optional)_</td>
            <td><code>int</code></td>
            <td>Additional nanoseconds to add. Defaults to <code>0</code>.</td>
        </tr>
    </tbody>
</table>

**Returns:** `Duration`

### Examples

```python
d = Duration.parse("1h30m")
print(d.minutes)  # 90.0

d = Duration.parse("500ms")
print(d.milliseconds)  # 500.0

d = Duration.parse("2d12h")
print(d.hours)  # 60.0

d = Duration.parse(1_000_000_000)
print(d.seconds)  # 1.0
```

---

## Properties {#properties}

All unit properties return a `float`.

| Property | Type | Description |
|---|---|---|
| `nanoseconds` | `float` | Duration in nanoseconds. |
| `microseconds` | `float` | Duration in microseconds. |
| `milliseconds` | `float` | Duration in milliseconds. |
| `seconds` | `float` | Duration in seconds. |
| `minutes` | `float` | Duration in minutes. |
| `hours` | `float` | Duration in hours. |
| `days` | `float` | Duration in days. |
| `weeks` | `float` | Duration in weeks. |
| `years` | `float` | Duration in years (365-day). |

```python
d = Duration.parse("2h30m")
print(d.hours)    # 2.5
print(d.minutes)  # 150.0
print(d.seconds)  # 9000.0
```

---

## Methods {#methods}

### `to_string()` {#to-string}

Returns the duration as a human-readable string.

```python title="Syntax"
duration.to_string()
```

**Returns:** `str`

```python
d = Duration.parse("1h30m")
print(d.to_string())  # "1h30m"
```

### `to_compact()` {#to-compact}

Returns the duration as a compact list of integer values.

```python title="Syntax"
duration.to_compact()
```

**Returns:** `list[int]`

```python
d = Duration.parse("1h30m")
print(d.to_compact())
```

---

## Usage {#usage}

```python
from surrealdb import Surreal, Duration

db = Surreal("ws://localhost:8000")
db.connect()
db.use("my_ns", "my_db")
db.signin({"username": "root", "password": "secret"})

db.create("tasks", {
    "title": "Backup",
    "interval": Duration.parse("6h"),
})
```

---

## See also

- [Data types](/docs/reference/python/api/values.md) - All SDK data types
- [Datetime](/docs/reference/python/api/values/datetime.md) - Datetime wrapper