surreal-orm-lite 0.35.2__tar.gz → 0.35.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/CHANGELOG.md +43 -0
  2. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/PKG-INFO +19 -10
  3. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/README.md +18 -9
  4. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/cache.py +16 -1
  7. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/model_auth.py +1 -1
  8. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/model_base.py +34 -15
  9. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/search.py +13 -0
  10. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/transaction.py +26 -0
  11. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/.gitignore +0 -0
  12. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/LICENSE +0 -0
  13. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/Makefile +0 -0
  14. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/_sdk.py +0 -0
  15. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/aggregations.py +0 -0
  16. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/auth.py +0 -0
  17. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/changefeed.py +0 -0
  18. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/concurrency.py +0 -0
  19. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/connection_config.py +0 -0
  20. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/connection_manager.py +0 -0
  21. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/constants.py +0 -0
  22. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/decoding.py +0 -0
  23. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/define_parser.py +0 -0
  24. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/edge.py +0 -0
  25. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/embedded.py +0 -0
  26. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/encoding.py +0 -0
  27. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/enum.py +0 -0
  28. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/exceptions.py +0 -0
  29. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/functions.py +0 -0
  30. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/geo.py +0 -0
  31. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/introspection.py +0 -0
  32. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/live.py +0 -0
  33. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/model_ddl.py +0 -0
  34. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/model_generator.py +0 -0
  35. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/py.typed +0 -0
  36. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/q.py +0 -0
  37. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/query_set.py +0 -0
  38. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/routing.py +0 -0
  39. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/schema.py +0 -0
  40. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/schema_state.py +0 -0
  41. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/signals.py +0 -0
  42. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/subquery.py +0 -0
  43. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/surql_literal.py +0 -0
  44. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/testing/__init__.py +0 -0
  45. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/testing/database.py +0 -0
  46. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  47. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/time_travel.py +0 -0
  48. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/types.py +0 -0
  49. {surreal_orm_lite-0.35.2 → surreal_orm_lite-0.35.3}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,49 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.35.3] - 2026-10-23
