Value types

The Python SDK maps SurrealDB data types to Python types automatically. Standard Python types like str, int, float, bool, None, dict, and list map directly to their SurrealDB equivalents. For SurrealDB-specific types such as record identifiers, durations, and geometry, the SDK provides dedicated Python classes.

See the Data Types reference for the full API details of each type.

API References

Type mapping between Python and SurrealDB

The following table shows how Python types correspond to SurrealDB types. Standard library types are used directly, while SurrealDB-specific types use the custom classes listed above.

Working with record identifiers

A RecordID uniquely identifies a single record in a table by combining a table name with an identifier value. You can construct one directly or parse it from a string.

from surrealdb import RecordID

record = RecordID("users", "tobie")
print(record.table_name)  # "users"
print(record.id)          # "tobie"

parsed = RecordID.parse("users:tobie")
print(parsed.table_name)  # "users"

The identifier can be a string, integer, list, or any other supported value type. Use RecordID wherever the SDK expects a record reference, such as in .select(), .create(), or .delete().

from surrealdb import Surreal, RecordID

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

    db.create(RecordID("users", "tobie"), {
        "name": "Tobie",
        "email": "tobie@surrealdb.com",
    })

    user = db.select(RecordID("users", "tobie"))

See the RecordID reference for the complete API, including equality checks and Pydantic support.

Working with durations

A Duration represents a time span with nanosecond precision. The most common way to create one is by parsing a human-readable string using SurrealDB's duration syntax.

from surrealdb import Duration

d = Duration.parse("1h30m")
print(d.hours)    # 1.5
print(d.minutes)  # 90.0

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

You can also construct a Duration directly from nanoseconds and convert it back to a string.

d = Duration(5_000_000_000)
print(d.seconds)      # 5.0
print(d.to_string())  # "5s"

Durations are useful for setting intervals, timeouts, and TTLs in your data.

from surrealdb import Surreal, Duration

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

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

See the Duration reference for all unit properties and methods.

Working with datetime values

A Datetime wraps an ISO 8601 datetime string for use with SurrealDB's datetime type. It preserves the original string representation through serialization and deserialization.

from surrealdb import Datetime

dt = Datetime("2025-06-01T09:00:00Z")
print(dt.dt)  # "2025-06-01T09:00:00Z"

Use Datetime when creating records that contain date or time fields.

from surrealdb import Surreal, Datetime

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

    db.create("events", {
        "title": "Launch",
        "scheduled_at": Datetime("2025-06-01T09:00:00Z"),
    })

See the Datetime reference for the full API.

Working with ranges

A Range represents a bounded interval with inclusive or exclusive endpoints. Each bound is wrapped in a BoundIncluded or BoundExcluded to specify whether the boundary value is part of the range.

from surrealdb import Range
from surrealdb.data.types.range import BoundIncluded, BoundExcluded

inclusive = Range(
    begin=BoundIncluded(1),
    end=BoundIncluded(10),
)

half_open = Range(
    begin=BoundIncluded(1),
    end=BoundExcluded(10),
)

Ranges are commonly used in query parameters to filter results within a specific interval.

from surrealdb import Surreal, Range
from surrealdb.data.types.range import BoundIncluded

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

    result = db.query(
        "SELECT * FROM events WHERE year IN $range",
        {"range": Range(BoundIncluded(2020), BoundIncluded(2025))},
    )

See the Range reference for the full API and bound types.

Working with geometry types

The SDK provides seven GeoJSON-compatible geometry types for working with SurrealDB's spatial data: GeometryPoint, GeometryLine, GeometryPolygon, GeometryMultiPoint, GeometryMultiLine, GeometryMultiPolygon, and GeometryCollection.

The most common type is GeometryPoint, which represents a single geographic coordinate.

from surrealdb import Surreal, GeometryPoint

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

    db.create("locations", {
        "name": "London",
        "coordinates": GeometryPoint(-0.1278, 51.5074),
    })

More complex types compose from simpler ones — a GeometryLine is built from a list of points, a GeometryPolygon from a list of lines, and so on. See the Geometry reference for constructors and examples of all seven types.

Learn more

• Data Types reference for complete API details

• RecordID reference for record identifier API

• Duration reference for duration API

• Python types for Value and RecordIdType definitions

• Data manipulation for using types in queries