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.
Type Definition
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
| Python Type | SurrealDB Type | Notes |
|---|
str | string | |
int | int | |
float | float | |
bool | bool | |
None | NONE / NULL | |
bytes | bytes | |
UUID | uuid | From uuid standard library |
Decimal | decimal | From decimal standard library |
dict | object | Keys must be strings |
list | array | |
RecordID | record | Table name + identifier |
Table | table reference | Table name wrapper |
Duration | duration | Nanosecond precision |
Datetime | datetime | ISO 8601 string |
Range | range | Inclusive/exclusive bounds |
Geometry* | geometry | GeoJSON-compatible types |
RecordIdType Type
Many SDK methods accept a RecordIdType, which allows passing a table name, a Table object, or a RecordID.
Type Definition
RecordIdType = str | Table | RecordID
Tokens Type
Authentication methods return a Tokens string alias.
Type Definition
Tokens = str
Custom Types
RecordID — Record identifier with table name and ID componentsTable — Table name wrapper for type-safe referencesDatetime — Datetime wrapper for SurrealDB datetime valuesDuration — Duration with nanosecond precision and unit conversionRange — Range type with inclusive and exclusive boundsGeometry — GeoJSON-compatible geometry types for spatial data
See Also
- Surreal — Connection and query methods
- Errors — Error classes reference
