SurrealDB Python SDK

All SDK errors derive from SurrealError. Errors are categorized into two main branches based on whether the request reached the server and whether the server rejected it:

• ServerError: The server received and processed the request but rejected it (e.g., syntax errors, permission issues). These are generally not retryable without changes. ServerError includes specific subclasses like NotFoundError that mirror SurrealDB's structured error format, allowing you to match on kind and details.
• TransportError: The request failed to produce a structured response (e.g., network failure, timeout). These may be retryable.

Common TransportError subclasses include:

• ConnectionUnavailableError: Host unreachable or socket closed.
• TransportTimeoutError: Request timed out.
• HttpStatusError: A non-2xx HTTP response (contains .status, .body, and .url).

Invalid Python inputs (like wrong types) will raise standard ValueError or TypeError before reaching the server.

from surrealdb import Surreal
from surrealdb.errors import NotFoundError, ServerError, SurrealError, TransportError

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

    try:
        db.query("SELECT * FROM nonexistent:1").execute()
    except NotFoundError as error:
        print(error.kind, error.table_name)   # NotFound nonexistent
    except ServerError as error:
        print(error.kind, error.details)
    except TransportError as error:
        print("could not reach the server:", error)

SurrealDB's set<T> is a deduplicated sequence. In Python, these are returned as SurrealSet objects.

Characteristics

• Type: SurrealSet is a subclass of list. It supports indexing and comparison like a list.
• Compatibility: Unlike a standard Python set, a SurrealSet can hold non-hashable members like dict or list (e.g., set<object>).
• Round-tripping: Writing a SurrealSet back to the database preserves the set type. Writing a plain Python set also works and is sent as a set.
• Normalization: SurrealDB normalizes sets, so the order of elements in a SurrealSet may differ from the input order.

Note: SurrealSet support requires SurrealDB 3.x. SurrealDB 2.x does not have a CBOR set representation.

# SurrealSet behaves like a list
row = db.select(rec)                   # {"tags": SurrealSet(['a', 'b'])}
row["name"] = "new name"
db.update(rec, row)              # tags is still a set

# Comparison with list works
db.select(rec)["tags"] == ["a", "b"]   # True

SurrealDB can store files in a bucket (in-memory, on disk, or via object storage like S3).

Key Concepts:

• A File is a reference consisting of a bucket name and a key. It is not a Python file object and holds no bytes itself.
• Experimental Feature: To use buckets, the server must be started with SURREAL_CAPS_ALLOW_EXPERIMENTAL=files and a bucket must be defined (e.g., DEFINE BUCKET images BACKEND "memory";).
• Non-Transactional Writes: File writes (db.files.put) are not transactional. They write directly to the bucket backend. This means a file write is visible to other connections immediately and will survive a txn.cancel(), even if a record write in the same transaction is rolled back.
• Key Normalization: Keys are normalized to start with /. File("b", "a.txt") and File("b", "/a.txt") refer to the same file.
• Data Types: put accepts bytes, bytearray, or memoryview. get returns bytes. You must manually encode strings (e.g., .encode("utf-8")) before putting them, as the server stores raw bytes.

from surrealdb import File, Surreal

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

    avatar = File("images", "/photos/avatar.png")

    with open("avatar.png", "rb") as handle:
        db.files.put(avatar, handle.read())

    png_bytes = db.files.get(avatar)         # -> bytes, or None if absent
    meta = db.files.head(avatar)             # -> FileMetadata | None

Client-side transactions and multi-session support are available only for WebSocket connections (ws:// or wss://). They are not supported for HTTP or embedded connections.

To use them, you must:

1. Create a session using await db.new_session().
2. Use the session object to perform operations.
3. Start a transaction on the session using await session.begin_transaction().
4. Commit the transaction with await txn.commit() or roll it back with await txn.cancel().

Both AsyncSurrealSession/BlockingSurrealSession and AsyncSurrealTransaction/BlockingSurrealTransaction provide the same CRUD builder, query(), run(), query_raw(), info(), and version() APIs. Operations are scoped to the session or transaction instance, so you do not need to pass session or transaction IDs manually.

async with AsyncSurreal("ws://localhost:8000/rpc") as db:
    await db.signin({"username": "root", "password": "root"})
    await db.use("ns", "db")

    # Create a session
    session = await db.new_session()
    await session.use("ns", "db")

    # Start a transaction on the session
    txn = await session.begin_transaction()
    await txn.create(RecordID("account", "alice"), {"balance": 100})
    await txn.update(RecordID("account", "bob")).merge({"balance": 50})

    # Commit (or call `await txn.cancel()` to roll back)
    await txn.commit()

    await session.close_session()

Choosing between an embedded database and a remote database depends on your architecture and persistence requirements.

Use Embedded Database

Use connection strings like memory, mem://, file://, surrealkv://, or surrealkv+versioned:// when:

• Desktop Applications: No server setup required.
• Testing: In-memory databases are extremely fast for unit tests.
• Local Development: Quick prototyping without managing infrastructure.
• Edge Computing: Running on devices without network access.
• Single-App Storage: When the data is specific to one application.

Use Remote Database

Use connection strings like ws:// or http:// when:

• Multi-App Architecture: Multiple applications need to share the same data.
• Distributed Systems: Microservices or distributed architectures.
• Cloud Deployments: Scalable cloud infrastructure.
• Horizontal Scaling: When you need to scale across multiple instances.
• Team Collaboration: Centralized data for multiple developers.