beaver-db 2.2.0__tar.gz → 2.4.0__tar.gz

beaver_db-2.4.0/AGENTS.md

@@ -0,0 +1,166 @@
+# AGENTS.md — beaver
+
+You're an AI agent picking up **beaver** (`beaver-db` on PyPI). This file is the door.
+
+## What it is
+
+A **local-first, embedded, multi-modal database for Python**, built on a single
+SQLite file. One file, many modalities: dicts, lists, queues, logs, documents
+(FTS + fuzzy), vectors (LSH), graphs, blobs, locks, channels and sketches — all
+in the same `.db`, all through one facade.
+
+It is a **public library** (`syalia-srl/beaver`, MIT) with real downstream users,
+not an internal utility. Its biggest consumer is AInBox (`repos/ainbox`), where
+warden, magpie, superbot, peacock, help and pipelines all persist through it.
+
+Read [`design.md`](design.md) first — the living design document, with the vision
+and the guiding principles. [`STATUS.md`](STATUS.md) is the running inventory of
+what is real versus missing in the v2 cycle.
+
+## The shape of the codebase
+
+    beaver/core.py          the engine: AsyncBeaverDB + the BeaverDB sync facade,
+                            _create_all_tables, _check_version, every factory method
+    beaver/interfaces.py    IBeaver* protocols — the surface the SID consumers target
+    beaver/api.py           @expose / @local_only — how a method reaches CLI + server + client
+    beaver/queries.py       the q() filter DSL: Query.__getattr__ builds dotted paths → Filter
+    beaver/<modality>.py    dicts, lists, queues, logs, docs, vectors, graphs, blobs,
+                            locks, channels, sketches — one module each
+    beaver/migrate.py       1.x → 2.x migration
+    beaver/cli/             the typer CLI (entry point `beaver`)
+    docs/                   Quarto site: guide-*.md (users), dev-*.md (contributors)
+    issues/                 numbered issue/spec files, synced with GitHub
+    tests/{unit,integration,concurrency}
+
+**Architecture in one paragraph.** `AsyncBeaverDB` is the async core (aiosqlite,
+one connection, WAL). `BeaverDB` is the *synchronous facade*: it spins a reactor
+thread running the async loop and bridges every call to it through
+`BeaverBridge` (the Portal pattern). "Synchronous facade, asynchronous engine" —
+so write the real logic in the async class, and the sync surface follows. See
+`docs/dev-architecture.md` and `docs/dev-concurrency.md`.
+
+## Conventions
+
+- **Every table is dunder-named** — `__beaver_logs__`, `__beaver_documents__`,
+  … (`core.py:63`). The single-prefix form (`beaver_logs`) is *1.x* and its
+  presence means a legacy file; see issue #41.
+- **The `.db` stays a valid, standard SQLite file.** Anyone must be able to open
+  it with `sqlite3`. That is a promise from `design.md`, not a preference.
+- **Schema changes are additive.** `_create_all_tables()` runs on *every*
+  `connect()` with `CREATE TABLE IF NOT EXISTS`, so a new table simply appears on
+  an existing database — no migration. Adding a side table is the house pattern
+  (see `__beaver_fts_index__`, `__beaver_trigrams__`, `__beaver_lsh_index__`).
+- **`BEAVER_DB_VERSION` (`core.py:42`) is at 1 and moving it is a breaking
+  change.** `_check_version` raises `BeaverIncompatibleSchemaError` when a file's
+  `user_version` exceeds what the running beaver understands (`core.py:372`), so
+  a bump means databases written by the new release **fail to open on the old
+  one**. Prefer a design that fits additively; bump only when you have decided to
+  break file compatibility on purpose.
+- **New capability on a manager? Decorate it.** `@expose(path=…, method=…,
+  cli_name=…, cli_help=…)` makes it reachable from the CLI, the REST server and
+  the remote client at once; `@local_only("reason")` marks what cannot cross the
+  wire (infinite streams, file-level operations). A method with neither is
+  local-only *by accident* rather than by decision.
+- **Minimal dependencies is a product constraint.** Core is `aiosqlite`, `numpy`,
+  `pydantic`, `rich`, `typer`. Heavy things go behind extras (`remote`,
+  `security`). In particular, **vector indexing stays pure-numpy** — no
+  `hnswlib`, no `faiss`, no compiled deps. The LSH strategy exists precisely so
+  scaling did not require one (issue #24); HNSW (#28) stays deferred until a
+  pure-numpy ANN beats LSH at >100k vectors.
+- **Silence is the bug.** The lesson of issue #41 — beaver opened a 1.x file,
+  reported everything empty, and wrote a parallel schema beside the untouched
+  data. Nothing errored; that was the problem. When state is partial, stale or
+  unmigrated, **say so loudly or degrade to the correct-but-slower path** — never
+  return a plausible subset.
+- Ships to `main`. English for code, docs, comments and commit messages.
+
+## Working here
+
+    make sync           uv sync --extra security --extra remote
+    uv run black .      format (see the warning below)
+    make format-check   black --check — test-unit depends on this
+    make type-check     mypy
+    make test-unit      pytest tests/unit --cov=beaver     ← the default target
+    make test-all       every suite, including concurrency
+    make ci             format-check + test-unit
+
+`pytest.ini` sets `asyncio_mode = auto` (no `@pytest.mark.asyncio` needed) and a
+**30 s timeout** — a test that hangs on a lock fails rather than wedging the run.
+Markers: `unit`, `integration`, `concurrency`.
+
+> ⚠️ **`make format` and `make bugfix` commit for you**, and they do it with
+> `git commit -am` / `git commit -a`, which sweeps up **every dirty file in the
+> tree** — including work from a concurrent session that has nothing to do with
+> yours. Use **`uv run black .`** and commit the paths you touched yourself.
+> `make format-check` is safe and is what `test-unit` actually gates on.
+
+**Releases:** `NEW_VERSION=x.y.z make release` — runs `test-all`, bumps the
+version in `pyproject.toml` *and* `beaver/__init__.py`, commits, tags, pushes and
+opens the GitHub release. Don't hand-edit those two version strings.
+
+The GitHub release is what actually ships it: `.github/workflows/release.yaml`
+fires on `release: created`, re-runs the suite, publishes to PyPI with
+`secrets.PYPI_TOKEN`, then pushes the image to GHCR. A tag alone publishes
+nothing.
+
+**Verify against an install, not against the tag — and not against the JSON API
+either.** Two things bite here, both observed releasing 2.3.0 on 2026-08-01:
+
+- `https://pypi.org/pypi/<pkg>/<ver>/json` returned **200** while `uv pip install`
+  still could not resolve the version. The JSON API and the simple index that
+  installers actually read propagate separately, so a 200 there is a proxy
+  signal, not proof the package is installable.
+- `uv` caches the index, and **`--refresh` does not clear it** — the install kept
+  failing with *"there is no version of beaver-db==2.3.0"* long after the simple
+  index listed both artifacts. `--no-cache` is what works.
+
+So the real check is a scratch venv that exercises the feature:
+
+```bash
+uv venv /tmp/verify && VIRTUAL_ENV=/tmp/verify uv pip install --no-cache "beaver-db==X.Y.Z"
+VIRTUAL_ENV=/tmp/verify uv run --no-project python -c "…exercise the new API…"
+```
+
+**Issues are files.** `issues/NN-slug.md` with `number / title / state / labels`
+frontmatter, round-tripped to GitHub by `make issues` (needs the `gh md-issues`
+extension). A substantial feature gets an issue file written *first* — see
+[`issues/24-…`](issues/) (LSH strategy) and
+[`issues/42-uniform-field-indexing-across-collections.md`](issues/42-uniform-field-indexing-across-collections.md)
+(field indexing) for the shape: Summary → the problem with real line references →
+Design → costs → delivery order → testing.
+
+## Gotchas paid for in advance
+
+- **FTS5 rejects punctuation in the query string** — tokenize before you hand a
+  user's words to `.search()` / `.fts()`. Measured on 2.2.0 against an indexed
+  document, three different `OperationalError`s:
+
+  | query | error |
+  |---|---|
+  | `thing` | — (1 hit) |
+  | `what's this?` | `fts5: syntax error near "'"` |
+  | `this?` | `fts5: syntax error near "?"` |
+  | `a-b` | `no such column: b` |
+
+  The hyphen case is the trap: FTS5 reads `a-b` as a **column filter**, so you
+  get a "no such column" error that says nothing about punctuation and sends you
+  hunting for a schema bug that isn't there.
+- **There is no reranking.** `docs` gives you FTS rank and trigram counts;
+  combining lexical and vector results is the caller's job (roll your own RRF).
+- **Embeddings are not part of `docs`.** A `docs()` collection and a `vectors()`
+  collection are separate things you keep in sync yourself; `docs` never embeds.
+- **`docs().where()` is a full scan today** — it compiles to `json_extract` per
+  row (`docs.py:472`), which is fast but not an index. Issue #42 is the fix.
+- **`__beaver_priority_queues__` has no declared PRIMARY KEY.** Its implicit
+  `rowid` is the only stable per-item identity. Any code assuming every table
+  declares a PK is wrong.
+- **`log()` resolves timestamp collisions by micro-incrementing and retrying**
+  (`logs.py:96`). Under many concurrent writers that loop can spin — use
+  `batched()`, which enforces monotonicity up front.
+
+## Where the planning lives
+
+Design docs and the v2 release plan live in Alex's workspace vault
+(`vault/Atlas/Architecture/2026-05-15-beaver-v2-release-plan.md`), not in this
+repo — this repo carries `design.md`, `STATUS.md` and `issues/`. If you need the
+wider roadmap and cannot see the vault, ask rather than guess.

{beaver_db-2.2.0 → beaver_db-2.4.0}/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to beaver-db will be recorded here.
 
+## 2.4.0 — 2026-08-10
+
+### Fixed — availability class
+
+- **A cancelled transaction no longer deadlocks every writer.** `Transaction.
+  __aenter__` had two windows in which it could leave `_tx_lock` held with
+  `__aexit__` never running, because the `async with` body was never entered:
+  cancellation between acquiring the lock and returning, and `BEGIN IMMEDIATE`
+  raising. Both left the lock held forever; the cancellation case *also* left
+  SQLite's write lock held, because cancelling the wait on
+  `connection.execute("BEGIN IMMEDIATE")` does not un-run the statement on
+  aiosqlite's worker thread.
+
+  In WAL mode this is nearly invisible: readers keep working while every
+  writer queues behind a lock with no owner. It took down authentication on an
+  AInBox appliance for hours on 2026-08-10 while the process kept serving its
+  login page and passing its healthcheck. Starlette/uvicorn cancel a request
+  task whenever a client disconnects, so the trigger is ordinary.
+
+  The enter path now cleans up after itself: a failed or cancelled `BEGIN` is
+  rolled back (shielded, so it survives the cancellation that caused it) and
+  the lock is released in a `finally`.
+
+- **Ownership is claimed only once the transaction has actually begun.**
+  `_tx_owner_task` was set *before* `BEGIN IMMEDIATE`, so a raising BEGIN left
+  it naming a transaction that never started — and the reentrancy check then
+  waved that task's next transaction through as a silent no-op, so a rolled
+  back block would persist.
+
+- **The reentrancy check no longer matches outside a task.**
+  `_tx_owner_task == current_task` was true when both were `None`, which
+  reads a caller with no running task as already owning the transaction.
+
+### Added
+
+- **`TransactionTimeoutError`** (exported from `beaver`, subclass of
+  `TimeoutError`). Waiting for the write lock is now bounded by
+  `connection_timeout` (default 30 s) instead of being unbounded. beaver
+  multiplexes every modality over a single connection, so contending tasks
+  queue on an in-process `asyncio.Lock` that SQLite's busy-timeout — which
+  only arbitrates between *separate* connections — never gets a say over.
+  An unbounded wait there is indistinguishable from a hang.
+
+- **`db.transaction(timeout=…)`** overrides that bound per call, for callers
+  with their own latency budget (a healthcheck, a request handler).
+
+- **An orphaned transaction is reclaimed, not waited on.** If the lock's owner
+  is a task that has already finished, the next writer rolls its transaction
+  back, logs a warning on the `beaver` logger and takes over. Recovery is
+  loud on purpose: it means something leaked.
+
 ## 2.2.0 — 2026-07-29
 
 ### Fixed — data-loss class (#41)

{beaver_db-2.2.0 → beaver_db-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beaver-db
-Version: 2.2.0
+Version: 2.4.0
 Summary: Fast, async-native, embedded, and multi-modal DB based on SQLite for AI-powered applications.
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License

{beaver_db-2.2.0 → beaver_db-2.4.0}/beaver/__init__.py

@@ -3,6 +3,7 @@ from .core import (
     AsyncBeaverDB,
     BeaverIncompatibleSchemaError,
     BeaverLegacySchemaError,
+    TransactionTimeoutError,
 )
 from .docs import Document
 from .events import Event
@@ -10,7 +11,7 @@ from .queries import q
 from .security import Secret
 from .errors import BeaverRemoteError, LocalOnlyError
 
-__version__ = "2.2.0"
+__version__ = "2.4.0"
 
 
 def connect(source: str, *, sync: bool = True, api_key: str | None = None):
@@ -39,6 +40,7 @@ __all__ = [
     "BeaverDB",
     "BeaverIncompatibleSchemaError",
     "BeaverLegacySchemaError",
+    "TransactionTimeoutError",
     "Document",
     "Secret",
     "Event",

{beaver_db-2.2.0 → beaver_db-2.4.0}/beaver/cli/discovery.py

@@ -171,7 +171,7 @@ def _build_command(method_name: str, meta: EndpointMeta, manager_accessor: Calla
             _run(ctx, manager_accessor, method_name, block=block, timeout=timeout)
 
     # --- shared no-arg shapes ---
-    elif method_name in ("count", "clear"):
+    elif method_name in ("count", "clear", "indexes"):
 
         def cmd(ctx: typer.Context):
             _run(ctx, manager_accessor, method_name)

{beaver_db-2.2.0 → beaver_db-2.4.0}/beaver/core.py

@@ -1,5 +1,6 @@
 import asyncio
 import json
+import logging
 import threading
 from typing import Any, Self, Type, AsyncContextManager
 
@@ -41,6 +42,8 @@ from .vectors import AsyncBeaverVectors
 
 BEAVER_DB_VERSION = 1
 
+_log = logging.getLogger("beaver")
+
 
 class BeaverIncompatibleSchemaError(RuntimeError):
     """Raised when opening a database whose schema is incompatible with this
@@ -82,6 +85,19 @@ LEGACY_1X_TABLES = frozenset(
 )
 
 
+class TransactionTimeoutError(TimeoutError):
+    """Raised when a transaction could not take the write lock in time.
+
+    beaver multiplexes every modality over a *single* connection, so tasks that
+    want to write queue on an in-process lock and SQLite's busy-timeout — which
+    only arbitrates between separate connections — never applies to them. The
+    bound is `connection_timeout` (or the per-call `timeout=` on
+    ``db.transaction()``).
+
+    Seeing this means a writer is holding the transaction open longer than the
+    budget: a long-running block, a stalled task, or a genuine write storm."""
+
+
 class Transaction:
     """
     A Reentrant Async Context Manager for database transactions.
@@ -91,29 +107,128 @@ class Transaction:
     at the outermost level.
     """
 
-    def __init__(self, db: "AsyncBeaverDB"):
+    def __init__(self, db: "AsyncBeaverDB", *, timeout: float | None = None):
         self.db = db
         self._is_root = False
+        self._timeout = db._timeout if timeout is None else timeout
 
     async def __aenter__(self):
         current_task = asyncio.current_task()
 
         # 1. Check Reentrancy: Do we already own the transaction?
-        if self.db._tx_owner_task == current_task:
+        #    `is not None` matters: outside a task `current_task()` is None,
+        #    and a bare `==` would read that as owning the transaction.
+        if current_task is not None and self.db._tx_owner_task is current_task:
             self._is_root = False
             return self
 
-        # 2. Acquire Lock (Wait for other tasks)
-        await self.db._tx_lock.acquire()
+        # 2. Acquire the write lock, bounded (see _acquire).
+        await self._acquire()
+
+        # 3. Start the DB transaction, THEN claim ownership.
+        #
+        #    Order matters. `__aexit__` never runs when `__aenter__` raises, so
+        #    everything between the acquire above and the return below has to
+        #    clean up after itself — and ownership must not name a transaction
+        #    that never began, or the reentrancy check above waves this task's
+        #    next transaction through as a no-op.
+        #
+        #    Using isolation_level=None globally means we MUST start manually.
+        try:
+            await self.db.connection.execute("BEGIN IMMEDIATE")
+        except BaseException:
+            try:
+                await self._rollback_quietly()
+            finally:
+                self.db._tx_lock.release()
+            raise
 
-        # 3. Mark ownership and start DB transaction
         self.db._tx_owner_task = current_task
         self._is_root = True
-
-        # Using isolation_level=None globally means we MUST start manually
-        await self.db.connection.execute("BEGIN IMMEDIATE")
         return self
 
+    async def _acquire(self) -> None:
+        """Take the write lock, waiting at most `self._timeout` seconds.
+
+        The wait has to be bounded because beaver multiplexes every modality
+        over a *single* connection: contending tasks queue here, on an
+        in-process `asyncio.Lock`, and SQLite's busy-timeout — which only
+        arbitrates between separate connections — never gets a say. An
+        unbounded wait here is indistinguishable from a hang, and in WAL mode
+        readers keep working throughout, so the process looks alive while every
+        writer is stuck behind it.
+        """
+        if await self._steal_if_orphaned():
+            return
+
+        try:
+            async with asyncio.timeout(self._timeout):
+                await self.db._tx_lock.acquire()
+        except TimeoutError:
+            # A holder that finished without releasing may have appeared while
+            # we waited; take it over rather than reporting contention.
+            if await self._steal_if_orphaned():
+                return
+            raise TransactionTimeoutError(
+                f"could not take the database write lock within "
+                f"{self._timeout:g}s — another task is holding a transaction "
+                f"open on {self.db._db_path!r}"
+            ) from None
+
+    async def _steal_if_orphaned(self) -> bool:
+        """Take over a lock whose owner has already finished.
+
+        A task that is `done()` cannot still be inside its `async with` body,
+        so nobody is coming back to commit or release: waiting out the timeout
+        would only delay an error. The rollback matters as much as the lock —
+        the orphan's `BEGIN IMMEDIATE` is what pins the file for every *other*
+        connection too, and SQLite refuses to begin a transaction inside one.
+
+        Returns True when this call now holds the lock. The lock object stays
+        `locked()` throughout; only ownership changes hands, so tasks already
+        queued on it keep waiting instead of racing us for it.
+
+        An owner of None means someone is mid-BEGIN and has not claimed the
+        lock yet — that is live, not orphaned. Nothing else can be `done()` and
+        still be running its transaction body, so there is no false positive
+        here that would roll back somebody's in-flight work.
+        """
+        owner = self.db._tx_owner_task
+        if owner is None or not owner.done() or not self.db._tx_lock.locked():
+            return False
+
+        # Loud, per beaver's rule about partial state: reclaiming is recovery
+        # from a bug somewhere, not a normal event, and a silent recovery is
+        # how the caller never learns it has a leak.
+        _log.warning(
+            "reclaiming an orphaned transaction on %r: its owning task (%s) "
+            "finished without committing or rolling back",
+            self.db._db_path,
+            owner.get_name(),
+        )
+        await self._rollback_quietly()
+        self.db._tx_owner_task = None
+        return True
+
+    async def _rollback_quietly(self) -> None:
+        """Undo a BEGIN that may have taken effect even though its await did not.
+
+        `await connection.execute("BEGIN IMMEDIATE")` is two things: the
+        statement running on aiosqlite's worker thread, and the future we wait
+        on. Cancelling the wait does not un-run the statement — so a cancelled
+        BEGIN can leave SQLite's write lock held with nothing left to release
+        it. That is the whole outage.
+
+        Shielded, because the rollback has to survive the very cancellation
+        that made it necessary. Errors are swallowed: this runs while another
+        exception is already propagating, and `rollback()` is a no-op when no
+        transaction turned out to be open.
+        """
+        try:
+            await asyncio.shield(self.db.connection.rollback())
+        except Exception:
+            pass
+
     async def __aexit__(self, exc_type, exc, tb):
         # Only the root transaction performs the Commit/Rollback and Release
         if not self._is_root:
@@ -152,6 +267,10 @@ class AsyncBeaverDB:
         pragma_mmap_size: int = 256 * 1024 * 1024,
     ):
         self._db_path = db_path
+        # Bounds both ways a write can be made to wait: SQLite's busy-timeout
+        # (contention from another *connection*) and the transaction lock below
+        # (contention from another *task* on this one). Only the second one
+        # applies in a single-process app, which is why it must be bounded too.
         self._timeout = connection_timeout
         self._cache_timeout = cache_timeout
 
@@ -256,12 +375,18 @@ class AsyncBeaverDB:
 
         return self._connection
 
-    def transaction(self) -> AsyncContextManager:
+    def transaction(self, *, timeout: float | None = None) -> AsyncContextManager:
         """
         Returns an async context manager for an atomic transaction.
         Use: async with db.transaction(): ...
+
+        `timeout` bounds the wait for the write lock, defaulting to this
+        database's `connection_timeout`. Pass a tighter one from a caller with
+        its own latency budget — a healthcheck, a request handler — so a
+        contended write fails fast with `TransactionTimeoutError` instead of
+        holding the caller for the full default.
         """
-        return Transaction(self)
+        return Transaction(self, timeout=timeout)
 
     async def _tables_named(self, names) -> list[str]:
         """Return which of `names` exist as tables in the open database."""
@@ -484,6 +609,41 @@ class AsyncBeaverDB:
             "CREATE INDEX IF NOT EXISTS idx_logs_timestamp ON __beaver_logs__ (log_name, timestamp)"
         )
 
+        # Field Index (issue #42) — uniform per-field indexing.
+        # Additive by design: new tables only, no ALTER, no version bump.
+        await c.execute(
+            """
+            CREATE TABLE IF NOT EXISTS __beaver_field_index__ (
+                kind      TEXT NOT NULL,
+                name      TEXT NOT NULL,
+                item_key  TEXT NOT NULL,
+                field     TEXT NOT NULL,
+                value     TEXT,
+                value_num REAL,
+                PRIMARY KEY (kind, name, item_key, field)
+            )
+        """
+        )
+        await c.execute(
+            "CREATE INDEX IF NOT EXISTS idx_field_lookup "
+            "ON __beaver_field_index__ (kind, name, field, value)"
+        )
+        await c.execute(
+            "CREATE INDEX IF NOT EXISTS idx_field_lookup_num "
+            "ON __beaver_field_index__ (kind, name, field, value_num)"
+        )
+        await c.execute(
+            """
+            CREATE TABLE IF NOT EXISTS __beaver_field_index_manifest__ (
+                kind     TEXT NOT NULL,
+                name     TEXT NOT NULL,
+                field    TEXT NOT NULL,
+                complete INTEGER NOT NULL DEFAULT 0,
+                PRIMARY KEY (kind, name, field)
+            )
+        """
+        )
+
         # Priority Queues
         await c.execute(
             """
@@ -685,9 +845,28 @@ class AsyncBeaverDB:
         return self.singleton(AsyncBeaverBlob, name, model=model)
 
     def log[T: BaseModel](
-        self, name: str, model: type[T] | None = None
+        self,
+        name: str,
+        model: type[T] | None = None,
+        # Quoted: inside a PEP 695 generic scope the class body is visible, so
+        # a bare `list[str]` resolves to AsyncBeaverDB.list, not the builtin.
+        indexed: "list[str] | None" = None,
     ) -> AsyncBeaverLog[T]:
-        return self.singleton(AsyncBeaverLog, name, model=model)
+        """Open a log.
+
+        `indexed` declares the fields whose values are maintained in the field
+        index. **Declare on first use:** `singleton()` keys its cache on
+        `(cls, name)` only, so after a bare `db.log("audit")` a later
+        `db.log("audit", indexed=[...])` returns the already-cached, undeclared
+        manager and the declaration is silently dropped.
+        """
+        return self.singleton(AsyncBeaverLog, name, model=model, indexed=indexed)
+
+    async def indexes(self) -> dict:
+        """Every declared field index in this database, by (kind, name)."""
+        from . import indexing
+
+        return await indexing.all_field_indexes(self.connection)
 
     def lock(
         self, name: str, timeout=None, lock_ttl=60.0, poll_interval=0.1

{beaver_db-2.2.0 → beaver_db-2.4.0}/beaver/docs.py

@@ -11,6 +11,7 @@ from typing import (
 
 from pydantic import BaseModel
 
+from . import indexing
 from .queries import Filter
 from .manager import AsyncBeaverBase, atomic, emits
 from .interfaces import Document, ScoredDocument, IDocumentQuery
@@ -468,11 +469,11 @@ class AsyncBeaverDocuments[T: BaseModel](AsyncBeaverBase[T]):
                 params.extend(q._search_fields)
 
         if q._filters:
-            for filter in q._filters:
-                where.append(
-                    f"json_extract(d.data, '$.{filter.path}') {filter.operator} ?"
-                )
-                params.append(filter.value)
+            clauses, filter_params = indexing.compile_scan_filters(
+                "data", q._filters, alias="d"
+            )
+            where.extend(clauses)
+            params.extend(filter_params)
 
         parts.append("WHERE " + " AND ".join(where))
 

{beaver_db-2.2.0 → beaver_db-2.4.0}/beaver/errors.py

@@ -3,7 +3,11 @@
 import pydantic
 from pydantic import BaseModel
 
-from .core import BeaverIncompatibleSchemaError, BeaverLegacySchemaError
+from .core import (
+    BeaverIncompatibleSchemaError,
+    BeaverLegacySchemaError,
+    TransactionTimeoutError,
+)
 
 
 class BeaverRemoteError(Exception):
@@ -26,6 +30,7 @@ _REGISTRY: dict[str, type[Exception]] = {
     "TimeoutError": TimeoutError,
     "BeaverIncompatibleSchemaError": BeaverIncompatibleSchemaError,
     "BeaverLegacySchemaError": BeaverLegacySchemaError,
+    "TransactionTimeoutError": TransactionTimeoutError,
     "ValidationError": pydantic.ValidationError,
 }