surreal-orm-lite 0.27.0__tar.gz → 0.28.1__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 (40) hide show
  1. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/CHANGELOG.md +197 -0
  2. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/PKG-INFO +322 -20
  3. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/README.md +321 -19
  4. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/__init__.py +4 -1
  6. surreal_orm_lite-0.28.1/src/surreal_orm_lite/cache.py +813 -0
  7. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/connection_manager.py +25 -3
  8. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/constants.py +7 -0
  9. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/edge.py +2 -0
  10. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/functions.py +16 -7
  11. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/model_auth.py +3 -0
  12. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/model_base.py +19 -0
  13. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/query_set.py +462 -50
  14. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/subquery.py +19 -5
  15. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/surql_literal.py +9 -6
  16. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/transaction.py +57 -11
  17. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/utils.py +180 -35
  18. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/.gitignore +0 -0
  19. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/LICENSE +0 -0
  20. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/Makefile +0 -0
  21. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/_sdk.py +0 -0
  22. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/aggregations.py +0 -0
  23. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/auth.py +0 -0
  24. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/changefeed.py +0 -0
  25. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/concurrency.py +0 -0
  26. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/decoding.py +0 -0
  27. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/embedded.py +0 -0
  28. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/encoding.py +0 -0
  29. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/enum.py +0 -0
  30. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/exceptions.py +0 -0
  31. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/geo.py +0 -0
  32. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/live.py +0 -0
  33. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/py.typed +0 -0
  34. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/q.py +0 -0
  35. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/signals.py +0 -0
  36. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
  37. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/database.py +0 -0
  38. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  39. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/time_travel.py +0 -0
  40. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/types.py +0 -0
