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.
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/CHANGELOG.md +197 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/PKG-INFO +322 -20
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/README.md +321 -19
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/pyproject.toml +1 -1
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/__init__.py +4 -1
- surreal_orm_lite-0.28.1/src/surreal_orm_lite/cache.py +813 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/connection_manager.py +25 -3
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/constants.py +7 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/edge.py +2 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/functions.py +16 -7
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/model_auth.py +3 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/model_base.py +19 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/query_set.py +462 -50
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/subquery.py +19 -5
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/surql_literal.py +9 -6
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/transaction.py +57 -11
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/utils.py +180 -35
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/.gitignore +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/LICENSE +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/Makefile +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.27.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/time_travel.py +0 -0
- {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.
|
|
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
|
-
####
|
|
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(
|
|
285
|
-
await User.objects().filter(
|
|
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
|
-
|
|
290
|
-
|
|
291
|
-
|
|
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
|
|
1345
|
-
|
|
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
|
|
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 `
|
|
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
|
|
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 | ✅ |
|