Duration
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.
Import
from surrealdb import Duration
Fields
| Field | Type | Description |
|---|
elapsed | int | The duration in nanoseconds. |
Constructor
Syntax
Duration(elapsed)
| Parameter | Type | Description |
|---|
elapsed required | int | The duration in nanoseconds. |
d = Duration(5_000_000_000)
print(d.seconds)
Static Methods
Duration.parse()
Parses a duration from a string or integer value. String values support SurrealDB duration syntax, including compound durations.
Syntax
Duration.parse(value, nanoseconds=0)
| Parameter | Type | Description |
|---|
value required | str | int | A duration string (e.g. “1h30m”, “500ms”) or an integer in nanoseconds. |
nanoseconds optional | int | Additional nanoseconds to add. Defaults to 0. |
Returns: Duration
Examples
d = Duration.parse("1h30m")
print(d.minutes)
d = Duration.parse("500ms")
print(d.milliseconds)
d = Duration.parse("2d12h")
print(d.hours)
d = Duration.parse(1_000_000_000)
print(d.seconds)
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). |
d = Duration.parse("2h30m")
print(d.hours)
print(d.minutes)
print(d.seconds)
Methods
to_string()
Returns the duration as a human-readable string.
Syntax
duration.to_string()
Returns: str
d = Duration.parse("1h30m")
print(d.to_string())
to_compact()
Returns the duration as a compact list of integer values.
Syntax
duration.to_compact()
Returns: list[int]
d = Duration.parse("1h30m")
print(d.to_compact())
Usage
from surrealdb import Surreal, Duration
db = Surreal("ws://localhost:8000")
db.connect()
db.use("my_ns", "my_db")
db.signin({"username": "root", "password": "root"})
db.create("tasks", {
"title": "Backup",
"interval": Duration.parse("6h"),
})
See Also
