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:

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:

QueryResponse

Frozen dataclass representing an HTTP query response.

@dataclass(frozen=True)
class QueryResponse:
    time: str
    status: str
    result: list[dict[str, Any]]

Properties:

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"

See Also

• Data Types for the SurrealDB-specific type classes

• Errors for error classes and constants

• Surreal API reference for methods using these types