surreal-orm-lite 0.28.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.28.0 → surreal_orm_lite-0.28.1}/CHANGELOG.md +90 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/PKG-INFO +106 -22
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/README.md +105 -21
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/pyproject.toml +1 -1
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/constants.py +7 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/functions.py +16 -7
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/query_set.py +247 -48
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/subquery.py +17 -5
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/surql_literal.py +9 -6
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/utils.py +180 -35
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/.gitignore +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/LICENSE +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/Makefile +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,96 @@ 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
|
+
|
|
8
98
|
## [0.28.0] - 2026-10-17
|
|
9
99
|
|
|
10
100
|
Query cache: a QuerySet serves its reads from a client-side cache with `cache(ttl)`, and every ORM
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.28.
|
|
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
|
|
@@ -273,23 +310,64 @@ await User.objects().filter(id__startswith="al").exec()
|
|
|
273
310
|
A model that aliases its identity through `primary_key` keeps that alias as an ordinary
|
|
274
311
|
column, so `filter(code="abc")` is a normal string comparison and is unaffected.
|
|
275
312
|
|
|
276
|
-
####
|
|
277
|
-
|
|
278
|
-
A filter value beginning with `$` is read as a reference to a **query variable**, not as data.
|
|
279
|
-
Use `Var(...)` to say so explicitly, and `$$` to escape a value that genuinely starts with a
|
|
280
|
-
dollar sign:
|
|
313
|
+
#### String filter values and `Var()`
|
|
281
314
|
|
|
282
315
|
```python
|
|
283
316
|
from surreal_orm_lite import Var
|
|
284
317
|
|
|
285
|
-
await User.objects().filter(
|
|
286
|
-
await User.objects().filter(
|
|
287
|
-
|
|
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
|
|
320
|
+
```
|
|
321
|
+
|
|
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
|
|
288
344
|
```
|
|
289
345
|
|
|
290
|
-
The
|
|
291
|
-
|
|
292
|
-
|
|
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`.
|
|
293
371
|
|
|
294
372
|
#### Model instances as filter values
|
|
295
373
|
|
|
@@ -1342,8 +1420,12 @@ else, a string containing a NUL character, an integer beyond 64 bits, a `Decimal
|
|
|
1342
1420
|
round or a zero, negative or oversized duration raises `TypeError` when you call `live()`, before
|
|
1343
1421
|
anything is sent. A `Var` must be supplied through `variables()` — an unbound reference would read
|
|
1344
1422
|
as `NONE` on every notification, so `age > $min_age` would match every record; it raises
|
|
1345
|
-
`SurrealDbError` instead
|
|
1346
|
-
|
|
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.
|
|
1347
1429
|
|
|
1348
1430
|
#### Diff mode
|
|
1349
1431
|
|
|
@@ -3346,7 +3428,8 @@ A statement with subqueries is one block, whose `LET`s bind each subquery once,
|
|
|
3346
3428
|
- **Reserved names**: `$_sq0`, `$_sq1`, … (`_sq<N>`) are the block's `LET`s and hide a
|
|
3347
3429
|
`variables()` value of the same name; a subquery can order by `_sqv` only when it selects `_sqv`
|
|
3348
3430
|
itself (`ValueError` otherwise).
|
|
3349
|
-
- `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).
|
|
3350
3433
|
|
|
3351
3434
|
#### Where subqueries apply
|
|
3352
3435
|
|
|
@@ -3408,8 +3491,7 @@ at the call):
|
|
|
3408
3491
|
- an inner `objects(tx=)` whose transaction is not the outer queryset's: `SurrealDbError`;
|
|
3409
3492
|
- an inner `variables()` binding a name of the statement to another value: `ValueError` (the two
|
|
3410
3493
|
values must have the same type and be equal: `1` and `True`, or `1` and `1.0`, differ);
|
|
3411
|
-
- an inner `
|
|
3412
|
-
(above): `ValueError`;
|
|
3494
|
+
- an inner `order_by()` on `_sqv` (above): `ValueError`;
|
|
3413
3495
|
- a subquery inside a list (`author__in=[Subquery(qs)]`): `ValueError`, give it as the whole value;
|
|
3414
3496
|
- `Q(...).to_sql()` called on its own with a subquery lookup: `ValueError` (only a QuerySet binds
|
|
3415
3497
|
a subquery);
|
|
@@ -3530,8 +3612,8 @@ Every ORM write removes the cached reads it can change, **before** its `post_*`
|
|
|
3530
3612
|
included.
|
|
3531
3613
|
- A read that **follows links** is removed by **any** ORM write: `fetch()`, a dotted path such as
|
|
3532
3614
|
`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.*"`
|
|
3534
|
-
|
|
3615
|
+
`select()` item that is not a plain field, such as `"author.*"` (the projection reads the linked
|
|
3616
|
+
record).
|
|
3535
3617
|
- A read of an **edge model** (`BaseSurrealEdge`) is removed by any delete: deleting a record
|
|
3536
3618
|
deletes the edges that point at it or from it.
|
|
3537
3619
|
- Inside `transaction()` the tables written are invalidated **at commit** (a failed commit too,
|
|
@@ -3553,8 +3635,7 @@ table's entries after such a change:
|
|
|
3553
3635
|
- what the server derives on its own: `DEFINE EVENT`, `REFERENCE … ON DELETE` (3.x), views
|
|
3554
3636
|
(`DEFINE TABLE … AS SELECT`), `PERMISSIONS` that read another table;
|
|
3555
3637
|
- 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)
|
|
3557
|
-
inside a `select()` expression;
|
|
3638
|
+
fields (over another table, the graph such as `count(<-likes)`, or the time);
|
|
3558
3639
|
- a table of relations read through a model that is not a `BaseSurrealEdge`.
|
|
3559
3640
|
|
|
3560
3641
|
```python
|
|
@@ -3772,7 +3853,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
3772
3853
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
3773
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
|
|
3774
3855
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
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.
|
|
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.
|
|
3776
3857
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
3777
3858
|
|
|
3778
3859
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -3878,6 +3959,9 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
3878
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 |
|
|
3879
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 |
|
|
3880
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) |
|
|
3881
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 |
|
|
3882
3966
|
|
|
3883
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.
|
|
@@ -129,6 +129,43 @@ results = await User.objects().query(
|
|
|
129
129
|
)
|
|
130
130
|
```
|
|
131
131
|
|
|
132
|
+
#### What `select()` accepts
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
await Book.objects().select("title", "price").exec() # field names
|
|
136
|
+
await Book.objects().select("title", "author.name").exec() # [{"title": "Dune", "author": {"name": "Ada"}}, …]
|
|
137
|
+
await Book.objects().select("title", "author.*").exec() # every field of the linked author
|
|
138
|
+
await Book.objects().select("*", "author.*").exec() # every field, the author's record included
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Each item is `*`, a field name (an aliased field by its Python name: its column is selected), a
|
|
142
|
+
dotted path into a nested object or through a record link, or such a path followed by `.*`. Names
|
|
143
|
+
are letters, digits and underscores, each part starting with a letter or an underscore, as in
|
|
144
|
+
`order_by()` and `values()`. Anything else — an expression, a function call, `AS`, `{…}` or
|
|
145
|
+
`[…]` — raises `ValueError` naming the item when `select()` is called, before any request; write a
|
|
146
|
+
computed projection with `query()` and bound parameters. Rows that do not validate as the model (a
|
|
147
|
+
link read as a record, a required field left out) come back as dicts keyed by Python names. On a
|
|
148
|
+
nested object that is not a link, `"meta.*"` gives the object on SurrealDB 3.x and its values as a
|
|
149
|
+
list on 2.x and the embedded engine.
|
|
150
|
+
|
|
151
|
+
#### `limit()` and `offset()`
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
users = await User.objects().order_by("name").limit(10).offset(20).exec()
|
|
155
|
+
User.objects().limit(int(size)) # a size read as text: convert it first
|
|
156
|
+
User.objects().limit("10") # TypeError: limit() takes a non-negative integer, got '10'
|
|
157
|
+
User.objects().offset(-1) # ValueError: offset() takes a non-negative integer, got -1
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Each takes a non-negative integer (`0` reads no record; an `IntEnum` member or an integer type
|
|
161
|
+
such as NumPy's `int64` gives its value). A value that is not an integer — a `bool`, a `str` such
|
|
162
|
+
as `"10"`, a `float`, `None` — raises `TypeError`, and a negative one or one above `2**63 - 1`
|
|
163
|
+
(SurrealQL's largest integer) `ValueError`, naming the method and the value, when `limit()` or
|
|
164
|
+
`offset()` is called, before any request; the value in place is kept. The same holds wherever the
|
|
165
|
+
queryset is read: `exec()`, `first()`, `get()`, `values(…).annotate(…)`, `cache()`, `as_of()` and
|
|
166
|
+
a subquery. The server may still refuse a large value when the read runs: SurrealDB 2.x and the
|
|
167
|
+
embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads it.
|
|
168
|
+
|
|
132
169
|
---
|
|
133
170
|
|
|
134
171
|
## Features
|
|
@@ -222,23 +259,64 @@ await User.objects().filter(id__startswith="al").exec()
|
|
|
222
259
|
A model that aliases its identity through `primary_key` keeps that alias as an ordinary
|
|
223
260
|
column, so `filter(code="abc")` is a normal string comparison and is unaffected.
|
|
224
261
|
|
|
225
|
-
####
|
|
226
|
-
|
|
227
|
-
A filter value beginning with `$` is read as a reference to a **query variable**, not as data.
|
|
228
|
-
Use `Var(...)` to say so explicitly, and `$$` to escape a value that genuinely starts with a
|
|
229
|
-
dollar sign:
|
|
262
|
+
#### String filter values and `Var()`
|
|
230
263
|
|
|
231
264
|
```python
|
|
232
265
|
from surreal_orm_lite import Var
|
|
233
266
|
|
|
234
|
-
await User.objects().filter(
|
|
235
|
-
await User.objects().filter(
|
|
236
|
-
|
|
267
|
+
await User.objects().filter(name="$admin").exec() # the string "$admin"
|
|
268
|
+
await User.objects().filter(age__gte=Var("min_age")).variables(min_age=21).exec() # … WHERE age >= $min_age
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
A string filter value is data, whatever it starts with: `filter(name="$admin")` compares `name`
|
|
272
|
+
with the string `"$admin"`, bound like any other value, wherever a filter applies: `filter()`, `Q`,
|
|
273
|
+
`get()`, `get_or_create()`, `update_or_create()`, `bulk_update()` by filter, subqueries and live
|
|
274
|
+
queries. `Var(...)` is the only way to reference a query variable, whose value `variables()`
|
|
275
|
+
gives.
|
|
276
|
+
|
|
277
|
+
Until v0.28.1 a value starting with `$` was read as a variable reference (deprecated since
|
|
278
|
+
v0.14.3), and `"$$admin"` was how to write the string `"$admin"`. That escape keeps its meaning,
|
|
279
|
+
deprecated: a filter value starting with `$$` loses one `$` (`"$$admin"` finds `"$admin"`: write
|
|
280
|
+
`"$admin"`), with a `DeprecationWarning`; an item of an `in` list never had the escape.
|
|
281
|
+
|
|
282
|
+
A call written for the old reading, such as `filter(age__lte="$max_age").variables(max_age=25)`,
|
|
283
|
+
now compares `age` with the string `"$max_age"`: a number sorts below a string, so `lt` and `lte`
|
|
284
|
+
match every number, and `gt`, `gte` and `exact` none. When a string filter value is exactly `$`
|
|
285
|
+
followed by the name of a variable that `variables()` gives, the ORM keeps it as data and emits a
|
|
286
|
+
`UserWarning` that says to write `Var("max_age")`, once per read, pointing at your line.
|
|
287
|
+
|
|
288
|
+
`Var()` also reads the parameters SurrealDB sets for each session, without `variables()`: `$auth`
|
|
289
|
+
(the signed-in record user), `$access`, `$session` and `$token`, in reads and in live queries.
|
|
290
|
+
|
|
291
|
+
```python
|
|
292
|
+
mine = await Doc.objects().filter(owner=Var("auth")).exec() # … WHERE owner = $auth
|
|
237
293
|
```
|
|
238
294
|
|
|
239
|
-
The
|
|
240
|
-
|
|
241
|
-
|
|
295
|
+
The string `"$auth"` is data: `filter(owner="$auth")` compares `owner` with the string `"$auth"`,
|
|
296
|
+
so a read keeps only the records whose `owner` is that string, and a live query notifies only for
|
|
297
|
+
those. A string filter value that is exactly `"$auth"`, `"$access"`, `"$session"` or `"$token"`
|
|
298
|
+
emits a `UserWarning` naming the `Var(...)` that reads the parameter, once per read, pointing at
|
|
299
|
+
your line. Any other string, such as `"$x"` with no variable `x`, is data the caller meant: no
|
|
300
|
+
warning. On an edge's `in` and `out`, which hold record ids, such a string is not a record id and
|
|
301
|
+
raises `ValueError`; when it names a variable of `variables()` or one of these parameters, the
|
|
302
|
+
message names the `Var(...)` to write.
|
|
303
|
+
|
|
304
|
+
`get_or_create()` and `update_or_create()` look up their criteria and write the `exact` ones on
|
|
305
|
+
create, so there such a string is refused: `update_or_create(owner="$auth", defaults=…)` would find
|
|
306
|
+
and write the record whose `owner` is the string `"$auth"`, the same record for every record user,
|
|
307
|
+
and `members__contains="$auth"` would look for the string. A criterion that is exactly `$` followed
|
|
308
|
+
by the name of a variable of `variables()` or of one of these parameters raises `SurrealDbError`
|
|
309
|
+
before any request, whatever its lookup, saying to pass the actual value as the criterion: the
|
|
310
|
+
record id, or the value itself. `Var("auth")` finds the signed-in user's record
|
|
311
|
+
(`get_or_create(owner=Var("auth"))` returns it) but cannot be written: with no record to return, it
|
|
312
|
+
raises `SurrealDbError`. Any other string, such as `"$admin"`, is looked up and written as it is. On
|
|
313
|
+
an edge's `in` and `out`, such a criterion raises the `ValueError` above.
|
|
314
|
+
|
|
315
|
+
`variables()` refuses these four names with a `ValueError`: SurrealDB sets them for each session
|
|
316
|
+
and refuses a query variable of that name. To pass your own value, give it another name, or pass
|
|
317
|
+
the value itself in the filter: `filter(token=Var("device_token")).variables(device_token=t)` or
|
|
318
|
+
`filter(token=t)`, in a read or a live query. `Var("token")` without `variables()` reads SurrealDB's
|
|
319
|
+
`$token`.
|
|
242
320
|
|
|
243
321
|
#### Model instances as filter values
|
|
244
322
|
|
|
@@ -1291,8 +1369,12 @@ else, a string containing a NUL character, an integer beyond 64 bits, a `Decimal
|
|
|
1291
1369
|
round or a zero, negative or oversized duration raises `TypeError` when you call `live()`, before
|
|
1292
1370
|
anything is sent. A `Var` must be supplied through `variables()` — an unbound reference would read
|
|
1293
1371
|
as `NONE` on every notification, so `age > $min_age` would match every record; it raises
|
|
1294
|
-
`SurrealDbError` instead
|
|
1295
|
-
|
|
1372
|
+
`SurrealDbError` instead. SurrealDB's own parameters need no `variables()`: `Var("auth")` (and
|
|
1373
|
+
`$access`, `$session`, `$token`) stays a reference the server reads on every notification, so
|
|
1374
|
+
`filter(owner=Var("auth"))` streams the signed-in record user's own records, on both lines; the
|
|
1375
|
+
string `"$auth"` is data, written as `'$auth'` (see
|
|
1376
|
+
[String filter values and `Var()`](#string-filter-values-and-var)). Every other query keeps binding
|
|
1377
|
+
parameters.
|
|
1296
1378
|
|
|
1297
1379
|
#### Diff mode
|
|
1298
1380
|
|
|
@@ -3295,7 +3377,8 @@ A statement with subqueries is one block, whose `LET`s bind each subquery once,
|
|
|
3295
3377
|
- **Reserved names**: `$_sq0`, `$_sq1`, … (`_sq<N>`) are the block's `LET`s and hide a
|
|
3296
3378
|
`variables()` value of the same name; a subquery can order by `_sqv` only when it selects `_sqv`
|
|
3297
3379
|
itself (`ValueError` otherwise).
|
|
3298
|
-
- `limit()` and `offset()` of a subquery take
|
|
3380
|
+
- `limit()` and `offset()` of a subquery take a non-negative integer, as everywhere (`TypeError` or
|
|
3381
|
+
`ValueError` when they are called).
|
|
3299
3382
|
|
|
3300
3383
|
#### Where subqueries apply
|
|
3301
3384
|
|
|
@@ -3357,8 +3440,7 @@ at the call):
|
|
|
3357
3440
|
- an inner `objects(tx=)` whose transaction is not the outer queryset's: `SurrealDbError`;
|
|
3358
3441
|
- an inner `variables()` binding a name of the statement to another value: `ValueError` (the two
|
|
3359
3442
|
values must have the same type and be equal: `1` and `True`, or `1` and `1.0`, differ);
|
|
3360
|
-
- an inner `
|
|
3361
|
-
(above): `ValueError`;
|
|
3443
|
+
- an inner `order_by()` on `_sqv` (above): `ValueError`;
|
|
3362
3444
|
- a subquery inside a list (`author__in=[Subquery(qs)]`): `ValueError`, give it as the whole value;
|
|
3363
3445
|
- `Q(...).to_sql()` called on its own with a subquery lookup: `ValueError` (only a QuerySet binds
|
|
3364
3446
|
a subquery);
|
|
@@ -3479,8 +3561,8 @@ Every ORM write removes the cached reads it can change, **before** its `post_*`
|
|
|
3479
3561
|
included.
|
|
3480
3562
|
- A read that **follows links** is removed by **any** ORM write: `fetch()`, a dotted path such as
|
|
3481
3563
|
`filter(**{"author.name": …})` or `order_by("author.name")` (in a subquery too), and a
|
|
3482
|
-
`select()` item that is not a plain field, such as `"author.*"`
|
|
3483
|
-
|
|
3564
|
+
`select()` item that is not a plain field, such as `"author.*"` (the projection reads the linked
|
|
3565
|
+
record).
|
|
3484
3566
|
- A read of an **edge model** (`BaseSurrealEdge`) is removed by any delete: deleting a record
|
|
3485
3567
|
deletes the edges that point at it or from it.
|
|
3486
3568
|
- Inside `transaction()` the tables written are invalidated **at commit** (a failed commit too,
|
|
@@ -3502,8 +3584,7 @@ table's entries after such a change:
|
|
|
3502
3584
|
- what the server derives on its own: `DEFINE EVENT`, `REFERENCE … ON DELETE` (3.x), views
|
|
3503
3585
|
(`DEFINE TABLE … AS SELECT`), `PERMISSIONS` that read another table;
|
|
3504
3586
|
- values computed when the read runs: a `DEFINE PARAM` read with `Var()`, `<future>`/`COMPUTED`
|
|
3505
|
-
fields (over another table, the graph such as `count(<-likes)`, or the time)
|
|
3506
|
-
inside a `select()` expression;
|
|
3587
|
+
fields (over another table, the graph such as `count(<-likes)`, or the time);
|
|
3507
3588
|
- a table of relations read through a model that is not a `BaseSurrealEdge`.
|
|
3508
3589
|
|
|
3509
3590
|
```python
|
|
@@ -3721,7 +3802,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
3721
3802
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
3722
3803
|
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
|
|
3723
3804
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
3724
|
-
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.
|
|
3805
|
+
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.
|
|
3725
3806
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
3726
3807
|
|
|
3727
3808
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -3827,6 +3908,9 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
3827
3908
|
| 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 |
|
|
3828
3909
|
| 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 |
|
|
3829
3910
|
| 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 |
|
|
3911
|
+
| `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) |
|
|
3912
|
+
| `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 |
|
|
3913
|
+
| `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) |
|
|
3830
3914
|
| 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 |
|
|
3831
3915
|
|
|
3832
3916
|
> **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.
|
|
@@ -27,3 +27,10 @@ GEOMETRY_LOOKUP_OPERATORS = {
|
|
|
27
27
|
"outside": "OUTSIDE",
|
|
28
28
|
"intersects": "INTERSECTS",
|
|
29
29
|
}
|
|
30
|
+
|
|
31
|
+
#: SurrealDB's session parameters (v0.28.1): ``$access``, ``$auth``, ``$session`` and ``$token``. The server sets them
|
|
32
|
+
#: for every session and refuses ``LET`` on them (its protected parameters; measured on 2.7.0 and 3.3.4), so a filter
|
|
33
|
+
#: reads them with ``Var("auth")`` and no ``variables()``. A ``str`` filter value ``"$auth"`` is data, with a
|
|
34
|
+
#: ``UserWarning`` (``utils.warn_on_variable_names``). The statement parameters (``$this``, ``$parent``, ``$value``,
|
|
35
|
+
#: ``$before``, ``$after``, ``$input``, ``$event``) and the 1.x ``$scope`` are not session values: not listed.
|
|
36
|
+
SESSION_PARAMETERS = frozenset({"access", "auth", "session", "token"})
|
|
@@ -233,19 +233,28 @@ def computed(expression: "str | SurrealFunc") -> Any:
|
|
|
233
233
|
|
|
234
234
|
|
|
235
235
|
class Var:
|
|
236
|
-
"""
|
|
236
|
+
"""A reference to a **bound query variable** in a filter (v0.14.3): the only one.
|
|
237
237
|
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
238
|
+
A string filter value is data, whatever it starts with: ``filter(name="$admin")`` compares
|
|
239
|
+
``name`` with the string ``"$admin"``. ``Var`` is how a filter reads a query variable
|
|
240
|
+
instead::
|
|
241
241
|
|
|
242
242
|
from surreal_orm_lite import Var
|
|
243
243
|
|
|
244
244
|
qs = User.objects().filter(age__gte=Var("min_age")) # … WHERE age >= $min_age
|
|
245
|
+
await qs.variables(min_age=21).exec()
|
|
245
246
|
|
|
246
|
-
The variable itself is supplied
|
|
247
|
-
|
|
248
|
-
|
|
247
|
+
The variable itself is supplied with ``variables()``. A leading ``$`` in the name is
|
|
248
|
+
accepted: ``Var("$min_age")`` is ``Var("min_age")``.
|
|
249
|
+
|
|
250
|
+
``Var`` also reads the parameters SurrealDB sets for the session — ``$auth`` (the signed-in
|
|
251
|
+
record user), ``$access``, ``$session``, ``$token`` — with no ``variables()``, in a read and in
|
|
252
|
+
a live query::
|
|
253
|
+
|
|
254
|
+
mine = await Doc.objects().filter(owner=Var("auth")).exec() # … WHERE owner = $auth
|
|
255
|
+
|
|
256
|
+
The string ``"$auth"`` is data: ``filter(owner="$auth")`` compares ``owner`` with the string
|
|
257
|
+
``"$auth"``, with a ``UserWarning`` naming ``Var("auth")``.
|
|
249
258
|
"""
|
|
250
259
|
|
|
251
260
|
__slots__ = ("name",)
|