9
+
10
+ Follow-ups to the review of v0.35.0's full-text search (#304): the warning of `define_indexes()`
11
+ names every index it rebuilds, and `define_indexes(tx=…)` refuses to define an index in a
12
+ transaction that has already written records to the model's table, which SurrealDB servers would
13
+ leave out of the index. No new public API.
14
+
15
+ ### Changed
16
+
17
+ - **`define_indexes(tx=…)` raises `SurrealDbError` after an ORM write to the model's table**
18
+ (#304). SurrealDB servers do not index the records a transaction wrote before the index was
19
+ defined: they stay out of it after the commit, and a search misses them. When an index must be
20
+ defined or redefined and the block has already written records to the model's table with the
21
+ ORM (`save()`, `objects(tx=…).bulk_create()`, …), `define_indexes(tx=…)` now raises before any
22
+ DDL, naming the model and the table; the refusal does not fail the transaction. Definitions
23
+ (`define_table(tx=…)`, `define_relation(tx=…)`, `remove_index(tx=…)`, …), a write to another
24
+ table and a call with nothing to apply do not count; a raw `tx.add()` is not tracked. Call
25
+ `define_indexes()` without `tx=` first, then write in the transaction. Earlier releases accepted
26
+ the call and the records written before it were missing from the index on SurrealDB 2.x and 3.x.
27
+
28
+ ### Fixed
29
+
30
+ - **The analyzer warning of `define_indexes()` names the indexes the call redefines** (#304).
31
+ When one call redefined an analyzer and an index that uses it, the warning counted only the
32
+ indexes rebuilt with `REBUILD INDEX` (`Analyzer 'plain' redefined; 0 index(es) rebuilt:`,
33
+ naming none), although `DEFINE INDEX OVERWRITE` rebuilds the redefined index too. It now names
34
+ every index the call rebuilds, in the order applied.
35
+
36
+ ### Notes
37
+
38
+ - **Reported upstream**: a SurrealDB 3.x server leaving out of an index the records the same
39
+ transaction wrote before `DEFINE INDEX` is a server defect,
40
+ [surrealdb/surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618); 2.x behaves the
41
+ same, and the embedded engine indexes those records. README section 36 (Transactions), a row of
42
+ the "ORM behaviour: SurrealDB 2.x vs 3.x" table and one of the embedded engine's table describe
43
+ each engine's outcome, which tests pin.
44
+ - **A write after `define_indexes(tx=…)` on SurrealDB 2.x**: in the same block, a write to a table
45
+ that held records fails the commit with a retryable `SurrealDbConflictError` that a retry meets
46
+ again, a 2.x limitation; SurrealDB 3.x and the embedded engine commit and index it. Prefer
47
+ `define_indexes()` outside the block.
48
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
49
+ plus 3.1.5 for backward compatibility.
50
+
8
51
  ## [0.35.2] - 2026-10-22
9
52
 
10
53
  An auth model whose signup field is declared `Field(exclude=True)` is refused whatever its schema
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.35.2
3
+ Version: 0.35.3
4
4
  Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
5
5
  Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
6
6
  Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -6034,11 +6034,12 @@ SurrealDB keeps the tokens of the records an index holds when their analyzer cha
6034
6034
  misses them — the records written afterwards use the new analyzer — until the index is rebuilt. So when
6035
6035
  `define_indexes()`, or `SurrealDBConnectionManager.define_analyzer()`, redefines an analyzer, it rebuilds every index of
6036
6036
  the database that uses it (`REBUILD INDEX`, sorted by table then index; `define_indexes()` rebuilds the model's table's
6037
- last), and logs one warning naming them (logger `surreal_orm_lite.search`). A rebuild re-reads the table: seconds
6038
- per thousands of records on SurrealDB 2.x and the embedded engine. An analyzer belongs to the database, not to a table:
6039
- declare one `Analyzer` per name (a module constant) and reference it from every index that uses it — two definitions
6040
- under one name would redefine it in turn, each time rebuilding its indexes. An unchanged index is never redefined, so
6041
- start-up never rebuilds (and, on SurrealDB 2.x, never inflates its scores).
6037
+ last), and logs one warning naming them, an index it redefines at the same time included (logger
6038
+ `surreal_orm_lite.search`). A rebuild re-reads the table: seconds per thousands of records on SurrealDB 2.x and the
6039
+ embedded engine. An analyzer belongs to the database, not to a table: declare one `Analyzer` per name (a module
6040
+ constant) and reference it from every index that uses it — two definitions under one name would redefine it in turn,
6041
+ each time rebuilding its indexes. An unchanged index is never redefined, so start-up never rebuilds (and, on SurrealDB
6042
+ 2.x, never inflates its scores).
6042
6043
 
6043
6044
  ```python
6044
6045
  PLAIN = Analyzer("plain", ["blank"], ["ascii"])
@@ -6082,9 +6083,15 @@ print(await NoteV2.objects().search(text="physics").count())
6082
6083
  So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL when an analyzer must be defined or redefined, and
6083
6084
  `define_analyzer(tx=…)` when a redefinition has indexes to rebuild (a new analyzer, or a redefinition no index uses,
6084
6085
  joins the transaction): call `define_analyzer()` without `tx=` first.
6085
- - Prefer `define_indexes()` outside the block: in a transaction that also writes to the model's table, SurrealDB may
6086
- leave out of the index a record the block wrote before the index was defined, and may fail the block on a write
6087
- after it.
6086
+ - The block must not have written to the model's table yet: SurrealDB servers do not index the records a transaction
6087
+ wrote before the index was defined, which stay out of it after the commit. It is a server defect
6088
+ ([surrealdb/surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618) on 3.x, the same on 2.x); only the
6089
+ embedded engine indexes them. So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL, naming the model and
6090
+ the table, when an index must be defined or redefined and the block has already written records to the model's table
6091
+ with the ORM (`save()`, `objects(tx=…).bulk_create()`, …). The refusal does not fail the block. `define_table(tx=…)`,
6092
+ `define_relation(tx=…)` and a write to another table do not count; a raw `tx.add()` is not tracked.
6093
+ - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6094
+ in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again.
6088
6095
  - `remove_analyzer(tx=…)` reads committed state to find the indexes that use the analyzer: an index queued earlier in
6089
6096
  a buffered block is not seen.
6090
6097
  - A search in an interactive transaction sees the transaction's writes; in a buffered one, a read raises, as every
@@ -6267,7 +6274,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6267
6274
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6268
6275
  on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
6269
6276
  otherwise. The full suite and every divergence below were re-verified on both new versions.
6270
- Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5.
6277
+ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
6271
6278
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6272
6279
 
6273
6280
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6418,6 +6425,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6418
6425
  | `search()` on a field without a full-text index | `SurrealDbError` naming the field | the same; 3.1 answers no record | v0.35.0 |
6419
6426
  | `live()` with a `Subquery` that searches a field without a full-text index | `SurrealDbError` naming the field, before the live query starts | the same (the live query would never notify); 3.1 starts it | v0.35.0 |
6420
6427
  | An auth model with a `Field(exclude=True)` field SIGNUP writes (`password: str = Field(exclude=True)`) | `TypeError` before any request, whatever the schema mode and `with_table`: the four DDL methods, `signup()` and `signin()` | same on both lines (a check of the model, no request) | v0.35.2 |
6428
+ | `define_indexes(tx=)` in a block that writes to the model's table (an ORM write before the index, a write after it) | a write before it: refused (left out of the index); a write after it, to a table holding records, fails the commit with a retryable `SurrealDbConflictError`, again on retry | a write before it: refused (left out of the index, [surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618)); a write after it is committed and indexed | v0.35.3 |
6421
6429
  | Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0 | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips) | 3.3.0 identical to 3.2.4, except the system-user signin row | v0.19.1 |
6422
6430
 
6423
6431
  > **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
@@ -6455,6 +6463,7 @@ Capabilities not listed behave as on a 2.x server.
6455
6463
  | TYPE RELATION constraints (v0.33.0) | as on a 2.x server: a raw `ALTER TABLE … TYPE` of a table already written to is not enforced (`define_relation()` sends `DEFINE TABLE OVERWRITE`); an endpoint outside `IN`/`OUT` whose record does not exist raises `SurrealDbNotFoundError` | `SurrealDbError` for that endpoint on 3.x | v0.33.0 |
6456
6464
  | Model table DDL (v0.34.0) | as on a 2.x server: `define_table()` adds `FLEXIBLE` to the `Any` and untyped columns of a `SCHEMAFULL` table and to its lists of sub-models holding a `FLEXIBLE` column; a write naming a field the table does not define drops that field, except in the items of a list `define_table()` writes `FLEXIBLE`, which keep it | 3.x keeps those values without `FLEXIBLE` and refuses that write, except in list items that define a field | v0.34.0 |
6457
6465
  | Full-text search (v0.35.0) | as on a 2.x server: `SEARCH ANALYZER`, a term in more than half the documents scores below zero, BM25 statistics grow with each rebuild and keep deleted records, `remove_analyzer()` refuses an analyzer an index uses; an index defined in the transaction that defines its analyzer sees it, which `define_indexes(tx=…)` refuses all the same | 3.x writes `FULLTEXT ANALYZER`, scores such a term `0.0`, keeps BM25 statistics exact and refuses that removal | v0.35.0 |
6466
+ | `define_indexes(tx=)` in a block that writes to the model's table | an ORM write before it: refused all the same, although this engine indexes its records; a write after it is committed and indexed | refused (left out of the index); on 2.x a write after it, to a table holding records, fails the commit | v0.35.3 |
6458
6467
  | Everything else | CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields, upsert/patch, server values, computed fields, stored functions, signals: the same as on a 2.x server | unchanged | v0.25.0 |
6459
6468
 
6460
6469
  ---
@@ -5983,11 +5983,12 @@ SurrealDB keeps the tokens of the records an index holds when their analyzer cha
5983
5983
  misses them — the records written afterwards use the new analyzer — until the index is rebuilt. So when
5984
5984
  `define_indexes()`, or `SurrealDBConnectionManager.define_analyzer()`, redefines an analyzer, it rebuilds every index of
5985
5985
  the database that uses it (`REBUILD INDEX`, sorted by table then index; `define_indexes()` rebuilds the model's table's
5986
- last), and logs one warning naming them (logger `surreal_orm_lite.search`). A rebuild re-reads the table: seconds
5987
- per thousands of records on SurrealDB 2.x and the embedded engine. An analyzer belongs to the database, not to a table:
5988
- declare one `Analyzer` per name (a module constant) and reference it from every index that uses it — two definitions
5989
- under one name would redefine it in turn, each time rebuilding its indexes. An unchanged index is never redefined, so
5990
- start-up never rebuilds (and, on SurrealDB 2.x, never inflates its scores).
5986
+ last), and logs one warning naming them, an index it redefines at the same time included (logger
5987
+ `surreal_orm_lite.search`). A rebuild re-reads the table: seconds per thousands of records on SurrealDB 2.x and the
5988
+ embedded engine. An analyzer belongs to the database, not to a table: declare one `Analyzer` per name (a module
5989
+ constant) and reference it from every index that uses it — two definitions under one name would redefine it in turn,
5990
+ each time rebuilding its indexes. An unchanged index is never redefined, so start-up never rebuilds (and, on SurrealDB
5991
+ 2.x, never inflates its scores).
5991
5992
 
5992
5993
  ```python
5993
5994
  PLAIN = Analyzer("plain", ["blank"], ["ascii"])
@@ -6031,9 +6032,15 @@ print(await NoteV2.objects().search(text="physics").count())
6031
6032
  So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL when an analyzer must be defined or redefined, and
6032
6033
  `define_analyzer(tx=…)` when a redefinition has indexes to rebuild (a new analyzer, or a redefinition no index uses,
6033
6034
  joins the transaction): call `define_analyzer()` without `tx=` first.
6034
- - Prefer `define_indexes()` outside the block: in a transaction that also writes to the model's table, SurrealDB may
6035
- leave out of the index a record the block wrote before the index was defined, and may fail the block on a write
6036
- after it.
6035
+ - The block must not have written to the model's table yet: SurrealDB servers do not index the records a transaction
6036
+ wrote before the index was defined, which stay out of it after the commit. It is a server defect
6037
+ ([surrealdb/surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618) on 3.x, the same on 2.x); only the
6038
+ embedded engine indexes them. So `define_indexes(tx=…)` raises `SurrealDbError` before any DDL, naming the model and
6039
+ the table, when an index must be defined or redefined and the block has already written records to the model's table
6040
+ with the ORM (`save()`, `objects(tx=…).bulk_create()`, …). The refusal does not fail the block. `define_table(tx=…)`,
6041
+ `define_relation(tx=…)` and a write to another table do not count; a raw `tx.add()` is not tracked.
6042
+ - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6043
+ in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again.
6037
6044
  - `remove_analyzer(tx=…)` reads committed state to find the indexes that use the analyzer: an index queued earlier in
6038
6045
  a buffered block is not seen.
6039
6046
  - A search in an interactive transaction sees the transaction's writes; in a buffered one, a read raises, as every
@@ -6216,7 +6223,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6216
6223
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6217
6224
  on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
6218
6225
  otherwise. The full suite and every divergence below were re-verified on both new versions.
6219
- Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5.
6226
+ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
6220
6227
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6221
6228
 
6222
6229
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6367,6 +6374,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6367
6374
  | `search()` on a field without a full-text index | `SurrealDbError` naming the field | the same; 3.1 answers no record | v0.35.0 |
6368
6375
  | `live()` with a `Subquery` that searches a field without a full-text index | `SurrealDbError` naming the field, before the live query starts | the same (the live query would never notify); 3.1 starts it | v0.35.0 |
6369
6376
  | An auth model with a `Field(exclude=True)` field SIGNUP writes (`password: str = Field(exclude=True)`) | `TypeError` before any request, whatever the schema mode and `with_table`: the four DDL methods, `signup()` and `signin()` | same on both lines (a check of the model, no request) | v0.35.2 |
6377
+ | `define_indexes(tx=)` in a block that writes to the model's table (an ORM write before the index, a write after it) | a write before it: refused (left out of the index); a write after it, to a table holding records, fails the commit with a retryable `SurrealDbConflictError`, again on retry | a write before it: refused (left out of the index, [surrealdb#7618](https://github.com/surrealdb/surrealdb/issues/7618)); a write after it is committed and indexed | v0.35.3 |
6370
6378
  | Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0 | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips) | 3.3.0 identical to 3.2.4, except the system-user signin row | v0.19.1 |
6371
6379
 
6372
6380
  > **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
@@ -6404,6 +6412,7 @@ Capabilities not listed behave as on a 2.x server.
6404
6412
  | TYPE RELATION constraints (v0.33.0) | as on a 2.x server: a raw `ALTER TABLE … TYPE` of a table already written to is not enforced (`define_relation()` sends `DEFINE TABLE OVERWRITE`); an endpoint outside `IN`/`OUT` whose record does not exist raises `SurrealDbNotFoundError` | `SurrealDbError` for that endpoint on 3.x | v0.33.0 |
6405
6413
  | Model table DDL (v0.34.0) | as on a 2.x server: `define_table()` adds `FLEXIBLE` to the `Any` and untyped columns of a `SCHEMAFULL` table and to its lists of sub-models holding a `FLEXIBLE` column; a write naming a field the table does not define drops that field, except in the items of a list `define_table()` writes `FLEXIBLE`, which keep it | 3.x keeps those values without `FLEXIBLE` and refuses that write, except in list items that define a field | v0.34.0 |
6406
6414
  | Full-text search (v0.35.0) | as on a 2.x server: `SEARCH ANALYZER`, a term in more than half the documents scores below zero, BM25 statistics grow with each rebuild and keep deleted records, `remove_analyzer()` refuses an analyzer an index uses; an index defined in the transaction that defines its analyzer sees it, which `define_indexes(tx=…)` refuses all the same | 3.x writes `FULLTEXT ANALYZER`, scores such a term `0.0`, keeps BM25 statistics exact and refuses that removal | v0.35.0 |
6415
+ | `define_indexes(tx=)` in a block that writes to the model's table | an ORM write before it: refused all the same, although this engine indexes its records; a write after it is committed and indexed | refused (left out of the index); on 2.x a write after it, to a table holding records, fails the commit | v0.35.3 |
6407
6416
  | Everything else | CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields, upsert/patch, server values, computed fields, stored functions, signals: the same as on a 2.x server | unchanged | v0.25.0 |
6408
6417
 
6409
6418
  ---
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.35.2"
3
+ version = "0.35.3"
4
4
  description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,4 +1,4 @@
1
- __version__ = "0.35.2"
1
+ __version__ = "0.35.3"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -783,7 +783,14 @@ def _resolve(
783
783
  return None, tx
784
784
 
785
785
 
786
- def invalidates(of: _Of, *, deletes: bool = False) -> Callable[[F], F]:
786
+ def _note_records(tables: frozenset[str] | None, tx: Any) -> None:
787
+ """Note *tables* (``None``: every table) as written with records on *tx* (issue #304), when its class has
788
+ ``_note_record_write`` — recognised by its class, as :func:`writing` recognises a transaction."""
789
+ if callable(getattr(type(tx), "_note_record_write", None)):
790
+ tx._note_record_write(tables)
791
+
792
+
793
+ def invalidates(of: _Of, *, deletes: bool = False, records: bool = True) -> Callable[[F], F]:
787
794
  """Decorate an ORM write method so that it invalidates the cached reads it can change.
788
795
 
789
796
  ``of`` says which tables the call writes, from its first argument: ``"self"`` (the instance's model table),
@@ -794,6 +801,11 @@ def invalidates(of: _Of, *, deletes: bool = False) -> Callable[[F], F]:
794
801
  ``@classmethod``, this is the inner decorator. The wrapper keeps the signature, the docstring and
795
802
  ``__wrapped__``, sends nothing, and carries ``__surreal_cache_writes__``.
796
803
 
804
+ With a transaction, the tables are also noted on it as written with records (issue #304:
805
+ ``Transaction._note_record_write``, which ``define_indexes(tx=…)`` reads) — unless ``records=False``, which marks
806
+ a method that applies definitions (``define_table()``, ``remove_index()``…) and writes no record: its tables are
807
+ noted for the query cache only. The wrapper carries the flag as ``__surreal_record_writes__``.
808
+
797
809
  The one error of its own (v0.29.0): with ``"self"``, ``"edge"`` or ``"cls"``, a ``tx`` of another connection than
798
810
  the model's raises ``SurrealDbError`` (``routing.check_transaction()``) before the write is put in flight or noted
799
811
  on the transaction, so a refused write invalidates nothing. The transaction is read statically, never asked. A
@@ -818,10 +830,13 @@ def invalidates(of: _Of, *, deletes: bool = False) -> Callable[[F], F]:
818
830
  arg0 = bound.arguments[first]
819
831
  model = arg0 if isinstance(arg0, type) else type(arg0)
820
832
  _routing.check_transaction(model, tx, f"{model.__name__}.{func.__name__}()")
833
+ if records and tx is not None:
834
+ _note_records(tables, tx)
821
835
  async with writing(tables, tx):
822
836
  return await func(*args, **kwargs)
823
837
 
824
838
  wrapper.__surreal_cache_writes__ = True # type: ignore[attr-defined]
839
+ wrapper.__surreal_record_writes__ = records # type: ignore[attr-defined]
825
840
  return cast(F, wrapper)
826
841
 
827
842
  return decorate
@@ -485,7 +485,7 @@ class AuthenticatedUserMixin:
485
485
  return statements
486
486
 
487
487
  @classmethod
488
- @_cache.invalidates("cls")
488
+ @_cache.invalidates("cls", records=False)
489
489
  async def define_access(
490
490
  cls,
491
491
  *,
@@ -79,6 +79,7 @@ from .search import (
79
79
  remove_index_statement,
80
80
  stored_indexes_using,
81
81
  transaction_analyzer_refused,
82
+ transaction_write_refused,
82
83
  warn_redefined,
83
84
  )
84
85
  from .signals import (
@@ -950,7 +951,7 @@ class BaseSurrealModel(BaseModel):
950
951
  return statements
951
952
 
952
953
  @classmethod
953
- @_cache.invalidates("cls")
954
+ @_cache.invalidates("cls", records=False)
954
955
  async def define_computed_fields(
955
956
  cls,
956
957
  overwrite: bool = True,
@@ -1238,7 +1239,8 @@ class BaseSurrealModel(BaseModel):
1238
1239
  index of the database that uses it: ``INFO FOR TABLE`` of every other table (one request each, only then), and
1239
1240
  ``REBUILD INDEX`` for each of their indexes using it (sorted by table then index) before the index definitions,
1240
1241
  then for each unchanged index of this table using it after them (the declared ones in declaration order, then
1241
- the others). One warning per redefined analyzer names the indexes rebuilt (logger
1242
+ the others). One warning per redefined analyzer names the indexes rebuilt, in the order applied — the indexes
1243
+ this call defines with it included, which their ``DEFINE INDEX OVERWRITE`` rebuilds (logger
1242
1244
  ``surreal_orm_lite.search``). A rebuild re-reads the table — seconds per thousands of records on SurrealDB 2.x
1243
1245
  and the embedded engine.
1244
1246
 
@@ -1258,11 +1260,19 @@ class BaseSurrealModel(BaseModel):
1258
1260
  Before any DDL (nothing sent but the reads): an index that names by ``str`` an analyzer neither the database
1259
1261
  nor the model's ``Analyzer`` objects define is refused; with *tx*, an analyzer to define or redefine is refused
1260
1262
  — SurrealDB builds an index with the analyzers committed before the transaction began: define it first,
1261
- outside the block. With *tx* and the analyzers in place, the index statements join the transaction — applied at
1262
- once in an interactive one (WebSocket, SurrealDB 3.x), at the commit in a buffered one (HTTP, SurrealDB 2.x,
1263
- the embedded engine), where a refusal comes back as the transaction's own error; a block that raises applies
1264
- nothing. In a buffered transaction an index queued earlier in the block is not seen by the reads, and is
1265
- queued again (the same statement). Every cached read is dropped.
1263
+ outside the block. With *tx*, an index to define or redefine is also refused when the transaction has already
1264
+ written records to the model's table — an ORM write (``save()``, ``objects(tx=…).bulk_create()``, …) or one
1265
+ noted on every table; a definition such as ``define_table(tx=…)`` does not count, nor does a raw ``tx.add()``,
1266
+ which the ORM does not track: SurrealDB servers do not index the records a transaction wrote before the index
1267
+ was defined, which stay out of it after the commit — a server defect (surrealdb/surrealdb#7618 on 3.x, the
1268
+ same on 2.x; the embedded engine indexes them). The refusal does not fail the transaction; call
1269
+ ``define_indexes()`` without *tx* first. With *tx* and the analyzers in place, the index statements join the
1270
+ transaction — applied at once in an interactive one (WebSocket, SurrealDB 3.x),
1271
+ at the commit in a buffered one (HTTP, SurrealDB 2.x, the embedded engine), where a refusal comes back as the
1272
+ transaction's own error; a block that raises applies nothing. On SurrealDB 2.x, a write to a table that held
1273
+ records, after its index in the same block, fails the commit with a retryable ``SurrealDbConflictError`` that a
1274
+ retry meets again. In a buffered transaction an index queued earlier in the block is not seen by the reads, and
1275
+ is queued again (the same statement). Every cached read is dropped.
1266
1276
 
1267
1277
  Names are written in backticks, filters re-rendered from a closed grammar, numbers from Python numbers,
1268
1278
  comments as string literals. A refusal names the analyzer or the index and its table, never the statement:
@@ -1279,9 +1289,10 @@ class BaseSurrealModel(BaseModel):
1279
1289
  Raises:
1280
1290
  TypeError: *overwrite* is not a ``bool`` — before any request.
1281
1291
  SurrealDbError: *tx* belongs to another connection — before any request; an analyzer named by ``str`` does
1282
- not exist, or *tx* is given and an analyzer must be defined or redefined — before any DDL; the server
1283
- refused a statement (``Can't apply analyzer definition: …``, ``Can't apply index definition: …``,
1284
- ``Can't apply index rebuild: …``).
1292
+ not exist, or *tx* is given and an analyzer must be defined or redefined, or an index must be defined
1293
+ or redefined after the transaction wrote records to the model's table (the message names the model and
1294
+ the table) — before any DDL; the server refused a statement (``Can't apply analyzer definition: …``,
1295
+ ``Can't apply index definition: …``, ``Can't apply index rebuild: …``).
1285
1296
  SurrealDbAuthenticationError: the session may not read the definitions or define the analyzers and
1286
1297
  indexes.
1287
1298
 
@@ -1332,9 +1343,17 @@ class BaseSurrealModel(BaseModel):
1332
1343
  keyword=keyword,
1333
1344
  redefined=redefined,
1334
1345
  )
1346
+ # Issue #304: SurrealDB servers do not index the records a transaction wrote before the index was defined.
1347
+ # Under tx the analyzers are in place (refused above otherwise), so the definitions are all that would join it.
1348
+ if tx is not None and definitions:
1349
+ written = tx._records_written() if isinstance(tx, Transaction) else frozenset()
1350
+ if written is None or table in written:
1351
+ raise SurrealDbError(transaction_write_refused(cls.__name__, table))
1335
1352
  # A redefined analyzer leaves every index using it with its old tokens: the table's declared indexes (above),
1336
1353
  # its other indexes (another model's, or defined by hand), and every other table's — one INFO FOR TABLE each.
1337
1354
  analyzer_of = {index.name: index.analyzer_name or "" for index in indexes}
1355
+ # Issue #304: an index this call redefines is rebuilt by its DEFINE INDEX OVERWRITE; the warning names it too.
1356
+ redefined_indexes = [(table, name, analyzer_of[name]) for name, _ in definitions if analyzer_of[name] in redefined]
1338
1357
  own_rebuilds = [(table, name, analyzer_of[name]) for name, _ in rebuilds]
1339
1358
  own_rebuilds += stored_indexes_using(table, stored_indexes, redefined, skip=analyzer_of)
1340
1359
  other_rebuilds: list[tuple[str, str, str]] = []
@@ -1352,11 +1371,11 @@ class BaseSurrealModel(BaseModel):
1352
1371
  subjects=[index_subject(name, table) for name, _ in definitions],
1353
1372
  )
1354
1373
  applied += await apply_rebuilds(client, tx, own_rebuilds)
1355
- warn_redefined(redefine, [*other_rebuilds, *own_rebuilds])
1374
+ warn_redefined(redefine, [*other_rebuilds, *redefined_indexes, *own_rebuilds])
1356
1375
  return applied
1357
1376
 
1358
1377
  @classmethod
1359
- @_cache.invalidates("cls")
1378
+ @_cache.invalidates("cls", records=False)
1360
1379
  async def remove_index(cls, name: str, *, missing_ok: bool = True, tx: Transaction | None = None) -> str:
1361
1380
  """Remove the index named *name* from this model's table (v0.35.0) and return the statement applied.
1362
1381
 
@@ -1494,7 +1513,7 @@ class BaseSurrealModel(BaseModel):
1494
1513
  return view_statement(cls.get_table_name(), query, overwrite, clauses=cls._declared_table_clauses())
1495
1514
 
1496
1515
  @classmethod
1497
- @_cache.invalidates("cls")
1516
+ @_cache.invalidates("cls", records=False)
1498
1517
  async def define_view(cls, *, overwrite: bool = True, tx: Transaction | None = None) -> str:
1499
1518
  """Apply this materialized view to the database (v0.32.0) and return the statement applied.
1500
1519
 
@@ -1594,7 +1613,7 @@ class BaseSurrealModel(BaseModel):
1594
1613
  return statement
1595
1614
 
1596
1615
  @classmethod
1597
- @_cache.invalidates("cls")
1616
+ @_cache.invalidates("cls", records=False)
1598
1617
  async def remove_view(cls, *, missing_ok: bool = True, tx: Transaction | None = None) -> str:
1599
1618
  """Remove this materialized view from the database (v0.32.0) and return the statement applied.
1600
1619
 
@@ -1923,7 +1942,7 @@ class BaseSurrealModel(BaseModel):
1923
1942
  return [table_statement, *field_statements]
1924
1943
 
1925
1944
  @classmethod
1926
- @_cache.invalidates("cls")
1945
+ @_cache.invalidates("cls", records=False)
1927
1946
  async def define_table(cls, *, overwrite: bool = True, tx: Transaction | None = None) -> str:
1928
1947
  """Apply this model's table and field definitions (v0.34.0; the full SurrealDB-ORM's method) and return the
1929
1948
  statements applied — or queued, with a buffered transaction — table first, joined with ``"\\n"`` (the full
@@ -1063,6 +1063,16 @@ def transaction_analyzer_refused(model: str, name: str) -> str:
1063
1063
  )
1064
1064
 
1065
1065
 
1066
+ def transaction_write_refused(model: str, table: str) -> str:
1067
+ """The refusal of ``define_indexes(tx=…)`` when the transaction has already written records to *table*, the
1068
+ model's (issue #304): SurrealDB servers leave those records out of the index."""
1069
+ return (
1070
+ f"{model}.define_indexes(tx=…) cannot define an index on table {table!r} in a transaction that has already "
1071
+ "written to that table: SurrealDB servers do not index the records a transaction wrote before the index was "
1072
+ f"defined. Call {model}.define_indexes() without tx= first, then write in the transaction."
1073
+ )
1074
+
1075
+
1066
1076
  def plan_indexes(
1067
1077
  indexes: Iterable[Index],
1068
1078
  table: str,
@@ -1140,6 +1150,9 @@ def warn_redefined(redefine: Iterable[Analyzer], rebuilt: Sequence[IndexUse]) ->
1140
1150
  """Log one warning per analyzer of *redefine*, naming the indexes of *rebuilt* (``(table, index, analyzer)``) that
1141
1151
  use it, in order: ``Analyzer 'english' redefined; 2 index(es) rebuilt: page.page_title, post.post_title``.
1142
1152
 
1153
+ *rebuilt* is every index the caller rebuilt, in the order applied: a ``REBUILD INDEX``, and an index it redefined
1154
+ (``DEFINE INDEX OVERWRITE`` rebuilds it — issue #304).
1155
+
1143
1156
  An analyzer belongs to the database: two models declaring two definitions of one name redefine it in turn, and
1144
1157
  rebuild every index using it each time — the warning makes that visible.
1145
1158
  """
@@ -25,6 +25,11 @@ Query cache (v0.28.0): an ORM write that joins a transaction notes the tables it
25
25
  it returns or raises (a failed commit's state is unknown). ``cancel()`` forgets them: nothing
26
26
  became visible.
27
27
 
28
+ Records written (issue #304): an ORM write of records that joins a transaction also notes the tables it writes
29
+ (``_note_record_write``), apart from the query cache's — a definition such as ``define_table(tx=…)`` notes its table
30
+ for the cache only. ``define_indexes(tx=…)`` reads them (``_records_written``): SurrealDB servers do not index the
31
+ records a transaction wrote before the index was defined. A raw ``tx.add()`` is not noted.
32
+
28
33
  Errors (issue #278): the errors a failed transaction raises give the server's reason and the failed statement's
29
34
  position, without the server's excerpt of the statement; the server's own text stays reachable as their suppressed
30
35
  ``__context__``. A query the server or the embedded engine refuses at a buffered commit raises ``SurrealDbError`` on
@@ -223,6 +228,10 @@ class Transaction(ABC):
223
228
  # Query cache: the tables written in this transaction, invalidated at commit.
224
229
  self._cache_tables: set[str] = set()
225
230
  self._cache_all = False
231
+ # Issue #304: the tables an ORM write of records changed in this transaction (definitions excluded), kept
232
+ # until the transaction ends.
233
+ self._record_tables: set[str] = set()
234
+ self._record_all = False
226
235
  # Issue #268: the errors of the statements that failed in this transaction (interactive strategy).
227
236
  self._failures: list[BaseException] = []
228
237
 
@@ -264,6 +273,23 @@ class Transaction(ABC):
264
273
  self._cache_tables.clear()
265
274
  self._cache_all = False
266
275
 
276
+ def _note_record_write(self, tables: Iterable[str] | None) -> None:
277
+ """Note the tables an ORM write of records in this transaction changes (``None``: every table) — issue #304.
278
+
279
+ ``cache.invalidates()`` calls it for each write method of records that joins the transaction, before the write
280
+ is sent or queued — never for a definition (``define_table()``, ``remove_index()``…), whose table is noted for
281
+ the query cache only. Unlike the query cache's tables, the commit and the cancel keep them.
282
+ """
283
+ if tables is None:
284
+ self._record_all = True
285
+ else:
286
+ self._record_tables |= set(tables)
287
+
288
+ def _records_written(self) -> frozenset[str] | None:
289
+ """The tables an ORM write of records changed so far in this transaction (issue #304): ``None`` when one noted
290
+ every table. ``define_indexes(tx=…)`` reads it; a raw ``tx.add()`` is not counted."""
291
+ return None if self._record_all else frozenset(self._record_tables)
292
+
267
293
  @property
268
294
  @abstractmethod
269
295
  def is_interactive(self) -> bool: