Data Types

The Python SDK provides custom classes that map SurrealDB types to Python. These classes are used throughout the SDK for parameters and return values. Standard Python types like str, int, float, bool, None, bytes, dict, and list are also used directly where they map naturally to SurrealDB types.

Value Type

The Value union type represents any value that can be sent to or received from SurrealDB.

Value = (
    str | int | float | bool | None | bytes | UUID | Decimal
    | Table | Range | RecordID | Duration | Datetime
    | GeometryPoint | GeometryLine | GeometryPolygon
    | GeometryMultiPoint | GeometryMultiLine | GeometryMultiPolygon
    | GeometryCollection | dict[str, "Value"] | list["Value"]
)

Type Mapping

RecordIdType Type

Many SDK methods accept a RecordIdType, which allows passing a table name, a Table object, or a RecordID.

RecordIdType = str | Table | RecordID

Tokens Type

Authentication methods return a Tokens string alias.

Tokens = str

Custom Types

• RecordID — Record identifier with table name and ID components

• Table — Table name wrapper for type-safe references

• Datetime — Datetime wrapper for SurrealDB datetime values

• Duration — Duration with nanosecond precision and unit conversion

• Range — Range type with inclusive and exclusive bounds

• Geometry — GeoJSON-compatible geometry types for spatial data

See Also

• Surreal — Connection and query methods

• Errors — Error classes reference