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.
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/CHANGELOG.md +107 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/PKG-INFO +222 -4
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/README.md +221 -3
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/__init__.py +4 -1
- surreal_orm_lite-0.28.0/src/surreal_orm_lite/cache.py +813 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/connection_manager.py +25 -3
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/edge.py +2 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/model_auth.py +3 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/model_base.py +19 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/query_set.py +223 -10
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/subquery.py +2 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/transaction.py +57 -11
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/.gitignore +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/LICENSE +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/Makefile +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.0}/src/surreal_orm_lite/types.py +0 -0
- {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.
|
|
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
|
|
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 | ✅ |
|