Commit 02365b5

**Limitation.** TinyDB evaluates every query condition against the raw document _body_ mapping — the value in the `{doc_id: body}` table dict — never against a [`Document`](https://tinydb.readthedocs.io/en/latest/api.html#tinydb.table.Document) carrying `doc_id`. All five evaluation sites behave this way: `Table.search()`, `Table.get(cond=...)`, and the updater loops inside `Table.update(cond=...)`, `Table.update_multiple()`, and `Table.remove(cond=...)`. (`Table._update_table()`'s docstring notes that skipping the `Document` wrap is a deliberate optimization.) `Table.__iter__`, `search()`, `all()`, and `get()` all _return_ `Document` instances — but none of them evaluate the condition against one. Consequently, no query object — however it is constructed — can express "document id equals 1": the id is structurally invisible to the condition, even though it sits right there as the dict key in every evaluation loop.

**Why it matters to an ODM.** Every mainstream document ODM lets users query by the model's id attribute (Beanie and ODMantic translate `Model.id` to MongoDB's `_id`; Firestore special-cases `FieldPath.documentId()` because — exactly like TinyDB — its document key is not a body field). `tinydantic` maps its `id` field to `doc_id`, so supporting `User.get(User.id == 1)` required a translation layer: id-bearing conditions are detected in every model method and executed via `Table.update(doc_ids=…)`/`Table.remove(doc_ids=…)` operations or by iterating the table (the one API that hands the condition a `Document`). See `src/tinydantic/_query.py` and the id-condition branches in `src/tinydantic/_model.py`.

Existing queries and third-party `QueryLike` objects pay nothing (the `getattr` default preserves current behavior); id queries work in every API including `update_multiple()`; the storage format is untouched. This would let `tinydantic` delete its entire translation layer.

**Why it matters to an ODM.** `Table.update_multiple()` is TinyDB's only batched write — the whole batch runs in one atomic read-modify-write cycle (`Table._update_table()`), which is the reason to use it over looping `Table.update()`. `tinydantic` translates id conditions to `doc_ids=` operations where a public landing spot exists, but `Table.update_multiple()` offers none, so supporting id conditions in `tinydantic`'s own [`update_many()`][tinydantic.TinydanticModel.update_many] wrapper (without sacrificing the batch's single-write atomicity) required the private-API use recorded in the [registry below](#tinydb-private-api-usage-registry).

- Accept an optional per-pair id selector, e.g. `update_multiple(updates: Iterable[tuple[fields, cond | None, doc_ids | None]])` (or a parallel `update_multiple_by_ids()`), mirroring the `update()`/`remove()` signatures.

- Ship the `needs_doc_id`/`DocId` improvement above, which subsumes this: id conditions would then work in `update_multiple()`'s existing signature.

**Tracking issue:** [#144](https://github.com/tinydantic/tinydantic/issues/144)

**Limitation.** [`Query.matches()`](https://tinydb.readthedocs.io/en/latest/api.html#tinydb.queries.Query.matches) documents itself as "Run a regex test against a dict value (whole string has to match)" and implements the test with `re.match`, which anchors at the start of the value only. `matches(r".*@example\.com")` therefore matches `"[email protected]"`. `re.fullmatch` is the function the docstring describes; `Query.search()` (the deliberately unanchored spelling) uses `re.search`.

**Why it matters to an ODM.** The pattern users reach for is an allow-list — "this field must look like _this_" — and the docstring tells them it is one. It is not, and nothing about the result says so: the query returns rows, just more of them than intended. `tinydantic` presents these builders as its primary query API and had copied the upstream wording verbatim into `GuardedQuery.matches()` and the [Queries](../usage/queries.md) page, so the same wrong contract was published twice more.

There is no code workaround, and none is wanted: changing the behavior would silently narrow every existing caller's results. `tinydantic` carries the correction in prose instead — `GuardedQuery.matches()` (`src/tinydantic/_query.py`) and the Queries page both name the anchoring and point at `$`.

**Suggested improvement.** Correct the docstring — "the pattern is matched against the start of the value (`re.match`); end it with `$` to require a whole-value match" — and, optionally, add a `fullmatch=` flag or a `Query.fullmatch()` builder for the behavior the current wording promises. A behavior change to `re.fullmatch` is explicitly _not_ proposed.

| `Table._update_table(updater)` | `TinydanticModel._run_write_cycle()` — all `update()`/`update_by_ids()`/`update_all()`/`update_many()` writes (which validate each matched document's merged result unless `validate_writes=False`), plus the id-condition paths of `remove()` and `upsert()` | **In use** (approved 2026-07-13 for id-condition writes; scope extended 2026-08-02 to all validated update writes). Tracking: [#134](https://github.com/tinydantic/tinydantic/issues/134) | The only way to select write targets by id inside one atomic read-modify-write cycle, and the only way to validate-then-write atomically: `Table.update_multiple()` has no `doc_ids` parameter, conditions cannot see ids (the two limitations above), and a public two-pass validate-then-update has a read-modify-write race between passes. The custom updater evaluates every condition against `Document(body, doc_id)` wrappers inside upstream's own read → mutate → write → cache-clear lifecycle, validates merged bodies before the write, applies mutations copy-on-write (so an aborted or validation-failed cycle leaks nothing, even on `MemoryStorage`, whose `read()` shares body dicts by reference), and skips the storage write entirely when nothing matched. Benchmarked ~23% faster than the two-pass public-API alternative on a 5,000-document JSONStorage table (one full file read saved per write). | Either the `update_multiple()` improvement above plus an atomic validate-hook, or the `needs_doc_id`/`DocId` evaluator change combined with a public batched read-modify-write API. |