Python Types
The SDK provides type definitions and dataclasses for type-safe development. This page documents the key types used throughout the SDK.
Source: types.py, models.py, url.py
Value Types
Value
Union type representing all possible values that can be sent to or returned 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"]
)
This type is recursive: dictionaries and lists can contain nested Value types. See the Data Types overview for details on each SurrealDB-specific type.
RecordIdType
Type alias for values accepted as record or table references by CRUD methods.
RecordIdType = str | Table | RecordID
When a str is passed, it is treated as a table name. Pass a RecordID for specific record targeting, or a Table for explicit table references.
Authentication Types
Tokens
Frozen dataclass returned by .signin() and .signup(). Contains the access token and an optional refresh token.
@dataclass(frozen=True)
class Tokens:
access: str | None = None
refresh: str | None = None
Properties:
| Property | Type | Description |
|---|
access | str | None | The JWT access token |
refresh | str | None | The refresh token, if the access method was defined with WITH REFRESH |
Example:
from surrealdb import Surreal
db = Surreal("ws://localhost:8000")
db.connect()
db.use("test", "test")
tokens = db.signin({"username": "root", "password": "root"})
print(tokens.access)
print(tokens.refresh)
Data Model Types
Patch
Dataclass representing a JSON Patch operation per the JSON Patch specification.
@dataclass
class Patch:
op: str
path: str
value: Any
Properties:
| Property | Type | Description |
|---|
op | str | The patch operation: "add", "remove", "replace", "move", "copy", or "test" |
path | str | The JSON pointer path |
value | Any | The value for the operation |
QueryResponse
Frozen dataclass representing an HTTP query response.
@dataclass(frozen=True)
class QueryResponse:
time: str
status: str
result: list[dict[str, Any]]
Properties:
| Property | Type | Description |
|---|
time | str | The time the request was processed |
status | str | The status of the request |
result | list[dict[str, Any]] | The query results |
Connection Types
UrlScheme
Enum of supported connection URL schemes. The SDK uses this internally to select the appropriate connection class.
class UrlScheme(Enum):
HTTP = "http"
HTTPS = "https"
WS = "ws"
WSS = "wss"
MEM = "mem"
FILE = "file"
MEMORY = "memory"
SURREALKV = "surrealkv"
| Scheme | Connection type | Description |
|---|
HTTP, HTTPS | HTTP | Short-lived stateless connections |
WS, WSS | WebSocket | Long-lived stateful connections with full feature support |
MEM, MEMORY | Embedded | In-memory database |
FILE | Embedded | File-based persistent database |
SURREALKV | Embedded | SurrealKV persistent database |
See Also
