surreal-orm-lite 0.27.0__tar.gz → 0.28.0__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.0}/CHANGELOG.md +107 -0
  2. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/PKG-INFO +222 -4
  3. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/README.md +221 -3
  4. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/__init__.py +4 -1
  6. surreal_orm_lite-0.28.0/src/surreal_orm_lite/cache.py +813 -0
  7. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/connection_manager.py +25 -3
  8. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/edge.py +2 -0
  9. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/model_auth.py +3 -0
  10. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/model_base.py +19 -0
  11. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/query_set.py +223 -10
  12. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/subquery.py +2 -0
  13. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/transaction.py +57 -11
  14. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/.gitignore +0 -0
  15. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/LICENSE +0 -0
  16. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/Makefile +0 -0
  17. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/_sdk.py +0 -0
  18. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/aggregations.py +0 -0
  19. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/auth.py +0 -0
  20. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/changefeed.py +0 -0
  21. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/concurrency.py +0 -0
  22. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/constants.py +0 -0
  23. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/decoding.py +0 -0
  24. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/embedded.py +0 -0
  25. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/encoding.py +0 -0
  26. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/enum.py +0 -0
  27. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/exceptions.py +0 -0
  28. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/functions.py +0 -0
  29. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/geo.py +0 -0
  30. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/live.py +0 -0
  31. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/py.typed +0 -0
  32. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/q.py +0 -0
  33. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/signals.py +0 -0
  34. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/surql_literal.py +0 -0
  35. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
  36. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/testing/database.py +0 -0
  37. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  38. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/time_travel.py +0 -0
  39. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/types.py +0 -0
  40. {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,113 @@ 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.0] - 2026-10-17
9
+
10
+ Query cache: a QuerySet serves its reads from a client-side cache with `cache(ttl)`, and every ORM
11
+ write removes the cached reads it can change, with nothing to set up. The sixth minor of Tier 2.
12
+
13
+ ### Added
14
+
15
+ - **`QuerySet.cache(ttl=None)`** and **`QueryCache`**, exported from `surreal_orm_lite` (the full
16
+ SurrealDB-ORM's names). The rows a cached read returned stay in this process's memory, and the
17
+ same read is answered from there, without a request, until its TTL runs out or an ORM write
18
+ changes what it reads.
19
+
20
+ ```python
21
+ from surreal_orm_lite import QueryCache
22
+
23
+ books = await Product.objects().filter(category="book").cache(ttl=30).exec() # the database answers
24
+ again = await Product.objects().filter(category="book").cache(ttl=30).exec() # the cache answers
25
+ await Product(id="p4", name="Atlas", category="book", price=40).save() # removes Product's cached reads
26
+ fresh = await Product.objects().filter(category="book").cache(ttl=30).exec() # the database answers
27
+ QueryCache.stats()["hits"] # 1
28
+ ```
29
+
30
+ - **Every read of a cached queryset**: `exec()`, `first()`, `get()` by filters or by id, `all()`,
31
+ `count()`, `sum()`, `avg()`, `min()`, `max()`, `exists()`, `values(…).annotate(…)` and
32
+ `annotate(GeoDistance)`. A read is a hit when an earlier read sent the same statement with the
33
+ same variables, on the same connection and with the same identity, within the TTL. Rows are
34
+ cached, not instances: each hit builds new instances from a copy. Empty results are cached
35
+ (`get(<id>)` of a missing record raises `SurrealDbNotFoundError` on the hit too); errors never
36
+ are. An internal failure of the cache never fails a read: the read goes to the database.
37
+ - **Time to live**: seconds (`int` or `float`) or a `timedelta`, the oldest result the read
38
+ accepts; `cache()` without a TTL uses `QueryCache`'s default (60 s unless configured); `0` means
39
+ never cached.
40
+ - **Built-in invalidation**: every ORM write removes the cached reads of the tables it writes,
41
+ before its `post_*` signals fire — `save()`, `update()`, `merge()`, `upsert()`, `patch()`,
42
+ `delete()`, the atomic operations, `relate()` and the `remove_*()` helpers, a typed edge's
43
+ `save()`, `bulk_create()`, `bulk_update()`, `bulk_delete()`, `QuerySet.patch()`,
44
+ `delete_table()`, `get_or_create()`/`update_or_create()` when they write, `signup()`,
45
+ `define_computed_fields()` and `define_access()`. Reads whose subqueries read those tables go
46
+ too; a read that follows links (`fetch()`, a dotted path, a `select()` item that is not a plain
47
+ field) is removed by any ORM write, and a read of an edge model by any delete. Inside
48
+ `transaction()` the written tables are invalidated at commit (a failed commit too, nothing on
49
+ rollback). While a write runs, reads of its tables go to the database and store nothing.
50
+ - **One cache scope per connection and identity**: a sign-in, a sign-up, `authenticate()` or
51
+ `invalidate()` starts a new scope and drops the previous identity's results; another event loop's
52
+ connection, a reconnect and an `embedded_database()` block start empty; closing a connection
53
+ drops its results. Cached results never cross identities.
54
+ - **`QueryCache`**: `configure(default_ttl=60, max_size=1000, enabled=True)` sets all three
55
+ settings at every call, as in the full ORM, and never clears; `enabled=False` hides the entries
56
+ (`cache()` reads go to the database and calling `cache()` logs a warning). Past `max_size` the
57
+ least recently used entry is evicted. `invalidate()` takes a model class or a table name and
58
+ returns how many entries it removed; `clear()` drops every entry and resets the counters;
59
+ `stats()` returns `entries`, `tables`, `max_size`, `default_ttl`, `enabled`, `hits` and
60
+ `misses`. `make_key()`, `get()` and `set()` cache your own results (of `raw_query()`, say),
61
+ tagged with a table so that an ORM write to it removes them; `get()` misses while such a write
62
+ runs.
63
+ - **Refusals**: `query()` raises `SurrealDbError` on a queryset with `cache()`; `live()`, `watch()`
64
+ and `changes()` name `cache()` among the clauses their usual error refuses; combining `cache()`
65
+ with `as_of()` raises `SurrealDbError`, in either order. A negative or non-finite TTL raises
66
+ `ValueError`, anything but a number or a `timedelta` (`True` included) `TypeError`.
67
+ - README section 29, "Query cache (`cache()`, `QueryCache`)" (what is cached, the time to live,
68
+ invalidation and what the cache cannot see, one cache per connection and identity,
69
+ configuration and statistics, a note for users of the full SurrealDB-ORM), a features row, a
70
+ row in the 2.x/3.x behaviour table, the comparison and roadmap rows, and the example notebook
71
+ `examples/v0.28.0_query_cache.ipynb`.
72
+
73
+ ### Changed
74
+
75
+ - ORM writes now also remove the cached reads they can change, in memory, without a request.
76
+ Without `cache()`, every read and write sends the same requests as in v0.27.x; the texts of the
77
+ `live()`, `watch()` and `changes()` refusals are unchanged.
78
+
79
+ ### Notes
80
+
81
+ - **Same on SurrealDB 2.x and 3.x**, and on the embedded engine. Reads inside a transaction
82
+ (`objects(tx=)`) are never cached: on 3.x an interactive transaction's reads see its uncommitted
83
+ writes, and on 2.x a buffered transaction cannot read.
84
+ - **What the cache cannot see** (the TTL bounds it; `QueryCache.invalidate(Model)` removes a
85
+ table's entries after such a change): writes by another process or client; raw SurrealQL
86
+ (`raw_query()`, `QuerySet.query()`, `call_function()`, `Transaction.add()`); a write whose task
87
+ is cancelled, or that fails client-side, after its request was sent; writes made by an access
88
+ method's own `SIGNIN`/`SIGNUP` clauses beyond the record they create; what the server derives on
89
+ its own (`DEFINE EVENT`, `REFERENCE … ON DELETE` on 3.x, views, `PERMISSIONS` that read another
90
+ table); values computed when the read runs (a `DEFINE PARAM` read with `Var()`,
91
+ `<future>`/`COMPUTED` fields, time functions in a `select()` expression); a table of relations
92
+ read through a model that is not a `BaseSurrealEdge`. A session changed behind the ORM's back
93
+ (`raw_query("USE …")`, `signin()` or `use()` on the SDK client) is not seen either: call
94
+ `QueryCache.clear()` after it.
95
+ - **Memory**: cached rows stay in this process's memory until they expire, are evicted,
96
+ invalidated or cleared, or their connection closes. `configure(enabled=False)` only hides them;
97
+ `QueryCache.clear()` drops them. Entries stored with `QueryCache.set()` are not scoped to a
98
+ connection or an identity: put whatever tells your callers apart in the key.
99
+ - **Keys** are the SHA-256 of the CBOR bytes the official SDK sends, with the keys of mappings
100
+ sorted: `RecordID("user", 1)` and `"user:1"` never share an entry. An SDK that exposes no CBOR
101
+ encoder sends every `cache()` read to the database (one warning per process).
102
+ - Concurrent misses of the same read each send their own request.
103
+ - **Differences from the full SurrealDB-ORM**: every read is cached, not only `exec()`, `first()`
104
+ and `get()` by filters; invalidation is built in and covers bulk operations, `QuerySet.patch()`,
105
+ the atomic operations, relations and transactions, where the full ORM listens to `post_save`,
106
+ `post_update` and `post_delete`; rows are cached instead of instances; one scope per connection
107
+ and identity; `live()`, `watch()`, `changes()` and `query()` refuse `cache()`; the TTL may be a
108
+ `float` or a `timedelta` and negative values are refused; LRU eviction instead of FIFO;
109
+ `invalidate()` takes a table name too; `stats()` adds `hits` and `misses`.
110
+ - Not available yet: invalidation from other processes or clients (through live queries),
111
+ caching `as_of()` reads, sharing cached results between event loops.
112
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, and on the embedded engine,
113
+ plus 3.1.5 for backward compatibility (identical).
114
+
8
115
  ## [0.27.0] - 2026-10-16
9
116
 
10
117
  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.0
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
@@ -225,6 +225,7 @@ results = await User.objects().query(
225
225
  | Embedded engine (mem://, surrealkv://) & test fixtures | ✅ |
226
226
  | Time travel (`as_of()`, versioned storage) | ✅ |
227
227
  | Subqueries (`Subquery`, a QuerySet as a filter value) | ✅ |
228
+ | Query cache (`cache()`, TTL, invalidated by ORM writes) | ✅ |
228
229
 
229
230
  ### Supported Filter Lookups
230
231
 
@@ -3442,6 +3443,221 @@ are not available yet.
3442
3443
  - **The inner `fetch()` is ignored**, as in the full ORM, while `values()` and `annotate()` are
3443
3444
  refused.
3444
3445
 
3446
+ ### 29. Query cache (`cache()`, `QueryCache`)
3447
+
3448
+ Since v0.28.0 a QuerySet can serve its reads from a **client-side cache**: with `cache(ttl)`, the
3449
+ rows a read returned stay in this process's memory, and the same read is answered from there,
3450
+ without a request, until its TTL runs out or an ORM write changes what it reads. Invalidation is
3451
+ built in: every ORM write removes the cached reads it can change, with nothing to set up. The
3452
+ cache behaves the same on SurrealDB 2.x, 3.x and the embedded engine.
3453
+
3454
+ ```python
3455
+ from surreal_orm_lite import BaseSurrealModel, QueryCache
3456
+
3457
+
3458
+ class Product(BaseSurrealModel):
3459
+ id: str | None = None
3460
+ name: str
3461
+ category: str
3462
+ price: int
3463
+
3464
+
3465
+ for key, name, category, price in [("p1", "Dune", "book", 12), ("p2", "Lamp", "home", 30), ("p3", "Emma", "book", 9)]:
3466
+ await Product(id=key, name=name, category=category, price=price).save()
3467
+
3468
+ books = await Product.objects().filter(category="book").order_by("name").cache(ttl=30).exec() # Dune, Emma
3469
+ again = await Product.objects().filter(category="book").order_by("name").cache(ttl=30).exec() # Dune, Emma
3470
+ hits = QueryCache.stats()["hits"] # 1 (the second read was answered from memory, without a request)
3471
+
3472
+ await Product(id="p4", name="Atlas", category="book", price=40).save() # an ORM write to Product
3473
+ fresh = await Product.objects().filter(category="book").order_by("name").cache(ttl=30).exec() # Atlas, Dune, Emma
3474
+ ```
3475
+
3476
+ #### What is cached
3477
+
3478
+ Every read of a queryset with `cache()`: `exec()`, `first()`, `get()` by filters or by id
3479
+ (`get(<id>)`), `all()`, `count()`, `sum()`, `avg()`, `min()`, `max()`, `exists()`,
3480
+ `values(…).annotate(…)` and `annotate(GeoDistance)`. A read is answered from the cache when an
3481
+ earlier read sent **the same statement with the same variables**, on the same connection and with
3482
+ the same identity, within the TTL, and no ORM write that can change its result has completed
3483
+ since.
3484
+
3485
+ - **Rows are cached, not instances**: each hit builds new instances from a copy of the cached
3486
+ rows, so changing a result never changes the cache.
3487
+ - **Empty results are cached too**: `[]`, a count of `0`, a missing record (`get(<id>)` raises
3488
+ `SurrealDbNotFoundError` on the hit as on the first read). Errors never are.
3489
+ - **Not cached**: reads inside a transaction (`objects(tx=)`, which on SurrealDB 3.x may see its
3490
+ uncommitted writes), `refresh()`, `get_related()`, `traverse()`, `raw_query()` and
3491
+ `call_function()`.
3492
+ - **Refused with `cache()`**: `query()` runs your own SurrealQL and raises `SurrealDbError` (cache
3493
+ its result yourself, see [Configuration and statistics](#configuration-and-statistics));
3494
+ `live()`, `watch()` and `changes()` name `cache()` among the clauses their usual error refuses;
3495
+ `as_of()` raises `SurrealDbError` in either order (a time-travel read is never cached).
3496
+ - **Writes on a cached queryset** (`bulk_update()`, `bulk_delete()`, `QuerySet.patch()`,
3497
+ `delete_table()`, `get_or_create()`…) run as without `cache()`: they never read the cache, and
3498
+ they invalidate it.
3499
+ - **A `Subquery`** is read inside the outer statement: the outer queryset's `cache()` applies, the
3500
+ inner one's is ignored, as its `fetch()` is.
3501
+ - **An internal failure of the cache** (a value it cannot copy, say) never fails a read: the read
3502
+ goes to the database.
3503
+ - It works the same on the embedded engine (`mem://`, `surrealkv://`).
3504
+
3505
+ #### Time to live
3506
+
3507
+ `cache(ttl)` takes the TTL in seconds (an `int` or a `float`) or a `timedelta`. It is the **oldest
3508
+ result this read accepts**: an entry stored by a read with a longer TTL is not served to it once
3509
+ older than its own, and a result it stores lives for its TTL. `cache()` without a TTL uses
3510
+ `QueryCache`'s default when the read runs: 60 seconds unless configured. A TTL of `0` means
3511
+ **never cached**: every read goes to the database. Negative or non-finite values raise
3512
+ `ValueError`, anything but a number or a `timedelta` (`True` included) `TypeError`.
3513
+
3514
+ ```python
3515
+ from datetime import timedelta
3516
+
3517
+ n = await Product.objects().filter(category="book").cache(timedelta(minutes=5)).count() # 3
3518
+ ```
3519
+
3520
+ #### Invalidation
3521
+
3522
+ Every ORM write removes the cached reads it can change, **before** its `post_*` signals fire:
3523
+ `save()`, `update()`, `merge()`, `upsert()`, `patch()`, `delete()`, the atomic operations,
3524
+ `relate()`, `remove_relation()`, `remove_all_relations()`, a typed edge's `save()`,
3525
+ `bulk_create()`, `bulk_update()`, `bulk_delete()`, `QuerySet.patch()`, `delete_table()`,
3526
+ `get_or_create()` and `update_or_create()` when they write, `signup()`, and the DDL helpers
3527
+ `define_computed_fields()` and `define_access()`.
3528
+
3529
+ - A write removes the reads of the tables it writes, the reads whose **subqueries** read them
3530
+ included.
3531
+ - A read that **follows links** is removed by **any** ORM write: `fetch()`, a dotted path such as
3532
+ `filter(**{"author.name": …})` or `order_by("author.name")` (in a subquery too), and a
3533
+ `select()` item that is not a plain field, such as `"author.*"` or an expression (a projection
3534
+ may read another table).
3535
+ - A read of an **edge model** (`BaseSurrealEdge`) is removed by any delete: deleting a record
3536
+ deletes the edges that point at it or from it.
3537
+ - Inside `transaction()` the tables written are invalidated **at commit** (a failed commit too,
3538
+ nothing on rollback); until then, reads outside the transaction see the committed state.
3539
+ `delete_table()` runs at once, outside `objects(tx=)`, and invalidates at once.
3540
+ - `SurrealDBConnectionManager.signup()` writes into a table the ORM does not map: it empties the
3541
+ cache.
3542
+ - While a write runs, cached reads of its tables go to the database and store nothing: a read
3543
+ answered before the write completed is returned to its caller, never stored.
3544
+
3545
+ What the cache **cannot see** — the TTL bounds it, and `QueryCache.invalidate(Model)` removes a
3546
+ table's entries after such a change:
3547
+
3548
+ - writes by another process or client;
3549
+ - raw SurrealQL: `raw_query()`, `QuerySet.query()`, `call_function()`, `Transaction.add()`;
3550
+ - a write whose task is cancelled, or that fails client-side, after its request was sent: the
3551
+ server may apply it after the invalidation;
3552
+ - writes made by an access method's own `SIGNIN`/`SIGNUP` clauses beyond the record they create;
3553
+ - what the server derives on its own: `DEFINE EVENT`, `REFERENCE … ON DELETE` (3.x), views
3554
+ (`DEFINE TABLE … AS SELECT`), `PERMISSIONS` that read another table;
3555
+ - values computed when the read runs: a `DEFINE PARAM` read with `Var()`, `<future>`/`COMPUTED`
3556
+ fields (over another table, the graph such as `count(<-likes)`, or the time), time functions
3557
+ inside a `select()` expression;
3558
+ - a table of relations read through a model that is not a `BaseSurrealEdge`.
3559
+
3560
+ ```python
3561
+ lamp = await Product.objects().cache().get("p2") # Lamp (price 30, now cached)
3562
+ await Product.raw_query("UPDATE Product:p2 SET price = 35") # raw SurrealQL: the cache is not told
3563
+ stale = (await Product.objects().cache().get("p2")).price # 30
3564
+ QueryCache.invalidate(Product) # removes Product's entries (and every read that follows links)
3565
+ price = (await Product.objects().cache().get("p2")).price # 35
3566
+ ```
3567
+
3568
+ #### One cache per connection and identity
3569
+
3570
+ Cached results never cross identities. Each connection the manager opens has its own cache scope,
3571
+ and every identity change on it starts a new one: after a sign-in, a sign-up, `authenticate()` or
3572
+ `invalidate()`, the previous identity's results leave memory. The connection of another event
3573
+ loop, a reconnect and an `embedded_database()` block start empty for the same reason, and closing
3574
+ a connection (`close_connection()`, `close_all_connections()`, or the manager dropping a dead one)
3575
+ drops its results.
3576
+
3577
+ - A session changed **behind the ORM's back** — `raw_query("USE …")`, or `signin()`/`use()`
3578
+ called on the SDK client itself — is not seen: call `QueryCache.clear()` after it.
3579
+ - Cached rows stay in this process's memory until they expire, are evicted, invalidated or
3580
+ cleared, or their connection closes. `configure(enabled=False)` only hides them;
3581
+ `QueryCache.clear()` drops them.
3582
+ - Entries you store with `QueryCache.set()` are not scoped to a connection or an identity: put
3583
+ whatever tells your callers apart in the key.
3584
+
3585
+ #### Configuration and statistics
3586
+
3587
+ `QueryCache` is one store for the whole process, shared by its event loops and threads, with the
3588
+ full SurrealDB-ORM's three settings: `QueryCache.configure(default_ttl=60, max_size=1000,
3589
+ enabled=True)`.
3590
+
3591
+ - **Every call sets all three settings**: an argument you leave out takes its default, as in the
3592
+ full ORM. `configure()` never clears the cache.
3593
+ - `default_ttl` is the TTL of a `cache()` read without one (seconds or a `timedelta`; `0`: never
3594
+ cached). `max_size` is the most entries kept: past it, the least recently used entry is evicted,
3595
+ and lowering it evicts at once.
3596
+ - `enabled=False` **hides** the entries without removing them: `cache()` reads go to the database
3597
+ (calling `cache()` logs a warning), `QueryCache.get()` returns `None`, `QueryCache.set()` stores
3598
+ nothing and nothing is counted, while ORM writes, expiry and closed connections keep removing
3599
+ entries. `enabled=True` serves again the entries still valid. `clear()` is the way to drop the
3600
+ rows from memory; it also resets `hits` and `misses`.
3601
+ - `stats()` returns `entries` (unexpired entries, hidden ones included), `tables` (the distinct
3602
+ tables they are tagged with), `max_size`, `default_ttl` (seconds), `enabled`, and `hits` and
3603
+ `misses` (the `cache()` reads and `get()` calls answered from the cache, and those that were not,
3604
+ since start-up or `clear()`).
3605
+ - `invalidate()` takes a model class or a table name and returns how many entries it removed.
3606
+
3607
+ ```python
3608
+ QueryCache.configure(default_ttl=timedelta(seconds=30), max_size=500) # enabled=True: its default
3609
+ ttl = QueryCache.stats()["default_ttl"] # 30.0
3610
+
3611
+ QueryCache.configure(enabled=False) # hides the entries; default_ttl and max_size take their defaults
3612
+ QueryCache.configure() # enabled again: the entries still valid are served
3613
+ QueryCache.clear() # drops every entry from memory and resets hits and misses
3614
+ ```
3615
+
3616
+ To cache your own results, of `raw_query()` for instance, build a key with `make_key()` and use
3617
+ `get()` and `set()`. The key comes from the statement, its variables as the SDK sends them and the
3618
+ table; the entry is tagged with the table, so an ORM write to it removes the entry. From the
3619
+ moment the write starts, its `pre_*`, `around_*` and `post_*` handlers included, `get()` returns
3620
+ `None` for the entry (a miss), and what `set()` stores for that table meanwhile leaves with the
3621
+ write:
3622
+
3623
+ ```python
3624
+ async def total_price() -> int:
3625
+ statement = "SELECT math::sum(price) AS total FROM Product GROUP ALL"
3626
+ key = QueryCache.make_key(statement, {}, "Product")
3627
+ rows = QueryCache.get(key) # a copy, or None: missing, expired, or the cache is disabled
3628
+ if rows is None:
3629
+ rows = await Product.raw_query(statement)
3630
+ QueryCache.set(key, rows, "Product", ttl=60)
3631
+ return rows[0]["total"]
3632
+
3633
+
3634
+ total = await total_price() # 96 (the database answers)
3635
+ cached_total = await total_price() # 96 (the cache answers)
3636
+ ```
3637
+
3638
+ #### Coming from the full SurrealDB-ORM
3639
+
3640
+ - **The same names**: `cache(ttl=…)` on a QuerySet, and `QueryCache` with `configure()`,
3641
+ `make_key()`, `get()`, `set()`, `invalidate()`, `clear()` and `stats()`, imported from
3642
+ `surreal_orm_lite`.
3643
+ - **Every read is cached**, not only `exec()` (with `first()` and `get()` by filters):
3644
+ `get(<id>)`, `all()`, `count()`, the aggregations, `exists()` and `values()`+`annotate()` too.
3645
+ - **Invalidation is built in** and needs no `configure()` call. It covers `bulk_*()`,
3646
+ `QuerySet.patch()`, the atomic operations, relations and transactions (at commit), where the
3647
+ full ORM listens to `post_save`, `post_update` and `post_delete`. Reads through links
3648
+ (`fetch()`, dotted paths) and edge reads after a delete are invalidated too.
3649
+ - **Rows are cached**, and each hit builds new instances: the full ORM caches the instances.
3650
+ - **Keys come from the CBOR bytes the SDK sends**, with the keys of mappings sorted as the full
3651
+ ORM's `sort_keys=True` does: `RecordID("user", 1)` and `"user:1"` never share an entry, where the
3652
+ full ORM's JSON with `default=str` writes them alike.
3653
+ - **One scope per connection and identity**: a sign-in never reads another identity's results.
3654
+ - **`live()`, `watch()`, `changes()` and `query()` refuse `cache()`**, which the full ORM ignores
3655
+ there; `as_of()` reads are not cached (the full ORM has no time travel).
3656
+ - **`ttl`** may be a `float` or a `timedelta`; `0` is never cached, as in the full ORM; negative or
3657
+ non-finite values are refused; it is the oldest result a read accepts.
3658
+ - **LRU eviction** instead of FIFO.
3659
+ - **`invalidate()` takes a table name too**, and **`stats()` adds `hits` and `misses`**.
3660
+
3445
3661
  ---
3446
3662
 
3447
3663
  ## Configuration Options
@@ -3556,7 +3772,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
3556
3772
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
3557
3773
  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
3774
  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.
3775
+ 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.
3560
3776
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
3561
3777
 
3562
3778
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -3661,6 +3877,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
3661
3877
  | 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
3878
  | 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
3879
  | 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 |
3880
+ | 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 |
3664
3881
  | 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
3882
 
3666
3883
  > **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 +3950,8 @@ Contributions are welcome! Please:
3733
3950
  | v0.25.0 | Embedded test engine | ✅ Released |
3734
3951
  | v0.26.0 | Time travel (versioned storage) | ✅ Released |
3735
3952
  | v0.27.0 | Subqueries | ✅ Released |
3736
- | v0.28.0 – v0.29.0 | Tier 2 — Extended (cache, multi-db) | 📋 Planned |
3953
+ | v0.28.0 | Query cache | ✅ Released |
3954
+ | v0.29.0 | Tier 2 — Multi-database | 📋 Planned |
3737
3955
  | v0.30.0 – v0.39.0 | Tier 3 — Advanced (search, DDL, migrations, CLI) | 📋 Planned |
3738
3956
  | v0.40.0 | Beta Phase (API freeze, hardening) | 📋 Planned |
3739
3957
  | v2.0.0 | Production / GA (aligned with SDK 2.0) | 📋 Planned |
@@ -3785,7 +4003,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
3785
4003
  | Embedded engine | ✅ v0.25.0 (mem://, surrealkv://; rocksdb:// #233) | ❌ (HTTP/WebSocket only) |
3786
4004
  | Time travel (`VERSION`) | ✅ v0.26.0 (`as_of()`) | ❌ |
3787
4005
  | Subqueries | ✅ v0.27.0 (`Subquery`, a QuerySet in `filter()`) | ✅ |
3788
- | Query Cache | v0.28.0 | ✅ |
4006
+ | Query Cache | ✅ v0.28.0 (`cache()`, `QueryCache`) | ✅ |
3789
4007
  | Multi-database | v0.29.0 | ✅ |
3790
4008
  | Schema Introspection | v0.30.0 | ✅ |
3791
4009
  | DEFINE EVENT | v0.31.0 | ✅ |