surreal-orm-lite 0.37.5__tar.gz → 0.37.7__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 (51) hide show
  1. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/CHANGELOG.md +57 -0
  2. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/PKG-INFO +21 -21
  3. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/README.md +20 -20
  4. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/cache.py +81 -12
  7. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/connection_manager.py +11 -0
  8. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/edge.py +5 -3
  9. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/model_base.py +30 -21
  10. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/query_set.py +14 -8
  11. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/transaction.py +55 -13
  12. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/.gitignore +0 -0
  13. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/LICENSE +0 -0
  14. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/Makefile +0 -0
  15. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/_sdk.py +0 -0
  16. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/aggregations.py +0 -0
  17. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/auth.py +0 -0
  18. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/changefeed.py +0 -0
  19. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/concurrency.py +0 -0
  20. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/connection_config.py +0 -0
  21. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/constants.py +0 -0
  22. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/decoding.py +0 -0
  23. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/define_parser.py +0 -0
  24. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/embedded.py +0 -0
  25. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/encoding.py +0 -0
  26. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/enum.py +0 -0
  27. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/exceptions.py +0 -0
  28. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/functions.py +0 -0
  29. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/geo.py +0 -0
  30. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/hybrid.py +0 -0
  31. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/introspection.py +0 -0
  32. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/live.py +0 -0
  33. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/model_auth.py +0 -0
  34. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/model_ddl.py +0 -0
  35. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/model_generator.py +0 -0
  36. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/py.typed +0 -0
  37. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/q.py +0 -0
  38. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/routing.py +0 -0
  39. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/schema.py +0 -0
  40. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/schema_state.py +0 -0
  41. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/search.py +0 -0
  42. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/signals.py +0 -0
  43. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/subquery.py +0 -0
  44. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/surql_literal.py +0 -0
  45. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/testing/__init__.py +0 -0
  46. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/testing/database.py +0 -0
  47. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  48. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/time_travel.py +0 -0
  49. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/types.py +0 -0
  50. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/utils.py +0 -0
  51. {surreal_orm_lite-0.37.5 → surreal_orm_lite-0.37.7}/src/surreal_orm_lite/vector.py +0 -0