@@ -5,6 +5,203 @@ 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.28.1] - 2026-10-17
9
+
10
+ Query building checks what it is given: `select()` accepts field names and paths, `limit()` and
11
+ `offset()` take a non-negative integer, and a string filter value is always data, with `Var()` as
12
+ the only variable reference. No new public API.
13
+
14
+ ### Changed
15
+
16
+ - **A string filter value is data, whatever its first character** (#250), on every filter path:
17
+ `filter()`, `Q`, `get()`, `first()`, `count()`, `exists()`, `get_or_create()`,
18
+ `update_or_create()`, `bulk_update()` by filter, `cache()`, subqueries and live queries.
19
+ `filter(name="$admin")` compares `name` with the string `"$admin"`, bound like any other value.
20
+ `Var("name")` is the only reference to a query variable, whose value `variables()` gives.
21
+ Migration: where a filter uses the `"$name"` form (deprecated since v0.14.3), write
22
+ `Var("name")`. When a string filter value is exactly `$` followed by the name of a variable of
23
+ `variables()` or of a session parameter (`$access`, `$auth`, `$session`, `$token`), a
24
+ `UserWarning` names the `Var(...)` to write, once per read, pointing at the caller's line; the
25
+ value stays data. Any other string, such as `"$x"` with no variable `x`, is data and nothing
26
+ warns.
27
+
28
+ ```python
29
+ from surreal_orm_lite import Var
30
+
31
+ await User.objects().filter(name="$admin").exec() # the string "$admin"
32
+ await User.objects().filter(age__gte=Var("min_age")).variables(min_age=21).exec() # $min_age
33
+ await Doc.objects().filter(owner=Var("auth")).exec() # SurrealDB's $auth
34
+ ```
35
+
36
+ - **The `"$$"` escape keeps its meaning and is deprecated** (#250): a string filter value starting
37
+ with `$$` loses one `$` (`"$$admin"` finds `"$admin"`) and emits a `DeprecationWarning`; write
38
+ the value with one `$` less. An item of an `in` list never had the escape and is unchanged.
39
+ - **`variables()` refuses `access`, `auth`, `session` and `token`** with a `ValueError` (#250):
40
+ SurrealDB sets these parameters for each session and refuses a query variable of that name. To
41
+ pass your own value, give it another name or put the value itself in the filter:
42
+ `filter(token=Var("device_token")).variables(device_token=t)` or `filter(token=t)`.
43
+ `Var("token")` without `variables()` reads SurrealDB's `$token`, and likewise for the three
44
+ others, in reads and in live queries.
45
+ - **`get_or_create()` and `update_or_create()`** raise `SurrealDbError` before any request when a
46
+ scalar string criterion is exactly `$` followed by the name of a variable of `variables()` or of
47
+ a session parameter, whatever its lookup (#250): pass the actual value as the criterion (the
48
+ record id, or the value itself). Any other `"$name"` string is looked up and written as it is.
49
+ `Var("auth")` finds the signed-in user's record but cannot be written: with no record to return,
50
+ it raises `SurrealDbError`.
51
+ - **`select()` checks its items** like `order_by()` and `values()` (#247): each item is `"*"`, a
52
+ field name (an aliased field by its Python name), a dotted path into a nested object or through a
53
+ record link, or such a path followed by `.*` (`"author.*"`). Anything else raises `ValueError`
54
+ naming the item when `select()` is called, before any request, and the selection in place is
55
+ kept; an item that is not a `str` raises `TypeError`. Write a computed projection with `query()`
56
+ and bound parameters.
57
+ - **`limit()` and `offset()` take a non-negative integer** (#249) of any type with `__index__`
58
+ (an `IntEnum` member, NumPy's `int64`; the parameter is annotated `SupportsIndex`), up to
59
+ `2**63 - 1`. A `bool`, `str`, `float` or `None` raises `TypeError`, a negative value or one above
60
+ `2**63 - 1` `ValueError`, naming the method and the value, when the method is called (for a
61
+ subquery's `limit()` and `offset()` too), before any request; the value in place is kept.
62
+ SurrealDB 2.x and the embedded engine refuse a value above `2**32 - 1` when the read runs;
63
+ SurrealDB 3.x reads it.
64
+ - **Live queries**: `Var("scope")` takes its value from `variables(scope=...)` like any other name
65
+ and raises `SurrealDbError` without it (#250). `$access`, `$auth`, `$session`, `$token`, `$this`
66
+ and `$parent` stay references the server reads on every notification.
67
+
68
+ ### Fixed
69
+
70
+ - On an edge's `in` and `out`, which hold record ids, a string that is `$` followed by the name of
71
+ a variable of `variables()` or of a session parameter raises a `ValueError` whose message names
72
+ the `Var(...)` to write (#250).
73
+ - Each warning of a filter value is emitted once per read: the second compilation of a `cache()`
74
+ miss and the re-send of a subquery over a missing table stay quiet, for the `"$$"`
75
+ `DeprecationWarning` too (#250).
76
+
77
+ ### Removed
78
+
79
+ - `utils.remove_quotes_for_variables()` and `utils.VALID_VARIABLE_REF_PATTERN`, internal helpers
80
+ that were never in `__all__`.
81
+
82
+ ### Notes
83
+
84
+ - **SurrealDB 2.x vs 3.x**: string filter values and `Var()` behave the same on both lines and on
85
+ the embedded engine. `select("meta.*")` on a nested object that is not a record link gives the
86
+ object on 3.x and its values as a list on 2.x and the embedded engine (through a link, the linked
87
+ record on both). A `limit()` or `offset()` above `2**32 - 1` is refused by SurrealDB 2.x and the
88
+ embedded engine when the read runs, and read by 3.x.
89
+ - **Docs**: the README section "String filter values and `Var()`" replaces "Filter values that
90
+ start with `$`"; new parts "What `select()` accepts" and "`limit()` and `offset()`"; the
91
+ live-query, subquery and query-cache invalidation notes match; three rows in the 2.x/3.x behaviour
92
+ table (string filter values, a nested object's `.*`, `LIMIT`/`START` above `2**32 - 1`). The
93
+ `getting_started` notebook reads `SURREALDB_HOST` and `SURREALDB_PORT`; the v0.14.3 notebook says
94
+ the `"$$"` escape is deprecated since v0.28.1.
95
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, and on the embedded engine,
96
+ plus 3.1.5 for backward compatibility (identical).
97
+
98
+ ## [0.28.0] - 2026-10-17
99
+
100
+ Query cache: a QuerySet serves its reads from a client-side cache with `cache(ttl)`, and every ORM
101
+ write removes the cached reads it can change, with nothing to set up. The sixth minor of Tier 2.
102
+
103
+ ### Added
104
+
105
+ - **`QuerySet.cache(ttl=None)`** and **`QueryCache`**, exported from `surreal_orm_lite` (the full
106
+ SurrealDB-ORM's names). The rows a cached read returned stay in this process's memory, and the
107
+ same read is answered from there, without a request, until its TTL runs out or an ORM write
108
+ changes what it reads.
109
+
110
+ ```python
111
+ from surreal_orm_lite import QueryCache
112
+
113
+ books = await Product.objects().filter(category="book").cache(ttl=30).exec() # the database answers
114
+ again = await Product.objects().filter(category="book").cache(ttl=30).exec() # the cache answers
115
+ await Product(id="p4", name="Atlas", category="book", price=40).save() # removes Product's cached reads
116
+ fresh = await Product.objects().filter(category="book").cache(ttl=30).exec() # the database answers
117
+ QueryCache.stats()["hits"] # 1
118
+ ```
119
+
120
+ - **Every read of a cached queryset**: `exec()`, `first()`, `get()` by filters or by id, `all()`,
121
+ `count()`, `sum()`, `avg()`, `min()`, `max()`, `exists()`, `values(…).annotate(…)` and
122
+ `annotate(GeoDistance)`. A read is a hit when an earlier read sent the same statement with the
123
+ same variables, on the same connection and with the same identity, within the TTL. Rows are
124
+ cached, not instances: each hit builds new instances from a copy. Empty results are cached
125
+ (`get(<id>)` of a missing record raises `SurrealDbNotFoundError` on the hit too); errors never
126
+ are. An internal failure of the cache never fails a read: the read goes to the database.
127
+ - **Time to live**: seconds (`int` or `float`) or a `timedelta`, the oldest result the read
128
+ accepts; `cache()` without a TTL uses `QueryCache`'s default (60 s unless configured); `0` means
129
+ never cached.
130
+ - **Built-in invalidation**: every ORM write removes the cached reads of the tables it writes,
131
+ before its `post_*` signals fire — `save()`, `update()`, `merge()`, `upsert()`, `patch()`,
132
+ `delete()`, the atomic operations, `relate()` and the `remove_*()` helpers, a typed edge's
133
+ `save()`, `bulk_create()`, `bulk_update()`, `bulk_delete()`, `QuerySet.patch()`,
134
+ `delete_table()`, `get_or_create()`/`update_or_create()` when they write, `signup()`,
135
+ `define_computed_fields()` and `define_access()`. Reads whose subqueries read those tables go
136
+ too; a read that follows links (`fetch()`, a dotted path, a `select()` item that is not a plain
137
+ field) is removed by any ORM write, and a read of an edge model by any delete. Inside
138
+ `transaction()` the written tables are invalidated at commit (a failed commit too, nothing on
139
+ rollback). While a write runs, reads of its tables go to the database and store nothing.
140
+ - **One cache scope per connection and identity**: a sign-in, a sign-up, `authenticate()` or
141
+ `invalidate()` starts a new scope and drops the previous identity's results; another event loop's
142
+ connection, a reconnect and an `embedded_database()` block start empty; closing a connection
143
+ drops its results. Cached results never cross identities.
144
+ - **`QueryCache`**: `configure(default_ttl=60, max_size=1000, enabled=True)` sets all three
145
+ settings at every call, as in the full ORM, and never clears; `enabled=False` hides the entries
146
+ (`cache()` reads go to the database and calling `cache()` logs a warning). Past `max_size` the
147
+ least recently used entry is evicted. `invalidate()` takes a model class or a table name and
148
+ returns how many entries it removed; `clear()` drops every entry and resets the counters;
149
+ `stats()` returns `entries`, `tables`, `max_size`, `default_ttl`, `enabled`, `hits` and
150
+ `misses`. `make_key()`, `get()` and `set()` cache your own results (of `raw_query()`, say),
151
+ tagged with a table so that an ORM write to it removes them; `get()` misses while such a write
152
+ runs.
153
+ - **Refusals**: `query()` raises `SurrealDbError` on a queryset with `cache()`; `live()`, `watch()`
154
+ and `changes()` name `cache()` among the clauses their usual error refuses; combining `cache()`
155
+ with `as_of()` raises `SurrealDbError`, in either order. A negative or non-finite TTL raises
156
+ `ValueError`, anything but a number or a `timedelta` (`True` included) `TypeError`.
157
+ - README section 29, "Query cache (`cache()`, `QueryCache`)" (what is cached, the time to live,
158
+ invalidation and what the cache cannot see, one cache per connection and identity,
159
+ configuration and statistics, a note for users of the full SurrealDB-ORM), a features row, a
160
+ row in the 2.x/3.x behaviour table, the comparison and roadmap rows, and the example notebook
161
+ `examples/v0.28.0_query_cache.ipynb`.
162
+
163
+ ### Changed
164
+
165
+ - ORM writes now also remove the cached reads they can change, in memory, without a request.
166
+ Without `cache()`, every read and write sends the same requests as in v0.27.x; the texts of the
167
+ `live()`, `watch()` and `changes()` refusals are unchanged.
168
+
169
+ ### Notes
170
+
171
+ - **Same on SurrealDB 2.x and 3.x**, and on the embedded engine. Reads inside a transaction
172
+ (`objects(tx=)`) are never cached: on 3.x an interactive transaction's reads see its uncommitted
173
+ writes, and on 2.x a buffered transaction cannot read.
174
+ - **What the cache cannot see** (the TTL bounds it; `QueryCache.invalidate(Model)` removes a
175
+ table's entries after such a change): writes by another process or client; raw SurrealQL
176
+ (`raw_query()`, `QuerySet.query()`, `call_function()`, `Transaction.add()`); a write whose task
177
+ is cancelled, or that fails client-side, after its request was sent; writes made by an access
178
+ method's own `SIGNIN`/`SIGNUP` clauses beyond the record they create; what the server derives on
179
+ its own (`DEFINE EVENT`, `REFERENCE … ON DELETE` on 3.x, views, `PERMISSIONS` that read another
180
+ table); values computed when the read runs (a `DEFINE PARAM` read with `Var()`,
181
+ `<future>`/`COMPUTED` fields, time functions in a `select()` expression); a table of relations
182
+ read through a model that is not a `BaseSurrealEdge`. A session changed behind the ORM's back
183
+ (`raw_query("USE …")`, `signin()` or `use()` on the SDK client) is not seen either: call
184
+ `QueryCache.clear()` after it.
185
+ - **Memory**: cached rows stay in this process's memory until they expire, are evicted,
186
+ invalidated or cleared, or their connection closes. `configure(enabled=False)` only hides them;
187
+ `QueryCache.clear()` drops them. Entries stored with `QueryCache.set()` are not scoped to a
188
+ connection or an identity: put whatever tells your callers apart in the key.
189
+ - **Keys** are the SHA-256 of the CBOR bytes the official SDK sends, with the keys of mappings
190
+ sorted: `RecordID("user", 1)` and `"user:1"` never share an entry. An SDK that exposes no CBOR
191
+ encoder sends every `cache()` read to the database (one warning per process).
192
+ - Concurrent misses of the same read each send their own request.
193
+ - **Differences from the full SurrealDB-ORM**: every read is cached, not only `exec()`, `first()`
194
+ and `get()` by filters; invalidation is built in and covers bulk operations, `QuerySet.patch()`,
195
+ the atomic operations, relations and transactions, where the full ORM listens to `post_save`,
196
+ `post_update` and `post_delete`; rows are cached instead of instances; one scope per connection
197
+ and identity; `live()`, `watch()`, `changes()` and `query()` refuse `cache()`; the TTL may be a
198
+ `float` or a `timedelta` and negative values are refused; LRU eviction instead of FIFO;
199
+ `invalidate()` takes a table name too; `stats()` adds `hits` and `misses`.
200
+ - Not available yet: invalidation from other processes or clients (through live queries),
201
+ caching `as_of()` reads, sharing cached results between event loops.
202
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, and on the embedded engine,
203
+ plus 3.1.5 for backward compatibility (identical).
204
+
8
205
  ## [0.27.0] - 2026-10-16
9
206
 
10
207
  Subqueries: a QuerySet filters another, as `Subquery(qs)` or the queryset itself, compiled to a
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.27.0
3
+ Version: 0.28.1
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
@@ -180,6 +180,43 @@ results = await User.objects().query(
180
180
  )
181
181
  ```
182
182
 
183
+ #### What `select()` accepts
184
+
185
+ ```python
186
+ await Book.objects().select("title", "price").exec() # field names
187
+ await Book.objects().select("title", "author.name").exec() # [{"title": "Dune", "author": {"name": "Ada"}}, …]
188
+ await Book.objects().select("title", "author.*").exec() # every field of the linked author
189
+ await Book.objects().select("*", "author.*").exec() # every field, the author's record included
190
+ ```
191
+
192
+ Each item is `*`, a field name (an aliased field by its Python name: its column is selected), a
193
+ dotted path into a nested object or through a record link, or such a path followed by `.*`. Names
194
+ are letters, digits and underscores, each part starting with a letter or an underscore, as in
195
+ `order_by()` and `values()`. Anything else — an expression, a function call, `AS`, `{…}` or
196
+ `[…]` — raises `ValueError` naming the item when `select()` is called, before any request; write a
197
+ computed projection with `query()` and bound parameters. Rows that do not validate as the model (a
198
+ link read as a record, a required field left out) come back as dicts keyed by Python names. On a
199
+ nested object that is not a link, `"meta.*"` gives the object on SurrealDB 3.x and its values as a
200
+ list on 2.x and the embedded engine.
201
+
202
+ #### `limit()` and `offset()`
203
+
204
+ ```python
205
+ users = await User.objects().order_by("name").limit(10).offset(20).exec()
206
+ User.objects().limit(int(size)) # a size read as text: convert it first
207
+ User.objects().limit("10") # TypeError: limit() takes a non-negative integer, got '10'
208
+ User.objects().offset(-1) # ValueError: offset() takes a non-negative integer, got -1
209
+ ```
210
+
211
+ Each takes a non-negative integer (`0` reads no record; an `IntEnum` member or an integer type
212
+ such as NumPy's `int64` gives its value). A value that is not an integer — a `bool`, a `str` such
213
+ as `"10"`, a `float`, `None` — raises `TypeError`, and a negative one or one above `2**63 - 1`
214
+ (SurrealQL's largest integer) `ValueError`, naming the method and the value, when `limit()` or
215
+ `offset()` is called, before any request; the value in place is kept. The same holds wherever the
216
+ queryset is read: `exec()`, `first()`, `get()`, `values(…).annotate(…)`, `cache()`, `as_of()` and
217
+ a subquery. The server may still refuse a large value when the read runs: SurrealDB 2.x and the
218
+ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads it.
219
+
183
220
  ---
184
221
 
185
222
  ## Features
@@ -225,6 +262,7 @@ results = await User.objects().query(
225
262
  | Embedded engine (mem://, surrealkv://) & test fixtures | ✅ |
226
263
  | Time travel (`as_of()`, versioned storage) | ✅ |
227
264
  | Subqueries (`Subquery`, a QuerySet as a filter value) | ✅ |
265
+ | Query cache (`cache()`, TTL, invalidated by ORM writes) | ✅ |
228
266
 
229
267
  ### Supported Filter Lookups
230
268
 
@@ -272,23 +310,64 @@ await User.objects().filter(id__startswith="al").exec()
272
310
  A model that aliases its identity through `primary_key` keeps that alias as an ordinary
273
311
  column, so `filter(code="abc")` is a normal string comparison and is unaffected.
274
312
 
275
- #### Filter values that start with `$`
276
-
277
- A filter value beginning with `$` is read as a reference to a **query variable**, not as data.
278
- Use `Var(...)` to say so explicitly, and `$$` to escape a value that genuinely starts with a
279
- dollar sign:
313
+ #### String filter values and `Var()`
280
314
 
281
315
  ```python
282
316
  from surreal_orm_lite import Var
283
317
 
284
- await User.objects().filter(age__gte=Var("min_age")).exec() # … WHERE age >= $min_age
285
- await User.objects().filter(name="$$admin").exec() # matches the literal "$admin"
286
- await User.objects().filter(name="$admin").exec() # deprecated: reads as $admin
318
+ await User.objects().filter(name="$admin").exec() # the string "$admin"
319
+ await User.objects().filter(age__gte=Var("min_age")).variables(min_age=21).exec() # … WHERE age >= $min_age
287
320
  ```
288
321
 
289
- The bare `"$admin"` form still works for backward compatibility but emits a `DeprecationWarning`:
290
- it silently matches nothing when the value is really meant as data, which is a trap for
291
- user-supplied strings. Prefer `Var(...)` in new code.
322
+ A string filter value is data, whatever it starts with: `filter(name="$admin")` compares `name`
323
+ with the string `"$admin"`, bound like any other value, wherever a filter applies: `filter()`, `Q`,
324
+ `get()`, `get_or_create()`, `update_or_create()`, `bulk_update()` by filter, subqueries and live
325
+ queries. `Var(...)` is the only way to reference a query variable, whose value `variables()`
326
+ gives.
327
+
328
+ Until v0.28.1 a value starting with `$` was read as a variable reference (deprecated since
329
+ v0.14.3), and `"$$admin"` was how to write the string `"$admin"`. That escape keeps its meaning,
330
+ deprecated: a filter value starting with `$$` loses one `$` (`"$$admin"` finds `"$admin"`: write
331
+ `"$admin"`), with a `DeprecationWarning`; an item of an `in` list never had the escape.
332
+
333
+ A call written for the old reading, such as `filter(age__lte="$max_age").variables(max_age=25)`,
334
+ now compares `age` with the string `"$max_age"`: a number sorts below a string, so `lt` and `lte`
335
+ match every number, and `gt`, `gte` and `exact` none. When a string filter value is exactly `$`
336
+ followed by the name of a variable that `variables()` gives, the ORM keeps it as data and emits a
337
+ `UserWarning` that says to write `Var("max_age")`, once per read, pointing at your line.
338
+
339
+ `Var()` also reads the parameters SurrealDB sets for each session, without `variables()`: `$auth`
340
+ (the signed-in record user), `$access`, `$session` and `$token`, in reads and in live queries.
341
+
342
+ ```python
343
+ mine = await Doc.objects().filter(owner=Var("auth")).exec() # … WHERE owner = $auth
344
+ ```
345
+
346
+ The string `"$auth"` is data: `filter(owner="$auth")` compares `owner` with the string `"$auth"`,
347
+ so a read keeps only the records whose `owner` is that string, and a live query notifies only for
348
+ those. A string filter value that is exactly `"$auth"`, `"$access"`, `"$session"` or `"$token"`
349
+ emits a `UserWarning` naming the `Var(...)` that reads the parameter, once per read, pointing at
350
+ your line. Any other string, such as `"$x"` with no variable `x`, is data the caller meant: no
351
+ warning. On an edge's `in` and `out`, which hold record ids, such a string is not a record id and
352
+ raises `ValueError`; when it names a variable of `variables()` or one of these parameters, the
353
+ message names the `Var(...)` to write.
354
+
355
+ `get_or_create()` and `update_or_create()` look up their criteria and write the `exact` ones on
356
+ create, so there such a string is refused: `update_or_create(owner="$auth", defaults=…)` would find
357
+ and write the record whose `owner` is the string `"$auth"`, the same record for every record user,
358
+ and `members__contains="$auth"` would look for the string. A criterion that is exactly `$` followed
359
+ by the name of a variable of `variables()` or of one of these parameters raises `SurrealDbError`
360
+ before any request, whatever its lookup, saying to pass the actual value as the criterion: the
361
+ record id, or the value itself. `Var("auth")` finds the signed-in user's record
362
+ (`get_or_create(owner=Var("auth"))` returns it) but cannot be written: with no record to return, it
363
+ raises `SurrealDbError`. Any other string, such as `"$admin"`, is looked up and written as it is. On
364
+ an edge's `in` and `out`, such a criterion raises the `ValueError` above.
365
+
366
+ `variables()` refuses these four names with a `ValueError`: SurrealDB sets them for each session
367
+ and refuses a query variable of that name. To pass your own value, give it another name, or pass
368
+ the value itself in the filter: `filter(token=Var("device_token")).variables(device_token=t)` or
369
+ `filter(token=t)`, in a read or a live query. `Var("token")` without `variables()` reads SurrealDB's
370
+ `$token`.
292
371
 
293
372
  #### Model instances as filter values
294
373
 
@@ -1341,8 +1420,12 @@ else, a string containing a NUL character, an integer beyond 64 bits, a `Decimal
1341
1420
  round or a zero, negative or oversized duration raises `TypeError` when you call `live()`, before
1342
1421
  anything is sent. A `Var` must be supplied through `variables()` — an unbound reference would read
1343
1422
  as `NONE` on every notification, so `age > $min_age` would match every record; it raises
1344
- `SurrealDbError` instead (server parameters such as `$auth` and `$session` are allowed). Every
1345
- other query keeps binding parameters.
1423
+ `SurrealDbError` instead. SurrealDB's own parameters need no `variables()`: `Var("auth")` (and
1424
+ `$access`, `$session`, `$token`) stays a reference the server reads on every notification, so
1425
+ `filter(owner=Var("auth"))` streams the signed-in record user's own records, on both lines; the
1426
+ string `"$auth"` is data, written as `'$auth'` (see
1427
+ [String filter values and `Var()`](#string-filter-values-and-var)). Every other query keeps binding
1428
+ parameters.
1346
1429
 
1347
1430
  #### Diff mode
1348
1431
 
@@ -3345,7 +3428,8 @@ A statement with subqueries is one block, whose `LET`s bind each subquery once,
3345
3428
  - **Reserved names**: `$_sq0`, `$_sq1`, … (`_sq<N>`) are the block's `LET`s and hide a
3346
3429
  `variables()` value of the same name; a subquery can order by `_sqv` only when it selects `_sqv`
3347
3430
  itself (`ValueError` otherwise).
3348
- - `limit()` and `offset()` of a subquery take an `int >= 0` (`ValueError` otherwise).
3431
+ - `limit()` and `offset()` of a subquery take a non-negative integer, as everywhere (`TypeError` or
3432
+ `ValueError` when they are called).
3349
3433
 
3350
3434
  #### Where subqueries apply
3351
3435
 
@@ -3407,8 +3491,7 @@ at the call):
3407
3491
  - an inner `objects(tx=)` whose transaction is not the outer queryset's: `SurrealDbError`;
3408
3492
  - an inner `variables()` binding a name of the statement to another value: `ValueError` (the two
3409
3493
  values must have the same type and be equal: `1` and `True`, or `1` and `1.0`, differ);
3410
- - an inner `limit()` or `offset()` that is not an `int >= 0`, or an inner `order_by()` on `_sqv`
3411
- (above): `ValueError`;
3494
+ - an inner `order_by()` on `_sqv` (above): `ValueError`;
3412
3495
  - a subquery inside a list (`author__in=[Subquery(qs)]`): `ValueError`, give it as the whole value;
3413
3496
  - `Q(...).to_sql()` called on its own with a subquery lookup: `ValueError` (only a QuerySet binds
3414
3497
  a subquery);
@@ -3442,6 +3525,220 @@ are not available yet.
3442
3525
  - **The inner `fetch()` is ignored**, as in the full ORM, while `values()` and `annotate()` are
3443
3526
  refused.
3444
3527
 
3528
+ ### 29. Query cache (`cache()`, `QueryCache`)
3529
+
3530
+ Since v0.28.0 a QuerySet can serve its reads from a **client-side cache**: with `cache(ttl)`, the
3531
+ rows a read returned stay in this process's memory, and the same read is answered from there,
3532
+ without a request, until its TTL runs out or an ORM write changes what it reads. Invalidation is
3533
+ built in: every ORM write removes the cached reads it can change, with nothing to set up. The
3534
+ cache behaves the same on SurrealDB 2.x, 3.x and the embedded engine.
3535
+
3536
+ ```python
3537
+ from surreal_orm_lite import BaseSurrealModel, QueryCache
3538
+
3539
+
3540
+ class Product(BaseSurrealModel):
3541
+ id: str | None = None
3542
+ name: str
3543
+ category: str
3544
+ price: int
3545
+
3546
+
3547
+ for key, name, category, price in [("p1", "Dune", "book", 12), ("p2", "Lamp", "home", 30), ("p3", "Emma", "book", 9)]:
3548
+ await Product(id=key, name=name, category=category, price=price).save()
3549
+
3550
+ books = await Product.objects().filter(category="book").order_by("name").cache(ttl=30).exec() # Dune, Emma
3551
+ again = await Product.objects().filter(category="book").order_by("name").cache(ttl=30).exec() # Dune, Emma
3552
+ hits = QueryCache.stats()["hits"] # 1 (the second read was answered from memory, without a request)
3553
+
3554
+ await Product(id="p4", name="Atlas", category="book", price=40).save() # an ORM write to Product
3555
+ fresh = await Product.objects().filter(category="book").order_by("name").cache(ttl=30).exec() # Atlas, Dune, Emma
3556
+ ```
3557
+
3558
+ #### What is cached
3559
+
3560
+ Every read of a queryset with `cache()`: `exec()`, `first()`, `get()` by filters or by id
3561
+ (`get(<id>)`), `all()`, `count()`, `sum()`, `avg()`, `min()`, `max()`, `exists()`,
3562
+ `values(…).annotate(…)` and `annotate(GeoDistance)`. A read is answered from the cache when an
3563
+ earlier read sent **the same statement with the same variables**, on the same connection and with
3564
+ the same identity, within the TTL, and no ORM write that can change its result has completed
3565
+ since.
3566
+
3567
+ - **Rows are cached, not instances**: each hit builds new instances from a copy of the cached
3568
+ rows, so changing a result never changes the cache.
3569
+ - **Empty results are cached too**: `[]`, a count of `0`, a missing record (`get(<id>)` raises
3570
+ `SurrealDbNotFoundError` on the hit as on the first read). Errors never are.
3571
+ - **Not cached**: reads inside a transaction (`objects(tx=)`, which on SurrealDB 3.x may see its
3572
+ uncommitted writes), `refresh()`, `get_related()`, `traverse()`, `raw_query()` and
3573
+ `call_function()`.
3574
+ - **Refused with `cache()`**: `query()` runs your own SurrealQL and raises `SurrealDbError` (cache
3575
+ its result yourself, see [Configuration and statistics](#configuration-and-statistics));
3576
+ `live()`, `watch()` and `changes()` name `cache()` among the clauses their usual error refuses;
3577
+ `as_of()` raises `SurrealDbError` in either order (a time-travel read is never cached).
3578
+ - **Writes on a cached queryset** (`bulk_update()`, `bulk_delete()`, `QuerySet.patch()`,
3579
+ `delete_table()`, `get_or_create()`…) run as without `cache()`: they never read the cache, and
3580
+ they invalidate it.
3581
+ - **A `Subquery`** is read inside the outer statement: the outer queryset's `cache()` applies, the
3582
+ inner one's is ignored, as its `fetch()` is.
3583
+ - **An internal failure of the cache** (a value it cannot copy, say) never fails a read: the read
3584
+ goes to the database.
3585
+ - It works the same on the embedded engine (`mem://`, `surrealkv://`).
3586
+
3587
+ #### Time to live
3588
+
3589
+ `cache(ttl)` takes the TTL in seconds (an `int` or a `float`) or a `timedelta`. It is the **oldest
3590
+ result this read accepts**: an entry stored by a read with a longer TTL is not served to it once
3591
+ older than its own, and a result it stores lives for its TTL. `cache()` without a TTL uses
3592
+ `QueryCache`'s default when the read runs: 60 seconds unless configured. A TTL of `0` means
3593
+ **never cached**: every read goes to the database. Negative or non-finite values raise
3594
+ `ValueError`, anything but a number or a `timedelta` (`True` included) `TypeError`.
3595
+
3596
+ ```python
3597
+ from datetime import timedelta
3598
+
3599
+ n = await Product.objects().filter(category="book").cache(timedelta(minutes=5)).count() # 3
3600
+ ```
3601
+
3602
+ #### Invalidation
3603
+
3604
+ Every ORM write removes the cached reads it can change, **before** its `post_*` signals fire:
3605
+ `save()`, `update()`, `merge()`, `upsert()`, `patch()`, `delete()`, the atomic operations,
3606
+ `relate()`, `remove_relation()`, `remove_all_relations()`, a typed edge's `save()`,
3607
+ `bulk_create()`, `bulk_update()`, `bulk_delete()`, `QuerySet.patch()`, `delete_table()`,
3608
+ `get_or_create()` and `update_or_create()` when they write, `signup()`, and the DDL helpers
3609
+ `define_computed_fields()` and `define_access()`.
3610
+
3611
+ - A write removes the reads of the tables it writes, the reads whose **subqueries** read them
3612
+ included.
3613
+ - A read that **follows links** is removed by **any** ORM write: `fetch()`, a dotted path such as
3614
+ `filter(**{"author.name": …})` or `order_by("author.name")` (in a subquery too), and a
3615
+ `select()` item that is not a plain field, such as `"author.*"` (the projection reads the linked
3616
+ record).
3617
+ - A read of an **edge model** (`BaseSurrealEdge`) is removed by any delete: deleting a record
3618
+ deletes the edges that point at it or from it.
3619
+ - Inside `transaction()` the tables written are invalidated **at commit** (a failed commit too,
3620
+ nothing on rollback); until then, reads outside the transaction see the committed state.
3621
+ `delete_table()` runs at once, outside `objects(tx=)`, and invalidates at once.
3622
+ - `SurrealDBConnectionManager.signup()` writes into a table the ORM does not map: it empties the
3623
+ cache.
3624
+ - While a write runs, cached reads of its tables go to the database and store nothing: a read
3625
+ answered before the write completed is returned to its caller, never stored.
3626
+
3627
+ What the cache **cannot see** — the TTL bounds it, and `QueryCache.invalidate(Model)` removes a
3628
+ table's entries after such a change:
3629
+
3630
+ - writes by another process or client;
3631
+ - raw SurrealQL: `raw_query()`, `QuerySet.query()`, `call_function()`, `Transaction.add()`;
3632
+ - a write whose task is cancelled, or that fails client-side, after its request was sent: the
3633
+ server may apply it after the invalidation;
3634
+ - writes made by an access method's own `SIGNIN`/`SIGNUP` clauses beyond the record they create;
3635
+ - what the server derives on its own: `DEFINE EVENT`, `REFERENCE … ON DELETE` (3.x), views
3636
+ (`DEFINE TABLE … AS SELECT`), `PERMISSIONS` that read another table;
3637
+ - values computed when the read runs: a `DEFINE PARAM` read with `Var()`, `<future>`/`COMPUTED`
3638
+ fields (over another table, the graph such as `count(<-likes)`, or the time);
3639
+ - a table of relations read through a model that is not a `BaseSurrealEdge`.
3640
+
3641
+ ```python
3642
+ lamp = await Product.objects().cache().get("p2") # Lamp (price 30, now cached)
3643
+ await Product.raw_query("UPDATE Product:p2 SET price = 35") # raw SurrealQL: the cache is not told
3644
+ stale = (await Product.objects().cache().get("p2")).price # 30
3645
+ QueryCache.invalidate(Product) # removes Product's entries (and every read that follows links)
3646
+ price = (await Product.objects().cache().get("p2")).price # 35
3647
+ ```
3648
+
3649
+ #### One cache per connection and identity
3650
+
3651
+ Cached results never cross identities. Each connection the manager opens has its own cache scope,
3652
+ and every identity change on it starts a new one: after a sign-in, a sign-up, `authenticate()` or
3653
+ `invalidate()`, the previous identity's results leave memory. The connection of another event
3654
+ loop, a reconnect and an `embedded_database()` block start empty for the same reason, and closing
3655
+ a connection (`close_connection()`, `close_all_connections()`, or the manager dropping a dead one)
3656
+ drops its results.
3657
+
3658
+ - A session changed **behind the ORM's back** — `raw_query("USE …")`, or `signin()`/`use()`
3659
+ called on the SDK client itself — is not seen: call `QueryCache.clear()` after it.
3660
+ - Cached rows stay in this process's memory until they expire, are evicted, invalidated or
3661
+ cleared, or their connection closes. `configure(enabled=False)` only hides them;
3662
+ `QueryCache.clear()` drops them.
3663
+ - Entries you store with `QueryCache.set()` are not scoped to a connection or an identity: put
3664
+ whatever tells your callers apart in the key.
3665
+
3666
+ #### Configuration and statistics
3667
+
3668
+ `QueryCache` is one store for the whole process, shared by its event loops and threads, with the
3669
+ full SurrealDB-ORM's three settings: `QueryCache.configure(default_ttl=60, max_size=1000,
3670
+ enabled=True)`.
3671
+
3672
+ - **Every call sets all three settings**: an argument you leave out takes its default, as in the
3673
+ full ORM. `configure()` never clears the cache.
3674
+ - `default_ttl` is the TTL of a `cache()` read without one (seconds or a `timedelta`; `0`: never
3675
+ cached). `max_size` is the most entries kept: past it, the least recently used entry is evicted,
3676
+ and lowering it evicts at once.
3677
+ - `enabled=False` **hides** the entries without removing them: `cache()` reads go to the database
3678
+ (calling `cache()` logs a warning), `QueryCache.get()` returns `None`, `QueryCache.set()` stores
3679
+ nothing and nothing is counted, while ORM writes, expiry and closed connections keep removing
3680
+ entries. `enabled=True` serves again the entries still valid. `clear()` is the way to drop the
3681
+ rows from memory; it also resets `hits` and `misses`.
3682
+ - `stats()` returns `entries` (unexpired entries, hidden ones included), `tables` (the distinct
3683
+ tables they are tagged with), `max_size`, `default_ttl` (seconds), `enabled`, and `hits` and
3684
+ `misses` (the `cache()` reads and `get()` calls answered from the cache, and those that were not,
3685
+ since start-up or `clear()`).
3686
+ - `invalidate()` takes a model class or a table name and returns how many entries it removed.
3687
+
3688
+ ```python
3689
+ QueryCache.configure(default_ttl=timedelta(seconds=30), max_size=500) # enabled=True: its default
3690
+ ttl = QueryCache.stats()["default_ttl"] # 30.0
3691
+
3692
+ QueryCache.configure(enabled=False) # hides the entries; default_ttl and max_size take their defaults
3693
+ QueryCache.configure() # enabled again: the entries still valid are served
3694
+ QueryCache.clear() # drops every entry from memory and resets hits and misses
3695
+ ```
3696
+
3697
+ To cache your own results, of `raw_query()` for instance, build a key with `make_key()` and use
3698
+ `get()` and `set()`. The key comes from the statement, its variables as the SDK sends them and the
3699
+ table; the entry is tagged with the table, so an ORM write to it removes the entry. From the
3700
+ moment the write starts, its `pre_*`, `around_*` and `post_*` handlers included, `get()` returns
3701
+ `None` for the entry (a miss), and what `set()` stores for that table meanwhile leaves with the
3702
+ write:
3703
+
3704
+ ```python
3705
+ async def total_price() -> int:
3706
+ statement = "SELECT math::sum(price) AS total FROM Product GROUP ALL"
3707
+ key = QueryCache.make_key(statement, {}, "Product")
3708
+ rows = QueryCache.get(key) # a copy, or None: missing, expired, or the cache is disabled
3709
+ if rows is None:
3710
+ rows = await Product.raw_query(statement)
3711
+ QueryCache.set(key, rows, "Product", ttl=60)
3712
+ return rows[0]["total"]
3713
+
3714
+
3715
+ total = await total_price() # 96 (the database answers)
3716
+ cached_total = await total_price() # 96 (the cache answers)
3717
+ ```
3718
+
3719
+ #### Coming from the full SurrealDB-ORM
3720
+
3721
+ - **The same names**: `cache(ttl=…)` on a QuerySet, and `QueryCache` with `configure()`,
3722
+ `make_key()`, `get()`, `set()`, `invalidate()`, `clear()` and `stats()`, imported from
3723
+ `surreal_orm_lite`.
3724
+ - **Every read is cached**, not only `exec()` (with `first()` and `get()` by filters):
3725
+ `get(<id>)`, `all()`, `count()`, the aggregations, `exists()` and `values()`+`annotate()` too.
3726
+ - **Invalidation is built in** and needs no `configure()` call. It covers `bulk_*()`,
3727
+ `QuerySet.patch()`, the atomic operations, relations and transactions (at commit), where the
3728
+ full ORM listens to `post_save`, `post_update` and `post_delete`. Reads through links
3729
+ (`fetch()`, dotted paths) and edge reads after a delete are invalidated too.
3730
+ - **Rows are cached**, and each hit builds new instances: the full ORM caches the instances.
3731
+ - **Keys come from the CBOR bytes the SDK sends**, with the keys of mappings sorted as the full
3732
+ ORM's `sort_keys=True` does: `RecordID("user", 1)` and `"user:1"` never share an entry, where the
3733
+ full ORM's JSON with `default=str` writes them alike.
3734
+ - **One scope per connection and identity**: a sign-in never reads another identity's results.
3735
+ - **`live()`, `watch()`, `changes()` and `query()` refuse `cache()`**, which the full ORM ignores
3736
+ there; `as_of()` reads are not cached (the full ORM has no time travel).
3737
+ - **`ttl`** may be a `float` or a `timedelta`; `0` is never cached, as in the full ORM; negative or
3738
+ non-finite values are refused; it is the oldest result a read accepts.
3739
+ - **LRU eviction** instead of FIFO.
3740
+ - **`invalidate()` takes a table name too**, and **`stats()` adds `hits` and `misses`**.
3741
+
3445
3742
  ---
3446
3743
 
3447
3744
  ## Configuration Options
@@ -3556,7 +3853,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
3556
3853
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
3557
3854
  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
3558
3855
  otherwise. The full suite and every divergence below were re-verified on both new versions.
3559
- 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.
3856
+ 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.
3560
3857
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
3561
3858
 
3562
3859
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -3661,6 +3958,10 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
3661
3958
  | A subquery with `order_by()` and `limit()` | right; the ORM also selects the order fields, without which 2.x refuses to order by a field other than the one compared | right: the ORM binds each subquery once, in a `LET`; 3.2 and later can return wrong rows for such an inline sub-SELECT (surrealdb#7470) | v0.27.0 |
3662
3959
  | A subquery reading a table that does not exist | read as empty, like any missing table | read as empty in three requests (statement, table probe, re-send); other errors, even ones quoting "does not exist", are relayed; transaction writes fail; `live()` raises on start | v0.27.0 |
3663
3960
  | Subqueries under `as_of()` | each subquery reads at the same moment: the ORM adds `VERSION` to it (the server would read the current state) | the same (the server applies the outer `VERSION` to an inline sub-SELECT only); without versioned storage `SurrealDbError`, but 3.1.5 raises the server's own `ThrownError` | v0.27.0 |
3961
+ | Query cache (`cache()`, `QueryCache`) | same on both lines: client-side, per connection and identity; writes in a transaction invalidate at commit; reads in one are never cached (on 2.x they raise: buffered) | the same; reads inside an interactive transaction are never cached (they see its uncommitted writes) | v0.28.0 |
3962
+ | `select("meta.*")` on a nested object that is not a record link | its values, as a list; through a link (`select("author.*")`), the linked record | the object; through a link, the linked record | pre-existing (documented in v0.28.1) |
3963
+ | `filter(f="$x")`: a string filter value starting with `$` | same on both lines: compared with the string `"$x"`, bound like any value, in a live query too; `Var("x")` reads the variable `$x`, `Var("auth")` SurrealDB's `$auth` | the same; on an edge's `in`/`out` (record ids) such a string raises `ValueError`, on both lines; `$access`, `$session`, `$token` read like `$auth` | v0.28.1 |
3964
+ | `limit(n)` or `offset(n)` above `4294967295` (`2**32 - 1`) | the server refuses the read: `Found <n> but the LIMIT clause must evaluate to a positive integer` (`START` likewise) | read; above `2**63 - 1` the ORM raises `ValueError` when `limit()` or `offset()` is called, on both lines | pre-existing (documented in v0.28.1) |
3664
3965
  | 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 |
3665
3966
 
3666
3967
  > **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.
@@ -3733,7 +4034,8 @@ Contributions are welcome! Please:
3733
4034
  | v0.25.0 | Embedded test engine | ✅ Released |
3734
4035
  | v0.26.0 | Time travel (versioned storage) | ✅ Released |
3735
4036
  | v0.27.0 | Subqueries | ✅ Released |
3736
- | v0.28.0 – v0.29.0 | Tier 2 — Extended (cache, multi-db) | 📋 Planned |
4037
+ | v0.28.0 | Query cache | ✅ Released |
4038
+ | v0.29.0 | Tier 2 — Multi-database | 📋 Planned |
3737
4039
  | v0.30.0 – v0.39.0 | Tier 3 — Advanced (search, DDL, migrations, CLI) | 📋 Planned |
3738
4040
  | v0.40.0 | Beta Phase (API freeze, hardening) | 📋 Planned |
3739
4041
  | v2.0.0 | Production / GA (aligned with SDK 2.0) | 📋 Planned |
@@ -3785,7 +4087,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
3785
4087
  | Embedded engine | ✅ v0.25.0 (mem://, surrealkv://; rocksdb:// #233) | ❌ (HTTP/WebSocket only) |
3786
4088
  | Time travel (`VERSION`) | ✅ v0.26.0 (`as_of()`) | ❌ |
3787
4089
  | Subqueries | ✅ v0.27.0 (`Subquery`, a QuerySet in `filter()`) | ✅ |
3788
- | Query Cache | v0.28.0 | ✅ |
4090
+ | Query Cache | ✅ v0.28.0 (`cache()`, `QueryCache`) | ✅ |
3789
4091
  | Multi-database | v0.29.0 | ✅ |
3790
4092
  | Schema Introspection | v0.30.0 | ✅ |
3791
4093
  | DEFINE EVENT | v0.31.0 | ✅ |