@@ -5,6 +5,63 @@ 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.37.7] - 2026-10-28
9
+
10
+ Follow-up to the review of v0.37.0 (#320): a write the ORM refuses before it reaches the database
11
+ now leaves its transaction and the query cache as they were, wherever in the method the refusal
12
+ comes from. No new public API.
13
+
14
+ ### Fixed
15
+
16
+ - **A refused write no longer counts as a write** (#325). Since v0.37.0 the refusals that need no
17
+ request ran before the write's tables were noted; a few refusals still ran in the method's body
18
+ and left the table noted on the transaction (so a later `define_indexes(tx=tx)` on that table was
19
+ refused, and the commit dropped the table's cached reads although nothing was written) or, outside
20
+ a transaction, dropped its cached reads when the call ended. They are: `upsert()` without an id,
21
+ `save(tx=…)` without an id on a buffered transaction, a field name or an `extra_vars` key that
22
+ `save(server_values=…)` or `merge(server_values=…)` refuses, the checks of `relate()`,
23
+ `remove_relation()` and `remove_all_relations()` (an invalid edge name no longer counts as a write
24
+ to every table), a field or a filter refused while a QuerySet write is compiled, an edge id of
25
+ another table, and a value the ORM cannot send (a `field_serializer` that raises, a negative
26
+ duration, an `int` outside the signed 64-bit range…). A write now counts once its statement is
27
+ queued or sent, or once it asked the connection for a client; before that, its notes are taken
28
+ back, and the notes of every other write on the same tables, a concurrent or an enclosing one
29
+ included, stay. A write that raises after that point still counts, since what the server applied
30
+ is unknown. Error types, messages and their order are unchanged.
31
+
32
+ ### Changed
33
+
34
+ - The values of a write are encoded before the connection is asked for a client, so a value the ORM
35
+ cannot send is refused without opening a connection.
36
+ - The README (section 36, _Transactions_) lists the refusals that do not count as a write and drops
37
+ the note that they still did.
38
+
39
+ ### Notes
40
+
41
+ - The bookkeeping is client-side: the behaviour is the same on SurrealDB 2.x and 3.x, on the
42
+ embedded engine and on both transaction strategies.
43
+
44
+ ## [0.37.6] - 2026-10-27
45
+
46
+ Follow-up to the review of v0.37.0 (#340): `hybrid_search()`'s docstring words its cross-line guarantee as
47
+ README section 38 does, and an empty `text_query` is tested against a server. No new public API.
48
+
49
+ ### Fixed
50
+
51
+ - **`hybrid_search()`'s docstring states the cross-line guarantee with its condition** (#343).
52
+ `help(QuerySet.hybrid_search)` said the records, scores and order are the same on every line;
53
+ it now says that the same two lists give the same records, scores and order on every line, and
54
+ that the lists themselves can differ (the HNSW search is approximate, the full-text list follows
55
+ the line's BM25 scores). The `dist` argument names the exact scan's ties at the `vector_limit`-th
56
+ place on SurrealDB 2.x and the embedded engine, which the ORM keeps by id since v0.37.4.
57
+
58
+ ### Changed
59
+
60
+ - A server test now covers an empty `text_query`: it matches nothing, so the vector list alone is
61
+ fused and every `_search_score` is `None`, with the HNSW index and with an exact scan, over
62
+ WebSocket and HTTP and on the embedded engine. Measured on SurrealDB 2.7.0 and 3.3.4; 3.1.5
63
+ behaves as 3.3.4.
64
+
8
65
  ## [0.37.4] - 2026-10-27
9
66
 
10
67
  Follow-up to the review of v0.37.0 (#340): the exact scan (`dist=`) of `similar_to()` and
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.37.5
3
+ Version: 0.37.7
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
@@ -3816,6 +3816,11 @@ Every ORM write removes the cached reads it can change, **before** its `post_*`
3816
3816
  cache.
3817
3817
  - While a write runs, cached reads of its tables go to the database and store nothing: a read
3818
3818
  answered before the write completed is returned to its caller, never stored.
3819
+ - A write the ORM refuses before it reaches the database — for its arguments, while it is built
3820
+ (an `upsert()` without an id, a field name the statement cannot take…), or for a value it cannot
3821
+ send — removes nothing, and in a transaction notes nothing for the commit to invalidate. Once its
3822
+ statement is queued or sent, or it asked the connection for a client, it counts as a write,
3823
+ whatever it raises.
3819
3824
 
3820
3825
  What the cache **cannot see** — the TTL bounds it, and `QueryCache.invalidate(Model)` removes a
3821
3826
  table's entries after such a change:
@@ -5789,7 +5794,7 @@ print(*table, sep="\n")
5789
5794
  - A write naming a field a `SCHEMAFULL` table does not define is refused on 3.x and dropped on 2.x and the embedded
5790
5795
  engine ("What SurrealDB checks" above), except in the items of a list of objects: on 3.x of a list whose items define
5791
5796
  a field (every list of sub-models `define_table()` writes), on 2.x and the embedded engine of a list `define_table()`
5792
- writes `FLEXIBLE`.
5797
+ writes `FLEXIBLE`. The 3.x exception is a gap fixed in SurrealDB 3.4 (nightly at the time of writing).
5793
5798
  - `COMPUTED` fields are SurrealDB 3.x's: `define_table()` keeps a stored one `COMPUTED`, and writes a new computed
5794
5799
  field `VALUE` on both lines.
5795
5800
  - The [2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x) and the
@@ -6121,23 +6126,18 @@ print(await NoteV2.objects().search(text="physics").count())
6121
6126
  missing them would not enforce uniqueness for them. The refusal does not fail the block. `define_table(tx=…)`,
6122
6127
  `define_relation(tx=…)` and a write to another table do not count, nor does a write the ORM refused before sending or
6123
6128
  queuing it: one refused for a materialized view, a snapshot read with `as_of()`, an auth model with a
6124
- `Field(exclude=True)` field SIGNUP writes, a `tx=` of another connection, or one of its arguments (a missing id,
6125
- invalid patch operations, an invalid `server_values`/`extra_vars` pair or either one on an edge's `save()`, a computed
6126
- field or an edge endpoint among the fields written, an atomic helper's field, amount or values, a subquery value in
6127
- `bulk_update()`, a snapshot in `bulk_create()`'s list); a raw `tx.add()` is not tracked. Until
6128
- [EulogySnowfall/SurrealDB-ORM-lite#325](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/325) is fixed,
6129
- some refusals made while the write is built or its values are encoded still count, although nothing was sent or
6130
- queued: `upsert()` without an id, `save(tx=…)` without an id in a buffered transaction, a field name or an
6131
- `extra_vars` key refused while the statement of `save(server_values=…)` or `merge(server_values=…)` is compiled (an
6132
- invalid name, a key that collides with an internal binding), the argument checks of `relate()`, `remove_relation()`
6133
- and `remove_all_relations()` (an invalid edge name, or an empty list of edges, counts as a write to every table, so
6134
- every later `define_indexes(tx=…)` in the block is refused), a field name `bulk_update()` refuses, a filter refused
6135
- while the statement of `objects(tx=…).bulk_update()`, `bulk_delete()` or `patch()` is compiled, an edge id of another
6136
- table in an edge's `save()` or `bulk_create()`, and a value the ORM cannot send, in any write (a field, a filter, a
6137
- patch operation, an atomic helper's value or amount, a relation's data, `extra_vars`): a `field_serializer` that
6138
- raises, or one of the [values refused before sending](#values-refused-before-sending), such as a negative duration,
6139
- an `int` outside the signed 64-bit range or a `Decimal` out of range. A write refused first for one of the arguments
6140
- listed above, such as an `update()` or a `merge()` without an id, does not count.
6129
+ `Field(exclude=True)` field SIGNUP writes, a `tx=` of another connection, one of its arguments (a missing id, invalid
6130
+ patch operations, an invalid `server_values`/`extra_vars` pair, a computed field or an edge endpoint among the fields
6131
+ written, an atomic helper's field, amount or values, a subquery value in `bulk_update()`, a snapshot in
6132
+ `bulk_create()`'s list), or while the write is built: `upsert()` without an id, `save(tx=…)` without an id in a
6133
+ buffered transaction, a field name or an `extra_vars` key the statement cannot take, the checks of `relate()`,
6134
+ `remove_relation()` and `remove_all_relations()` (an invalid edge name, an empty list of edges, an unsaved record, an
6135
+ invalid direction or target), a field or a filter refused while a QuerySet write is compiled, an edge id of another
6136
+ table, a `field_serializer` that raises, and a value the ORM cannot send in any write (a field, a filter, a patch
6137
+ operation, an atomic helper's value, a relation's data, `extra_vars`), such as one of the
6138
+ [values refused before sending](#values-refused-before-sending); a raw `tx.add()` is not tracked. A write counts once
6139
+ it reached the database: when it raises after its statement was queued or sent, or after it, or one of its `pre_*`
6140
+ handlers, asked the connection for a client, its table stays counted.
6141
6141
  - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6142
6142
  in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again; so does a
6143
6143
  block that removes an index of a table that held records and defines it again, where the index stands as before.
@@ -6854,7 +6854,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6854
6854
  | Cleanup on a missing target (`delete_table`) | native no-op | ORM makes it a silent no-op | v0.7.0 |
6855
6855
  | Aggregation over an empty set (`NaN` / `±inf`) | returns `0.0` / `None` | ORM normalises to `0.0` / `None` | v0.7.0 |
6856
6856
  | Namespace/db selection (`use()` ordering) | lenient (auto-creates) | strict — ORM signs in before `use()` | v0.7.0 |
6857
- | Writing a field a `SCHEMAFULL` table does not define (`CREATE`, `INSERT`, `INSERT RELATION`) | silently dropped: the record is stored without it; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | rejected ("Found field …, but no such field exists"): nothing is stored, except in the items of a list whose items define a field (every list of sub-models), which keep it | v0.7.0 |
6857
+ | Writing a field a `SCHEMAFULL` table does not define (`CREATE`, `INSERT`, `INSERT RELATION`) | silently dropped: the record is stored without it; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | rejected ("Found field …, but no such field exists"): nothing is stored, except in the items of a list whose items define a field (every list of sub-models), a gap fixed in 3.4 | v0.7.0 |
6858
6858
  | `upsert()` / `update_or_create()` / `get_or_create()` | same on both lines | same on both lines | v0.10.0 |
6859
6859
  | `patch()` / `atomic_append` / `atomic_set_add` / `atomic_remove` / `atomic_increment` | same on both lines (portable `array::*` fns chosen over divergent `+=`/`-=`) | same on both lines | v0.11.0 |
6860
6860
  | `retry_on_conflict` / `SurrealDbConflictError` (retryable conflict) | same type + decorator; conflicts rarer (engine serialises more), except on `CHANGEFEED` tables (section 22) | same type + decorator; conflicts are the normal optimistic-MVCC failure | v0.12.0 |
@@ -7042,7 +7042,7 @@ Capabilities not listed behave as on a 2.x server.
7042
7042
  | Server-side events and stored functions (v0.31.0) | as on a 2.x server: `$input` is `NONE`; `Event(async_mode=True)` raises `SurrealDbError` before any DDL | `ASYNC` events on 3.x | v0.31.0 |
7043
7043
  | Materialized views (v0.32.0) | as on a 2.x server: `int` sums and `Decimal` means; in a grouped view, `math::stddev()`/`math::variance()`, an expression around an aggregate, a field outside `GROUP BY` and a `GROUP BY` on an alias raise `SurrealDbError` before any DDL; writes to a view refused by the ORM (the engine would accept them); no live queries | `float` sums and means on 3.x | v0.32.0 |
7044
7044
  | 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 |
7045
- | 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 |
7045
+ | 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 them without `FLEXIBLE`, refuses that write except in list items defining a field, a gap fixed in 3.4 | v0.34.0 |
7046
7046
  | 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 |
7047
7047
  | `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 |
7048
7048
  | Vector search (v0.36.0) | as on a 2.x server: `MTREE` accepted, at most `ef` records returned (the ORM raises `ef` to `limit`), other conditions selected first in a `LET` (search annotations refused), writes made by the ids of the nearest, fewer records with a selective condition; an index without `TYPE` is `F64` (servers: `F32`), so the ORM always writes `TYPE` | 3.x refuses `MTREE`, applies the conditions during the index search and keeps search annotations | v0.36.0 |
@@ -3765,6 +3765,11 @@ Every ORM write removes the cached reads it can change, **before** its `post_*`
3765
3765
  cache.
3766
3766
  - While a write runs, cached reads of its tables go to the database and store nothing: a read
3767
3767
  answered before the write completed is returned to its caller, never stored.
3768
+ - A write the ORM refuses before it reaches the database — for its arguments, while it is built
3769
+ (an `upsert()` without an id, a field name the statement cannot take…), or for a value it cannot
3770
+ send — removes nothing, and in a transaction notes nothing for the commit to invalidate. Once its
3771
+ statement is queued or sent, or it asked the connection for a client, it counts as a write,
3772
+ whatever it raises.
3768
3773
 
3769
3774
  What the cache **cannot see** — the TTL bounds it, and `QueryCache.invalidate(Model)` removes a
3770
3775
  table's entries after such a change:
@@ -5738,7 +5743,7 @@ print(*table, sep="\n")
5738
5743
  - A write naming a field a `SCHEMAFULL` table does not define is refused on 3.x and dropped on 2.x and the embedded
5739
5744
  engine ("What SurrealDB checks" above), except in the items of a list of objects: on 3.x of a list whose items define
5740
5745
  a field (every list of sub-models `define_table()` writes), on 2.x and the embedded engine of a list `define_table()`
5741
- writes `FLEXIBLE`.
5746
+ writes `FLEXIBLE`. The 3.x exception is a gap fixed in SurrealDB 3.4 (nightly at the time of writing).
5742
5747
  - `COMPUTED` fields are SurrealDB 3.x's: `define_table()` keeps a stored one `COMPUTED`, and writes a new computed
5743
5748
  field `VALUE` on both lines.
5744
5749
  - The [2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x) and the
@@ -6070,23 +6075,18 @@ print(await NoteV2.objects().search(text="physics").count())
6070
6075
  missing them would not enforce uniqueness for them. The refusal does not fail the block. `define_table(tx=…)`,
6071
6076
  `define_relation(tx=…)` and a write to another table do not count, nor does a write the ORM refused before sending or
6072
6077
  queuing it: one refused for a materialized view, a snapshot read with `as_of()`, an auth model with a
6073
- `Field(exclude=True)` field SIGNUP writes, a `tx=` of another connection, or one of its arguments (a missing id,
6074
- invalid patch operations, an invalid `server_values`/`extra_vars` pair or either one on an edge's `save()`, a computed
6075
- field or an edge endpoint among the fields written, an atomic helper's field, amount or values, a subquery value in
6076
- `bulk_update()`, a snapshot in `bulk_create()`'s list); a raw `tx.add()` is not tracked. Until
6077
- [EulogySnowfall/SurrealDB-ORM-lite#325](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/325) is fixed,
6078
- some refusals made while the write is built or its values are encoded still count, although nothing was sent or
6079
- queued: `upsert()` without an id, `save(tx=…)` without an id in a buffered transaction, a field name or an
6080
- `extra_vars` key refused while the statement of `save(server_values=…)` or `merge(server_values=…)` is compiled (an
6081
- invalid name, a key that collides with an internal binding), the argument checks of `relate()`, `remove_relation()`
6082
- and `remove_all_relations()` (an invalid edge name, or an empty list of edges, counts as a write to every table, so
6083
- every later `define_indexes(tx=…)` in the block is refused), a field name `bulk_update()` refuses, a filter refused
6084
- while the statement of `objects(tx=…).bulk_update()`, `bulk_delete()` or `patch()` is compiled, an edge id of another
6085
- table in an edge's `save()` or `bulk_create()`, and a value the ORM cannot send, in any write (a field, a filter, a
6086
- patch operation, an atomic helper's value or amount, a relation's data, `extra_vars`): a `field_serializer` that
6087
- raises, or one of the [values refused before sending](#values-refused-before-sending), such as a negative duration,
6088
- an `int` outside the signed 64-bit range or a `Decimal` out of range. A write refused first for one of the arguments
6089
- listed above, such as an `update()` or a `merge()` without an id, does not count.
6078
+ `Field(exclude=True)` field SIGNUP writes, a `tx=` of another connection, one of its arguments (a missing id, invalid
6079
+ patch operations, an invalid `server_values`/`extra_vars` pair, a computed field or an edge endpoint among the fields
6080
+ written, an atomic helper's field, amount or values, a subquery value in `bulk_update()`, a snapshot in
6081
+ `bulk_create()`'s list), or while the write is built: `upsert()` without an id, `save(tx=…)` without an id in a
6082
+ buffered transaction, a field name or an `extra_vars` key the statement cannot take, the checks of `relate()`,
6083
+ `remove_relation()` and `remove_all_relations()` (an invalid edge name, an empty list of edges, an unsaved record, an
6084
+ invalid direction or target), a field or a filter refused while a QuerySet write is compiled, an edge id of another
6085
+ table, a `field_serializer` that raises, and a value the ORM cannot send in any write (a field, a filter, a patch
6086
+ operation, an atomic helper's value, a relation's data, `extra_vars`), such as one of the
6087
+ [values refused before sending](#values-refused-before-sending); a raw `tx.add()` is not tracked. A write counts once
6088
+ it reached the database: when it raises after its statement was queued or sent, or after it, or one of its `pre_*`
6089
+ handlers, asked the connection for a client, its table stays counted.
6090
6090
  - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6091
6091
  in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again; so does a
6092
6092
  block that removes an index of a table that held records and defines it again, where the index stands as before.
@@ -6803,7 +6803,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6803
6803
  | Cleanup on a missing target (`delete_table`) | native no-op | ORM makes it a silent no-op | v0.7.0 |
6804
6804
  | Aggregation over an empty set (`NaN` / `±inf`) | returns `0.0` / `None` | ORM normalises to `0.0` / `None` | v0.7.0 |
6805
6805
  | Namespace/db selection (`use()` ordering) | lenient (auto-creates) | strict — ORM signs in before `use()` | v0.7.0 |
6806
- | Writing a field a `SCHEMAFULL` table does not define (`CREATE`, `INSERT`, `INSERT RELATION`) | silently dropped: the record is stored without it; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | rejected ("Found field …, but no such field exists"): nothing is stored, except in the items of a list whose items define a field (every list of sub-models), which keep it | v0.7.0 |
6806
+ | Writing a field a `SCHEMAFULL` table does not define (`CREATE`, `INSERT`, `INSERT RELATION`) | silently dropped: the record is stored without it; kept in the items of a list `define_table()` writes `FLEXIBLE` (a 2.x limitation) | rejected ("Found field …, but no such field exists"): nothing is stored, except in the items of a list whose items define a field (every list of sub-models), a gap fixed in 3.4 | v0.7.0 |
6807
6807
  | `upsert()` / `update_or_create()` / `get_or_create()` | same on both lines | same on both lines | v0.10.0 |
6808
6808
  | `patch()` / `atomic_append` / `atomic_set_add` / `atomic_remove` / `atomic_increment` | same on both lines (portable `array::*` fns chosen over divergent `+=`/`-=`) | same on both lines | v0.11.0 |
6809
6809
  | `retry_on_conflict` / `SurrealDbConflictError` (retryable conflict) | same type + decorator; conflicts rarer (engine serialises more), except on `CHANGEFEED` tables (section 22) | same type + decorator; conflicts are the normal optimistic-MVCC failure | v0.12.0 |
@@ -6991,7 +6991,7 @@ Capabilities not listed behave as on a 2.x server.
6991
6991
  | Server-side events and stored functions (v0.31.0) | as on a 2.x server: `$input` is `NONE`; `Event(async_mode=True)` raises `SurrealDbError` before any DDL | `ASYNC` events on 3.x | v0.31.0 |
6992
6992
  | Materialized views (v0.32.0) | as on a 2.x server: `int` sums and `Decimal` means; in a grouped view, `math::stddev()`/`math::variance()`, an expression around an aggregate, a field outside `GROUP BY` and a `GROUP BY` on an alias raise `SurrealDbError` before any DDL; writes to a view refused by the ORM (the engine would accept them); no live queries | `float` sums and means on 3.x | v0.32.0 |
6993
6993
  | 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 |
6994
- | 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 |
6994
+ | 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 them without `FLEXIBLE`, refuses that write except in list items defining a field, a gap fixed in 3.4 | v0.34.0 |
6995
6995
  | 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 |
6996
6996
  | `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 |
6997
6997
  | Vector search (v0.36.0) | as on a 2.x server: `MTREE` accepted, at most `ef` records returned (the ORM raises `ef` to `limit`), other conditions selected first in a `LET` (search annotations refused), writes made by the ids of the nearest, fewer records with a selective condition; an index without `TYPE` is `F64` (servers: `F32`), so the ORM always writes `TYPE` | 3.x refuses `MTREE`, applies the conditions during the index search and keeps search annotations | v0.36.0 |
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.37.5"
3
+ version = "0.37.7"
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.37.5"
1
+ __version__ = "0.37.7"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -21,6 +21,8 @@ What makes a cached result right:
21
21
  of them is stored), then bumps their generations and removes their entries; a read that follows links
22
22
  (``any_table``) is removed by every write. ``EDGES`` tags the reads of edge tables, which every
23
23
  delete invalidates (a deleted record's edges go with it).
24
+ - **Refused writes** (issue #325): a write that raises before it reached the database (:func:`reaching`) changed
25
+ nothing: its tables leave flight without being invalidated, or its notes are taken back from its transaction.
24
26
 
25
27
  Internal failures never fail a read: keying, copying a hit and copying a result to store fall back to the database.
26
28
  Nothing is logged but the fixed warning of an SDK without a CBOR encoder: no row, variable or key.
@@ -48,6 +50,7 @@ import weakref
48
50
  from collections import OrderedDict
49
51
  from collections.abc import AsyncIterator, Callable, Coroutine, Iterable, Iterator, Mapping
50
52
  from contextlib import asynccontextmanager, contextmanager
53
+ from contextvars import ContextVar
51
54
  from dataclasses import dataclass
52
55
  from datetime import timedelta
53
56
  from typing import TYPE_CHECKING, Any, ClassVar, Final, Literal, TypeVar, cast
@@ -532,6 +535,21 @@ class QueryCache:
532
535
  cls._in_flight.pop(table, None)
533
536
  cls._invalidate_tables(token)
534
537
 
538
+ @classmethod
539
+ def _write_withdrawn(cls, token: frozenset[str] | None) -> None:
540
+ """End a write that changed nothing (issue #325): its tables leave flight, no generation moves and no entry
541
+ goes. A read that began before it and finishes after it may store its result."""
542
+ with cls._guard():
543
+ if token is None:
544
+ cls._in_flight_all = max(0, cls._in_flight_all - 1)
545
+ return
546
+ for table in token:
547
+ count = cls._in_flight.get(table, 0) - 1
548
+ if count > 0:
549
+ cls._in_flight[table] = count
550
+ else:
551
+ cls._in_flight.pop(table, None)
552
+
535
553
  # --- scopes -------------------------------------------------------------------------------------------
536
554
 
537
555
  @classmethod
@@ -718,13 +736,44 @@ def retire_client(client: Any) -> None:
718
736
  # --- writes (the ORM's write methods, transactions) -----------------------------------------------------------
719
737
 
720
738
 
739
+ @dataclass(eq=False, slots=True)
740
+ class _Attempt:
741
+ """One write in progress (:func:`writing`): whether it reached the database (:func:`reaching`)."""
742
+
743
+ reached: bool = False
744
+
745
+
746
+ #: The writes in progress in this context, innermost last (issue #325). Each task has its own: a concurrent write
747
+ #: that reaches the database never makes another task's write count as reached; a nested one reaches every write
748
+ #: around it.
749
+ _attempts: ContextVar[tuple[_Attempt, ...]] = ContextVar("surreal_orm_lite_cache_attempts", default=())
750
+
751
+
752
+ def reaching() -> None:
753
+ """Mark every write in progress in this context as having reached the database (issue #325).
754
+
755
+ Called wherever a write may stop changing nothing: ``Transaction.add()`` once its variables are encoded, an
756
+ interactive transaction's ``run_read()`` and commit, a buffered commit once its request is built, and the
757
+ connection manager whenever it hands out a client. A write that raises after it is marked counts as written:
758
+ what the server applied is unknown. Outside a write: nothing.
759
+ """
760
+ for attempt in _attempts.get():
761
+ attempt.reached = True
762
+
763
+
721
764
  @asynccontextmanager
722
- async def writing(tables: Iterable[str] | None, tx: Any = None) -> AsyncIterator[None]:
765
+ async def writing(tables: Iterable[str] | None, tx: Any = None, *, records: bool = False) -> AsyncIterator[None]:
723
766
  """Around one ORM write of ``tables`` (``None``: every table).
724
767
 
725
768
  Outside a transaction, the tables are in flight for the whole block (a cached read of them goes to the database
726
769
  and stores nothing), then invalidated when it ends, also on an exception. With a transaction (``tx`` whose class
727
- has ``_note_cache_write``), the tables are noted on it and invalidated at its commit. No table: nothing.
770
+ has ``_note_cache_write``), the tables are noted on it and invalidated at its commit; with ``records``, they are
771
+ also noted as written with records (``_note_record_write``, issue #304). No table: nothing.
772
+
773
+ Issue #325: a block that raises before it reached the database (:func:`reaching`) changed nothing. Outside a
774
+ transaction its tables leave flight without being invalidated; with one, the notes it made are taken back
775
+ (``_withdraw_write``, which keeps those of every other write, a concurrent or an enclosing one included). A block
776
+ that reached the database, or that returns, counts as a write.
728
777
 
729
778
  The transaction is recognised by its class, never by asking the object (no instance ``__getattr__`` runs), so a
730
779
  write refused before it reaches its transaction leaves the object untouched.
@@ -733,15 +782,32 @@ async def writing(tables: Iterable[str] | None, tx: Any = None) -> AsyncIterator
733
782
  if resolved is not None and not resolved:
734
783
  yield
735
784
  return
736
- if tx is not None and callable(getattr(type(tx), "_note_cache_write", None)):
737
- tx._note_cache_write(resolved)
738
- yield
739
- return
740
- token = QueryCache._write_started(resolved)
785
+ attempt = _Attempt()
786
+ reset = _attempts.set((*_attempts.get(), attempt))
741
787
  try:
742
- yield
743
- finally:
788
+ if tx is not None and callable(getattr(type(tx), "_note_cache_write", None)):
789
+ if records:
790
+ _note_records(resolved, tx)
791
+ tx._note_cache_write(resolved)
792
+ try:
793
+ yield
794
+ except BaseException:
795
+ if not attempt.reached and callable(getattr(type(tx), "_withdraw_write", None)):
796
+ tx._withdraw_write(resolved, records=records)
797
+ raise
798
+ return
799
+ token = QueryCache._write_started(resolved)
800
+ try:
801
+ yield
802
+ except BaseException:
803
+ if attempt.reached:
804
+ QueryCache._write_finished(token)
805
+ else:
806
+ QueryCache._write_withdrawn(token)
807
+ raise
744
808
  QueryCache._write_finished(token)
809
+ finally:
810
+ _attempts.reset(reset)
745
811
 
746
812
 
747
813
  F = TypeVar("F", bound=Callable[..., Coroutine[Any, Any, Any]])
@@ -828,6 +894,11 @@ def invalidates(
828
894
  and never ask the transaction. Whatever they raise propagates: a write they refuse leaves the transaction as it was
829
895
  (no statement, no table noted) and invalidates nothing — no table in flight, no cached read dropped. Neither is
830
896
  called when the arguments do not bind (Python raises the function's own error).
897
+
898
+ A refusal of the method's body (issue #325) — an id it needs, a name the statement cannot take, a payload that
899
+ cannot be serialized, a value the ORM cannot send — raises before the write reached the database, so
900
+ :func:`writing` takes back what the call noted on the transaction, or puts its tables out of flight without
901
+ invalidating them. Once the call reached the database, it counts as written, whatever it raises.
831
902
  """
832
903
  if of not in _RESOLVERS:
833
904
  raise ValueError(f"invalidates() takes one of {sorted(_RESOLVERS)}, not {of!r}")
@@ -853,9 +924,7 @@ def invalidates(
853
924
  refuse(bound.arguments[first])
854
925
  if refuse_args is not None:
855
926
  refuse_args(bound.arguments)
856
- if records and tx is not None:
857
- _note_records(tables, tx)
858
- async with writing(tables, tx):
927
+ async with writing(tables, tx, records=records and tx is not None):
859
928
  return await func(*args, **kwargs)
860
929
 
861
930
  wrapper.__surreal_cache_writes__ = True # type: ignore[attr-defined]
@@ -829,6 +829,9 @@ class SurrealDBConnectionManager:
829
829
  these clients get it: a client the application builds itself with ``AsyncSurreal`` keeps the
830
830
  SDK's behaviour.
831
831
 
832
+ Like every way the ORM gets a client, it marks the ORM writes in progress as having reached the database
833
+ (``cache.reaching()``, issue #325).
834
+
832
835
  On an **embedded** URL the SDK's constructor opens the in-process engine and ``connect()``
833
836
  takes no argument; nobody is signed in, whatever *signin_as_configured* says: the engine
834
837
  has no system user on a fresh database, and its anonymous session is the in-process owner.
@@ -838,6 +841,7 @@ class SurrealDBConnectionManager:
838
841
  :raises SurrealDbConnectionError: the client cannot be opened; on an embedded URL the error
839
842
  quotes the engine's own message and is never retryable (a bad path stays bad).
840
843
  """
844
+ _cache.reaching()
841
845
  assert cls.__url is not None
842
846
  assert cls.__namespace is not None
843
847
  assert cls.__database is not None
@@ -951,7 +955,11 @@ class SurrealDBConnectionManager:
951
955
  :param still_wanted: for a background reconnect — checked again just before a new client
952
956
  is published, so a connection the application closed meanwhile is not reopened behind
953
957
  its back. Not used on an embedded URL: an in-process client never drops.
958
+
959
+ Issue #325: an ORM write in progress that asks for a client counts as having reached the database
960
+ (``cache.reaching()``), whatever it raises afterwards.
954
961
  """
962
+ _cache.reaching()
955
963
  loop = asyncio.get_running_loop()
956
964
  cls.__prune_dead_loops()
957
965
  # Before the per-loop fast path: once the URL changed to one the SDK refuses (set_url()),
@@ -1253,7 +1261,10 @@ class SurrealDBConnectionManager:
1253
1261
  name again with other settings, or ``remove_connection()`` removes it, while the engine opens or its session
1254
1262
  is selected again, the call raises a retryable ``SurrealDbConnectionError`` instead of serving the old settings
1255
1263
  (:meth:`_refuse_retired_embedded`).
1264
+
1265
+ Issue #325: an ORM write in progress counts as having reached the database (``cache.reaching()``).
1256
1266
  """
1267
+ _cache.reaching()
1257
1268
  if not is_embedded_url(cls.__url):
1258
1269
  return None
1259
1270
  cls.require_connection()
@@ -138,12 +138,14 @@ async def insert_edges(
138
138
  if not tx.is_interactive:
139
139
  return []
140
140
  else:
141
+ guarded = any("id" in row for row in rows)
142
+ encoded = _encoding.encode({"data": data} if guarded else data) # issue #325: refused before any client is asked for
141
143
  client = await manager.get_client()
142
144
  try:
143
- if any("id" in row for row in rows):
144
- result = await client.query(_GUARDED_INSERT.format(table=table), _encoding.encode({"data": data}))
145
+ if guarded:
146
+ result = await client.query(_GUARDED_INSERT.format(table=table), encoded)
145
147
  else:
146
- result = await client.insert_relation(table, _encoding.encode(data))
148
+ result = await client.insert_relation(table, encoded)
147
149
  except ServerError as exc:
148
150
  raise edge_write_error(exc) from exc
149
151
  returned = _as_rows(result)
@@ -3252,6 +3252,7 @@ class BaseSurrealModel(BaseModel):
3252
3252
  self._apply_record(rows)
3253
3253
  return self, True
3254
3254
 
3255
+ payload = _encoding.encode(data) # issue #325: refused before any client is asked for
3255
3256
  client = await type(self)._connection_manager().get_client()
3256
3257
 
3257
3258
  if record_id is not None:
@@ -3261,7 +3262,7 @@ class BaseSurrealModel(BaseModel):
3261
3262
  # ServerError, so catch the base and match on the message to stay
3262
3263
  # faithful to the original "already exists" contract across versions.
3263
3264
  try:
3264
- record = await client.create(record_id, _encoding.encode(data))
3265
+ record = await client.create(record_id, payload)
3265
3266
  except ServerError as e:
3266
3267
  if "already exists" in str(e).lower():
3267
3268
  raise SurrealDbError(f"There was a problem with the database: {e}") from e
@@ -3274,7 +3275,7 @@ class BaseSurrealModel(BaseModel):
3274
3275
  return self, True
3275
3276
 
3276
3277
  # Auto-generate the ID
3277
- record = await client.create(table, _encoding.encode(data)) # pragma: no cover
3278
+ record = await client.create(table, payload) # pragma: no cover
3278
3279
 
3279
3280
  if isinstance(record, list):
3280
3281
  raise SurrealDbError("Can't save data, multiple records returned.") # pragma: no cover
@@ -3353,9 +3354,10 @@ class BaseSurrealModel(BaseModel):
3353
3354
  self._apply_record(rows) # interactive: applies; buffered: None → stale until commit
3354
3355
  return self, True
3355
3356
 
3357
+ encoded = _encoding.encode(variables) # issue #325: refused before any client is asked for
3356
3358
  client = await type(self)._connection_manager().get_client()
3357
3359
  try:
3358
- rows = await client.query(statement, _encoding.encode(variables))
3360
+ rows = await client.query(statement, encoded)
3359
3361
  except ServerError as e:
3360
3362
  # Same normalisation as the native path: "already exists" is an ORM error.
3361
3363
  if "already exists" in str(e).lower():
@@ -3576,9 +3578,10 @@ class BaseSurrealModel(BaseModel):
3576
3578
  DB lines. That holds under ``refresh=False`` too: the server raises for a missing table
3577
3579
  whatever the statement asks back.
3578
3580
  """
3581
+ encoded = _encoding.encode(variables) # issue #325: refused before any client is asked for
3579
3582
  client = await type(self)._connection_manager().get_client()
3580
3583
  try:
3581
- rows = await client.query(statement, _encoding.encode(variables))
3584
+ rows = await client.query(statement, encoded)
3582
3585
  except NotFoundError as e:
3583
3586
  raise SurrealDbError("Can't merge data, no record found.") from e
3584
3587
  self._sync_after_merge(rows, refresh, data, server_values)
@@ -3595,9 +3598,10 @@ class BaseSurrealModel(BaseModel):
3595
3598
  statement = "UPDATE $rid MERGE $data RETURN NONE;"
3596
3599
  await self._run_update(statement, {"rid": record_id, "data": wire_data}, False, data, {})
3597
3600
  return
3601
+ encoded = _encoding.encode(wire_data) # issue #325: refused before any client is asked for
3598
3602
  client = await type(self)._connection_manager().get_client()
3599
3603
  try:
3600
- row = await client.merge(record_id, _encoding.encode(wire_data))
3604
+ row = await client.merge(record_id, encoded)
3601
3605
  except NotFoundError as e:
3602
3606
  raise SurrealDbError("Can't merge data, no record found.") from e
3603
3607
  self._sync_after_merge(row, True, data, {})
@@ -3671,8 +3675,9 @@ class BaseSurrealModel(BaseModel):
3671
3675
  self._apply_record(after if after is not None else rows)
3672
3676
  return self, before is None
3673
3677
 
3678
+ encoded = _encoding.encode(variables) # issue #325: refused before any client is asked for
3674
3679
  client = await type(self)._connection_manager().get_client()
3675
- rows = await client.query(statement, _encoding.encode(variables))
3680
+ rows = await client.query(statement, encoded)
3676
3681
  before, after = self._split_upsert_result(rows)
3677
3682
  self._apply_record(after if after is not None else rows)
3678
3683
  return self, before is None
@@ -3802,34 +3807,34 @@ class BaseSurrealModel(BaseModel):
3802
3807
  tx.enqueue_post_commit(lambda: post_update.send(sender, instance=self, update_fields=update_fields))
3803
3808
  return None
3804
3809
 
3805
- client = await type(self)._connection_manager().get_client()
3806
-
3807
3810
  if not has_signals:
3808
- return await self._replace_direct(client, record_id, data, content, bound)
3811
+ return await self._replace_direct(record_id, data, content, bound)
3809
3812
 
3810
3813
  update_fields = self._py_fields(data)
3811
3814
  await pre_update.send(sender, instance=self, update_fields=update_fields)
3812
3815
 
3813
3816
  async with around_update.wrap(sender, instance=self, update_fields=update_fields):
3814
- result = await self._replace_direct(client, record_id, data, content, bound)
3817
+ result = await self._replace_direct(record_id, data, content, bound)
3815
3818
 
3816
3819
  await post_update.send(sender, instance=self, update_fields=update_fields)
3817
3820
 
3818
3821
  return result
3819
3822
 
3820
- @staticmethod
3821
- async def _replace_direct(
3822
- client: Any, record_id: RecordID, data: dict[str, Any], content: str, bound: dict[str, Any]
3823
- ) -> Any:
3823
+ async def _replace_direct(self, record_id: RecordID, data: dict[str, Any], content: str, bound: dict[str, Any]) -> Any:
3824
3824
  """Run ``update()`` outside a transaction, ``content`` and ``bound`` being :func:`replace_content` of ``data``.
3825
3825
 
3826
3826
  A payload without a ``datetime`` to keep goes through the SDK's ``update()``, as before #261. Otherwise the compiled
3827
3827
  ``UPDATE $rid CONTENT …`` goes through ``client.query()``, and its single row is unwrapped as the SDK's
3828
- ``update()`` unwraps it, so ``update()`` returns the same thing either way.
3828
+ ``update()`` unwraps it, so ``update()`` returns the same thing either way. The values are encoded before the
3829
+ client is asked for (issue #325): a value the ORM cannot send is refused before the write reaches the database.
3829
3830
  """
3830
3831
  if content == PLAIN_CONTENT:
3831
- return await client.update(record_id, _encoding.encode(data))
3832
- rows = await client.query(f"UPDATE $rid CONTENT {content};", _encoding.encode({"rid": record_id, **bound}))
3832
+ encoded = _encoding.encode(data)
3833
+ client = await type(self)._connection_manager().get_client()
3834
+ return await client.update(record_id, encoded)
3835
+ encoded = _encoding.encode({"rid": record_id, **bound})
3836
+ client = await type(self)._connection_manager().get_client()
3837
+ rows = await client.query(f"UPDATE $rid CONTENT {content};", encoded)
3833
3838
  return rows[0] if isinstance(rows, list) and len(rows) == 1 else rows
3834
3839
 
3835
3840
  async def _merge_server(
@@ -4014,8 +4019,9 @@ class BaseSurrealModel(BaseModel):
4014
4019
  rows = await tx.add("UPDATE $rid PATCH $data;", {"rid": record_id, "data": operations})
4015
4020
  self._apply_record(rows) # interactive: applies; buffered: add() returns None → no-op (stale)
4016
4021
  return self
4022
+ encoded = _encoding.encode(operations) # issue #325: refused before any client is asked for
4017
4023
  client = await type(self)._connection_manager().get_client()
4018
- record = await client.patch(record_id, _encoding.encode(operations))
4024
+ record = await client.patch(record_id, encoded)
4019
4025
  self._apply_record(record)
4020
4026
  return self
4021
4027
 
@@ -4040,8 +4046,9 @@ class BaseSurrealModel(BaseModel):
4040
4046
  rows = await tx.add(statement, vars_)
4041
4047
  self._apply_record(rows)
4042
4048
  return self
4049
+ encoded = _encoding.encode(vars_) # issue #325: refused before any client is asked for
4043
4050
  client = await type(self)._connection_manager().get_client()
4044
- rows = await client.query(statement, _encoding.encode(vars_))
4051
+ rows = await client.query(statement, encoded)
4045
4052
  self._apply_record(rows)
4046
4053
  return self
4047
4054
 
@@ -4504,9 +4511,10 @@ class BaseSurrealModel(BaseModel):
4504
4511
  rows = await tx.add(query, variables)
4505
4512
  return rows if isinstance(rows, list) else []
4506
4513
 
4514
+ encoded = _encoding.encode(variables) # issue #325: refused before any client is asked for
4507
4515
  client = await type(self)._connection_manager().get_client()
4508
4516
  try:
4509
- result = await client.query(query, _encoding.encode(variables))
4517
+ result = await client.query(query, encoded)
4510
4518
  except ServerError as exc:
4511
4519
  # The rule of every edge creation (v0.33.0): the ORM's error, the SDK's as its cause.
4512
4520
  raise edge_write_error(exc) from exc
@@ -4601,9 +4609,10 @@ class BaseSurrealModel(BaseModel):
4601
4609
  if tx is not None:
4602
4610
  await tx.add(statement, variables)
4603
4611
  return
4612
+ encoded = _encoding.encode(variables) # issue #325: refused before any client is asked for
4604
4613
  client = await cls._connection_manager().get_client()
4605
4614
  with contextlib.suppress(NotFoundError):
4606
- await client.query(statement, _encoding.encode(variables))
4615
+ await client.query(statement, encoded)
4607
4616
 
4608
4617
  @_cache.invalidates("edge", refuse=_write_refusals("remove_relation()", view=False))
4609
4618
  async def remove_relation(
@@ -1787,9 +1787,10 @@ class QuerySet:
1787
1787
  self._tx._note_failure(refusal)
1788
1788
  raise refusal from exc
1789
1789
  raise
1790
+ encoded = _encoding.encode(vars_) # issue #325: refused before any client is asked for
1790
1791
  client = await self._manager().get_client()
1791
1792
  try:
1792
- return await client.query(query, _encoding.encode(vars_)) # type: ignore
1793
+ return await client.query(query, encoded) # type: ignore
1793
1794
  except ServerError as exc:
1794
1795
  if await self._reads_as_empty(exc, subquery_tables):
1795
1796
  return []
@@ -2159,14 +2160,15 @@ class QuerySet:
2159
2160
  counted from 1, and the records come back best first; equal scores keep the vector list's order first, then
2160
2161
  the full-text list's for the records it alone found. SurrealDB 3.x fuses the lists with its ``search::rrf()``;
2161
2162
  SurrealDB 2.x and the embedded engine have no such function, so the ORM fuses them with the same formula: the
2162
- records, scores and order are the same on every line. The vector and the text are bound as query variables,
2163
- never written into the statement.
2163
+ same two lists give the same records, scores and order on every line. Each list is SurrealDB's own, so the
2164
+ lists themselves can differ between lines: the HNSW search is approximate, and the full-text list follows the
2165
+ line's BM25 scores (a term found in more than half the documents scores ``0.0`` on SurrealDB 3.x and below
2166
+ zero on 2.x and the embedded engine, README section 36). The vector and the text are bound as query
2167
+ variables, never written into the statement.
2164
2168
 
2165
2169
  Each record is a dict — the full SurrealDB-ORM's result: its fields keyed by their Python names and
2166
2170
  ``_rrf_score``, plus ``_knn_distance`` (its distance, ``None`` when only the full-text search found it) and
2167
- ``_search_score`` (its BM25 score, ``None`` when only the vector search found it). An exact scan (``dist=``)
2168
- gives identical calls one vector list on every line: records at an equal distance at the ``vector_limit``-th
2169
- place are kept by id on SurrealDB 2.x and the embedded engine, as ``similar_to(dist=...)`` keeps them.
2171
+ ``_search_score`` (its BM25 score, ``None`` when only the vector search found it).
2170
2172
 
2171
2173
  Each search needs its index. Without a full-text index on ``text_field``, SurrealDB 3.3, 2.x and the embedded
2172
2174
  engine refuse the search (``SurrealDbError`` naming the field), while SurrealDB 3.1 and 3.2 match nothing.
@@ -2197,7 +2199,10 @@ class QuerySet:
2197
2199
  ef: The HNSW search's candidate list: ``None`` (100) or an ``int`` from 1 to 10000, raised to
2198
2200
  ``vector_limit``.
2199
2201
  dist: An exact scan by this distance instead of the index's search: ``EUCLIDEAN``, ``COSINE``,
2200
- ``MANHATTAN``, ``CHEBYSHEV`` or ``HAMMING``, in any case; not with ``ef``.
2202
+ ``MANHATTAN``, ``CHEBYSHEV`` or ``HAMMING``, in any case; not with ``ef``. SurrealDB 2.x's and the
2203
+ embedded engine's own scan picks among records at an equal distance at the ``vector_limit``-th place
2204
+ in no fixed order, so there the ORM ranks it by distance, then id, as ``similar_to(dist=...)`` does:
2205
+ the tied records are kept by id, and identical calls get one vector list on every line.
2201
2206
 
2202
2207
  Returns:
2203
2208
  list[dict[str, Any]]: The fused records, best first, each a dict of its fields and ``_rrf_score``,
@@ -2859,8 +2864,9 @@ class QuerySet:
2859
2864
  return self.model.from_db(rows) # type: ignore
2860
2865
  return models # buffered: not executed until commit; return inputs
2861
2866
 
2867
+ encoded = _encoding.encode(data_list) # issue #325: refused before any client is asked for
2862
2868
  client = await self._manager().get_client()
2863
- results = await client.insert(self._model_table, _encoding.encode(data_list))
2869
+ results = await client.insert(self._model_table, encoded)
2864
2870
 
2865
2871
  if isinstance(results, list):
2866
2872
  return self.model.from_db(results) # type: ignore
@@ -30,6 +30,11 @@ Records written (issue #304): an ORM write of records that joins a transaction a
30
30
  for the cache only. ``define_indexes(tx=…)`` reads them (``_records_written``): SurrealDB servers do not index the
31
31
  records a transaction wrote before the index was defined. A raw ``tx.add()`` is not noted.
32
32
 
33
+ Refused writes (issue #325): each note is counted per write, so that a write that raises before it reached the
34
+ database takes back its own notes (``_withdraw_write``) and leaves those of every other write. ``add()``, an
35
+ interactive ``run_read()`` and the commits mark the writes in progress as reached (``cache.reaching()``) before they
36
+ queue or send anything.
37
+
33
38
  Indexes removed (issue #312): ``remove_index(tx=…)`` notes the index it removes, by table (``_note_index_removal``).
34
39
  ``define_indexes(tx=…)`` reads committed state, where that index still stands: it counts the indexes noted for its table
35
40
  (``_indexes_removed``) as missing, plans them again, and forgets those it defines (``_forget_index_removals``, through
@@ -98,6 +103,16 @@ _MISSING_INDEX_EXPRESSION = re.compile(r"no suitable index supporting the expres
98
103
  _Locate = Callable[[int, int], tuple[int, int, int, int] | None]
99
104
 
100
105
 
106
+ def _count(counts: dict[str, int], tables: Iterable[str], step: int) -> None:
107
+ """Add *step* to the count of each of *tables* (each once); a count that reaches 0 is removed (issue #325)."""
108
+ for table in set(tables):
109
+ count = counts.get(table, 0) + step
110
+ if count > 0:
111
+ counts[table] = count
112
+ else:
113
+ counts.pop(table, None)
114
+
115
+
101
116
  def _is_pure_filler(result: Any) -> bool:
102
117
  """True if a statement's message is ONLY the generic 'not executed' filler.
103
118
 
@@ -248,13 +263,15 @@ class Transaction(ABC):
248
263
 
249
264
  def __init__(self) -> None:
250
265
  self._post_commit: list[Callable[[], Awaitable[None]]] = []
251
- # Query cache: the tables written in this transaction, invalidated at commit.
252
- self._cache_tables: set[str] = set()
253
- self._cache_all = False
266
+ # Query cache: the tables written in this transaction, invalidated at commit — each with the number of writes
267
+ # that noted it, and the number of writes that noted every table (issue #325: a refused write takes back its
268
+ # own note only).
269
+ self._cache_tables: dict[str, int] = {}
270
+ self._cache_all = 0
254
271
  # Issue #304: the tables an ORM write of records changed in this transaction (definitions excluded), kept
255
- # until the transaction ends.
256
- self._record_tables: set[str] = set()
257
- self._record_all = False
272
+ # until the transaction ends; counted as the query cache's.
273
+ self._record_tables: dict[str, int] = {}
274
+ self._record_all = 0
258
275
  # Issue #312: the indexes remove_index(tx=…) removed in this transaction, by table, until define_indexes(tx=…)
259
276
  # defines them again; kept until the transaction ends.
260
277
  self._removed_indexes: dict[str, set[str]] = {}
@@ -293,9 +310,9 @@ class Transaction(ABC):
293
310
  invalidates the edge reads at commit).
294
311
  """
295
312
  if tables is None:
296
- self._cache_all = True
313
+ self._cache_all += 1
297
314
  else:
298
- self._cache_tables |= set(tables)
315
+ _count(self._cache_tables, tables, 1)
299
316
 
300
317
  def _cache_written(self) -> frozenset[str] | None:
301
318
  """The tables noted so far: ``None`` when a write noted every table."""
@@ -304,7 +321,7 @@ class Transaction(ABC):
304
321
  def _forget_cache_writes(self) -> None:
305
322
  """Clear the tables noted (after a commit, or on cancel without invalidating)."""
306
323
  self._cache_tables.clear()
307
- self._cache_all = False
324
+ self._cache_all = 0
308
325
 
309
326
  def _note_record_write(self, tables: Iterable[str] | None) -> None:
310
327
  """Note the tables an ORM write of records in this transaction changes (``None``: every table) — issue #304.
@@ -314,18 +331,36 @@ class Transaction(ABC):
314
331
  refuse_args=…)``: a write refused for a materialized view, a snapshot or SG1, #315, or for a snapshot in
315
332
  ``bulk_create()``'s list, a missing id or another argument it checks, #320, notes nothing) — never for a
316
333
  definition (``define_table()``, ``remove_index()``…), whose table is noted for the query cache only. Unlike
317
- the query cache's tables, the commit and the cancel keep them.
334
+ the query cache's tables, the commit and the cancel keep them. A write that raises before it reached the
335
+ database takes them back (:meth:`_withdraw_write`, issue #325).
318
336
  """
319
337
  if tables is None:
320
- self._record_all = True
338
+ self._record_all += 1
321
339
  else:
322
- self._record_tables |= set(tables)
340
+ _count(self._record_tables, tables, 1)
323
341
 
324
342
  def _records_written(self) -> frozenset[str] | None:
325
343
  """The tables an ORM write of records changed so far in this transaction (issue #304): ``None`` when one noted
326
344
  every table. ``define_indexes(tx=…)`` reads it; a raw ``tx.add()`` is not counted."""
327
345
  return None if self._record_all else frozenset(self._record_tables)
328
346
 
347
+ def _withdraw_write(self, tables: Iterable[str] | None, *, records: bool) -> None:
348
+ """Take back the notes of one ORM write that raised before it reached the database (issue #325).
349
+
350
+ ``cache.writing()`` calls it with what that write noted: *tables* (``None``: every table) for the query cache
351
+ and, with *records*, as written with records. Each note is counted per write, so the notes of every other
352
+ write stay, a concurrent or an enclosing one on the same tables included. Never below nothing: a note the
353
+ commit or the cancel already forgot is not taken from a later write.
354
+ """
355
+ if tables is None:
356
+ self._cache_all = max(0, self._cache_all - 1)
357
+ if records:
358
+ self._record_all = max(0, self._record_all - 1)
359
+ return
360
+ _count(self._cache_tables, tables, -1)
361
+ if records:
362
+ _count(self._record_tables, tables, -1)
363
+
329
364
  def _note_index_removal(self, table: str, name: str) -> None:
330
365
  """Note that the index *name* of *table* was removed in this transaction — issue #312.
331
366
 
@@ -499,6 +534,7 @@ class BufferedTransaction(Transaction):
499
534
  position the server reports at commit is given in the caller's text (issue #278).
500
535
  """
501
536
  variables = _encoding.encode(variables)
537
+ _cache.reaching() # issue #325: past every refusal, the statement joins the transaction
502
538
  prefix = f"t{self._counter}_"
503
539
  renamed = statement
504
540
  inserted: list[int] = []
@@ -578,8 +614,11 @@ class BufferedTransaction(Transaction):
578
614
  return
579
615
  # query_raw (NOT query): query() returns None on a failed tx; query_raw gives
580
616
  # per-statement status for raise_for_status.
617
+ query = self.build_query()
618
+ variables = _encoding.encode(self.variables)
619
+ _cache.reaching() # issue #325: from here, the commit's outcome is unknown
581
620
  try:
582
- raw = await self._client.query_raw(self.build_query(), _encoding.encode(self.variables))
621
+ raw = await self._client.query_raw(query, variables)
583
622
  except RuntimeError as exc:
584
623
  # The embedded engine raises a bare RuntimeError for a query it refuses as a whole (issue
585
624
  # #278): the same error as a server's envelope, the engine's error kept as the suppressed
@@ -631,6 +670,7 @@ class InteractiveTransaction(Transaction):
631
670
  A failure is recorded before it raises: the transaction will not commit (issue #268).
632
671
  """
633
672
  payload = _encoding.encode(variables or {})
673
+ _cache.reaching() # issue #325: the statement is sent
634
674
  try:
635
675
  try:
636
676
  raw = await self._client.query_raw(statement, payload, txn_id=self._txn_id)
@@ -650,6 +690,7 @@ class InteractiveTransaction(Transaction):
650
690
  error as an answer (:meth:`_absorb_failure`).
651
691
  """
652
692
  payload = _encoding.encode(variables or {})
693
+ _cache.reaching() # issue #325: the statement is sent
653
694
  try:
654
695
  try:
655
696
  return await self._client.query(statement, payload, txn_id=self._txn_id)
@@ -680,6 +721,7 @@ class InteractiveTransaction(Transaction):
680
721
  # or raises (a failed commit's state is unknown).
681
722
  try:
682
723
  async with _cache.writing(self._cache_written()):
724
+ _cache.reaching() # issue #325: from here, the commit's outcome is unknown
683
725
  try:
684
726
  await self._client.commit(self._txn_id)
685
727
  except Exception as exc: