surreal-orm-lite 0.26.0__tar.gz → 0.27.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/CHANGELOG.md +97 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/PKG-INFO +237 -4
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/README.md +236 -3
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/__init__.py +3 -1
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/_sdk.py +6 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/q.py +14 -3
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/query_set.py +453 -108
- surreal_orm_lite-0.27.0/src/surreal_orm_lite/subquery.py +423 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/utils.py +28 -2
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/.gitignore +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/LICENSE +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/Makefile +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.26.0 → surreal_orm_lite-0.27.0}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,103 @@ 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.27.0] - 2026-10-16
|
|
9
|
+
|
|
10
|
+
Subqueries: a QuerySet filters another, as `Subquery(qs)` or the queryset itself, compiled to a
|
|
11
|
+
sub-`SELECT` the server runs inside the outer statement: one request, one consistent read, every
|
|
12
|
+
inner value bound. The fifth minor of Tier 2.
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- **`Subquery(qs)`**, exported from `surreal_orm_lite` (the full SurrealDB-ORM's name), and a
|
|
17
|
+
QuerySet given directly as a filter value, in `filter()` and in `Q` (`&`, `|`, `~`, any nesting).
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from surreal_orm_lite import Q, Subquery
|
|
21
|
+
|
|
22
|
+
active = Person.objects().filter(active=True)
|
|
23
|
+
posts = await Post.objects().filter(author__in=Subquery(active)).exec()
|
|
24
|
+
same = await Post.objects().filter(author__in=active).exec() # a QuerySet is a subquery
|
|
25
|
+
|
|
26
|
+
best = Post.objects().select("score").order_by("-score").limit(1)
|
|
27
|
+
top = await Post.objects().filter(score=Subquery(best)).exec() # compared with its first value
|
|
28
|
+
|
|
29
|
+
inactive = Person.objects().filter(active=False)
|
|
30
|
+
mixed = await Post.objects().filter(Q(author__in=inactive) | Q(score__gte=9)).exec()
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- **Lookups.** `in`, `not_in`, `containsall` and `containsany` compare the field with all the
|
|
34
|
+
subquery's values; `exact` (no suffix), `gt`, `gte`, `lt`, `lte`, `contains` and `not_contains`
|
|
35
|
+
with its first value (order the subquery to choose it). A first-value lookup on an empty
|
|
36
|
+
subquery matches no record, and `~Q(...)` of it every record; for `in`, an empty subquery is an
|
|
37
|
+
empty list.
|
|
38
|
+
- **What the inner queryset selects**: its record ids without `select()` (`SELECT VALUE id`), or
|
|
39
|
+
the values of the one field given to `select()` (an aliased field compiles its column). Its
|
|
40
|
+
`filter()`, `Q`, `nearby()`, `order_by()`, `limit()`, `offset()` and `variables()` apply; its
|
|
41
|
+
`fetch()` is ignored, as in the full ORM. Values are compared as stored, never converted: to
|
|
42
|
+
match records, select `id` or a record link.
|
|
43
|
+
- **Where it applies**: `exec()`, `first()`, `get()` with filters, `exists()`, `count()`, `sum()`,
|
|
44
|
+
`avg()`, `min()`, `max()`, `values(…).annotate(…)` and `annotate(GeoDistance)`; the writes by
|
|
45
|
+
filter `bulk_update()`, `bulk_delete()` and `QuerySet.patch()`; the lookups of `get_or_create()`
|
|
46
|
+
and `update_or_create()`. Subqueries nest. In `Model.objects(tx=tx)` the statement runs in the
|
|
47
|
+
transaction, and an interactive transaction's subquery sees its uncommitted writes. Under
|
|
48
|
+
`as_of()` every subquery reads at the same moment. `live()` and `watch()` write the sub-SELECT
|
|
49
|
+
inline, and the server evaluates it again on every change. `changes()` refuses `filter()`, so
|
|
50
|
+
subqueries too.
|
|
51
|
+
- **Refusals before any request** (`live()` and `watch()` at the call). `ValueError`: a lookup
|
|
52
|
+
that takes no subquery (`isnull`, `like`, `ilike`, `startswith`, `endswith`, `match`, `regex`,
|
|
53
|
+
`inside`, `outside`, `intersects`), a queryset that is its own subquery, an inner `values()`,
|
|
54
|
+
`annotate()` or `select()` of several fields, an inner `limit()` or `offset()` that is not an
|
|
55
|
+
`int >= 0`, an inner `order_by()` on `_sqv` it does not select, an inner `variables()` binding a
|
|
56
|
+
name of the statement to another value, a subquery inside a list, `Q(...).to_sql()` called on its
|
|
57
|
+
own with a subquery, and `bulk_update(score=Subquery(qs))`. `SurrealDbError`: an inner `as_of()`
|
|
58
|
+
(call it on the outer queryset), an inner `objects(tx=)` whose transaction is not the outer
|
|
59
|
+
one's, and a subquery as an `exact` criterion or a `defaults=` value of `get_or_create()` or
|
|
60
|
+
`update_or_create()`. `TypeError`: `Subquery(x)` for anything but a QuerySet.
|
|
61
|
+
- README section 28, "Subqueries (`Subquery`)" (what a subquery selects, the lookups, ordered and
|
|
62
|
+
limited subqueries, where subqueries apply, what they cannot do, a note for users of the full
|
|
63
|
+
SurrealDB-ORM), a bullet in the supported lookups, a `Q` example in section 5, four rows in the
|
|
64
|
+
2.x/3.x behaviour table, and the example notebook `examples/v0.27.0_subqueries.ipynb`.
|
|
65
|
+
|
|
66
|
+
### Changed
|
|
67
|
+
|
|
68
|
+
- A QuerySet given as a filter value is now a subquery. v0.26.x refused it: `in` and `not_in`
|
|
69
|
+
raised `ValueError` ("requires an iterable") and the other lookups failed when the SDK encoded
|
|
70
|
+
the request. Every call that worked in v0.26.x behaves the same.
|
|
71
|
+
- `Q.to_sql()` gains a keyword-only `subqueries` parameter (default `None`), the compiler of the
|
|
72
|
+
statement the QuerySet sends; a `Q` compiled on its own refuses a subquery lookup.
|
|
73
|
+
|
|
74
|
+
### Notes
|
|
75
|
+
|
|
76
|
+
- **One statement per request, a block of `LET`s**:
|
|
77
|
+
`{ LET $_sq0 = (SELECT VALUE id FROM Person WHERE active = $_f0); (SELECT * FROM Post WHERE author IN $_sq0) };`.
|
|
78
|
+
Each subquery is bound once, innermost first, because SurrealDB 3.2 and later can return wrong
|
|
79
|
+
rows for an inline sub-SELECT with `ORDER BY` and `LIMIT`
|
|
80
|
+
([surrealdb/surrealdb#7470](https://github.com/surrealdb/surrealdb/issues/7470)), and because the
|
|
81
|
+
official SDK's `query()` returns the first statement's result only, so the full ORM's `LET`
|
|
82
|
+
prelude (two statements) does not fit. An ordered subquery selects its column as `_sqv` with its
|
|
83
|
+
order fields: SurrealDB 2.x refuses to order a one-column sub-SELECT by another field. `$_sq0`,
|
|
84
|
+
`$_sq1`, … are reserved in such a statement and hide a `variables()` value of the same name.
|
|
85
|
+
- **A first-value lookup on an empty subquery matches no record**: SurrealDB alone would compare
|
|
86
|
+
with `array::first([])`, which is `NONE`, and `score > NONE` holds for every record, so the ORM
|
|
87
|
+
guards the comparison. The full SurrealDB-ORM matches every record there.
|
|
88
|
+
- **A subquery table that does not exist reads as empty**, like any missing table. SurrealDB 2.x
|
|
89
|
+
and the embedded engine read it so in the same request. On SurrealDB 3.x the ORM asks the server
|
|
90
|
+
whether the table exists and, once it confirms the table does not, sends the statement again
|
|
91
|
+
with that subquery empty: three requests, and only then. Any other error, even one quoting
|
|
92
|
+
"does not exist", is relayed. On 3.x a write by filter in a transaction fails with the server's
|
|
93
|
+
error, and `live()` raises `SurrealDbNotFoundError` before it starts (3.x would accept the live
|
|
94
|
+
query and never notify).
|
|
95
|
+
- **Transactions**: a buffered transaction (2.x, or HTTP) still cannot read, and applies writes by
|
|
96
|
+
filter at commit. Build the inner queryset with the same `objects(tx=)`, or with none.
|
|
97
|
+
- **Time travel**: without versioned storage, a subquery read under `as_of()` raises v0.26.0's
|
|
98
|
+
`SurrealDbError`; SurrealDB 3.1.5 raises the server's own `ThrownError` instead.
|
|
99
|
+
- Not available yet: `annotate(x=Subquery(...))`, correlated subqueries (`OuterRef`, `$parent`)
|
|
100
|
+
and `Exists`.
|
|
101
|
+
- **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, in memory and on versioned
|
|
102
|
+
storage, and on the embedded engine, plus 3.1.5 for backward compatibility (identical except the
|
|
103
|
+
time-travel error above).
|
|
104
|
+
|
|
8
105
|
## [0.26.0] - 2026-10-16
|
|
9
106
|
|
|
10
107
|
Time travel: a QuerySet reads a model's records as they were at a past moment, with
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.27.0
|
|
4
4
|
Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
|
|
5
5
|
Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
|
|
6
6
|
Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
|
|
@@ -224,6 +224,7 @@ results = await User.objects().query(
|
|
|
224
224
|
| Geospatial fields (nearby, distance, spatial lookups) | ✅ |
|
|
225
225
|
| Embedded engine (mem://, surrealkv://) & test fixtures | ✅ |
|
|
226
226
|
| Time travel (`as_of()`, versioned storage) | ✅ |
|
|
227
|
+
| Subqueries (`Subquery`, a QuerySet as a filter value) | ✅ |
|
|
227
228
|
|
|
228
229
|
### Supported Filter Lookups
|
|
229
230
|
|
|
@@ -237,6 +238,7 @@ results = await User.objects().query(
|
|
|
237
238
|
- `match`, `regex`
|
|
238
239
|
- `isnull`
|
|
239
240
|
- `inside`, `outside`, `intersects` (geometry values: see [section 25](#25-geospatial-fields))
|
|
241
|
+
- a subquery — `Subquery(qs)` or the queryset itself — as the value of `in`, `not_in`, `containsall`, `containsany` (all its values) or `exact`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains` (its first value): see [section 28](#28-subqueries-subquery)
|
|
240
242
|
|
|
241
243
|
Filter values on rich fields must be typed: `filter(trial__gte=timedelta(days=7))`, not
|
|
242
244
|
`"7d"`. Strings are not converted (see [section 24](#24-rich-field-types)).
|
|
@@ -354,6 +356,13 @@ results = await User.objects().filter(
|
|
|
354
356
|
).exec()
|
|
355
357
|
```
|
|
356
358
|
|
|
359
|
+
Since v0.27.0 a lookup inside a `Q` takes a subquery as `filter()` does (see
|
|
360
|
+
[section 28](#28-subqueries-subquery)), here with `admins = User.objects().filter(role="admin")`:
|
|
361
|
+
|
|
362
|
+
```python
|
|
363
|
+
posts = await Post.objects().filter(Q(author__in=Subquery(admins)) | Q(score__gte=9)).exec()
|
|
364
|
+
```
|
|
365
|
+
|
|
357
366
|
### 6. Bulk Operations
|
|
358
367
|
|
|
359
368
|
```python
|
|
@@ -3215,6 +3224,224 @@ not exist then), and a `CREATE` of an id that exists raises.
|
|
|
3215
3224
|
- **A snapshot is never `==` the current instance**, even with identical fields: compare
|
|
3216
3225
|
`model_dump()`s.
|
|
3217
3226
|
|
|
3227
|
+
### 28. Subqueries (`Subquery`)
|
|
3228
|
+
|
|
3229
|
+
Since v0.27.0 a QuerySet can filter another: `Subquery(qs)`, or the queryset itself, is the value
|
|
3230
|
+
of a lookup in `filter()` or `Q`. The ORM sends **one request**: the server runs the inner
|
|
3231
|
+
queryset inside the outer statement, so both read the same state (one consistent read), and the
|
|
3232
|
+
inner queryset's values are bound like any filter value.
|
|
3233
|
+
|
|
3234
|
+
```python
|
|
3235
|
+
from surrealdb import RecordID
|
|
3236
|
+
|
|
3237
|
+
from surreal_orm_lite import BaseSurrealModel, Subquery
|
|
3238
|
+
|
|
3239
|
+
|
|
3240
|
+
class Person(BaseSurrealModel):
|
|
3241
|
+
id: str | None = None
|
|
3242
|
+
name: str
|
|
3243
|
+
active: bool = True
|
|
3244
|
+
age: int = 0
|
|
3245
|
+
|
|
3246
|
+
|
|
3247
|
+
class Post(BaseSurrealModel):
|
|
3248
|
+
id: str | None = None
|
|
3249
|
+
title: str
|
|
3250
|
+
author: RecordID | None = None # a record link to a Person
|
|
3251
|
+
score: int = 0
|
|
3252
|
+
|
|
3253
|
+
|
|
3254
|
+
people = [("ada", "Ada", True, 36), ("bob", "Bob", True, 50), ("cy", "Cy", False, 20)]
|
|
3255
|
+
for key, name, is_active, age in people:
|
|
3256
|
+
await Person(id=key, name=name, active=is_active, age=age).save()
|
|
3257
|
+
for key, title, author, score in [
|
|
3258
|
+
("p1", "one", "ada", 5),
|
|
3259
|
+
("p2", "two", "bob", 8),
|
|
3260
|
+
("p3", "three", "cy", 2),
|
|
3261
|
+
("p4", "four", "ada", 9),
|
|
3262
|
+
("p5", "five", None, 1), # no author
|
|
3263
|
+
]:
|
|
3264
|
+
link = RecordID("Person", author) if author else None
|
|
3265
|
+
await Post(id=key, title=title, author=link, score=score).save()
|
|
3266
|
+
|
|
3267
|
+
active = Person.objects().filter(active=True)
|
|
3268
|
+
posts = await Post.objects().filter(author__in=Subquery(active)).exec() # p1, p2, p4
|
|
3269
|
+
same = await Post.objects().filter(author__in=active).exec() # p1, p2, p4 (a QuerySet is a subquery)
|
|
3270
|
+
```
|
|
3271
|
+
|
|
3272
|
+
#### What a subquery selects
|
|
3273
|
+
|
|
3274
|
+
The inner queryset gives the outer filter **one list of values**: without `select()`, the ids of
|
|
3275
|
+
its records (`SELECT VALUE id`); with `select("field")`, the values of that one field (an aliased
|
|
3276
|
+
field compiles its column). Here the subquery gives the record links the posts hold:
|
|
3277
|
+
|
|
3278
|
+
```python
|
|
3279
|
+
top_authors = Post.objects().filter(score__gt=8).select("author")
|
|
3280
|
+
writers = await Person.objects().filter(id__in=top_authors).exec() # ada
|
|
3281
|
+
```
|
|
3282
|
+
|
|
3283
|
+
`filter()`, `Q`, `nearby()`, `order_by()`, `limit()`, `offset()` and `variables()` apply to the
|
|
3284
|
+
inner queryset, and `fetch()` on the inner queryset is ignored, as in the full ORM. `select()` of
|
|
3285
|
+
several fields, `values()` and `annotate()` raise `ValueError`: a list of objects would match
|
|
3286
|
+
nothing.
|
|
3287
|
+
|
|
3288
|
+
Values are compared as stored, never converted: to match records, select `id` or a record link (a
|
|
3289
|
+
`"table:key"` string never equals a record id). A record without the selected field gives `NONE`,
|
|
3290
|
+
which `in` matches with a record whose field is missing, as a list holding `None` does:
|
|
3291
|
+
`Post.objects().filter(author__in=Post.objects().select("author"))` returns p5 too, and
|
|
3292
|
+
`author__not_in=active` keeps it.
|
|
3293
|
+
|
|
3294
|
+
#### Lookups
|
|
3295
|
+
|
|
3296
|
+
| Lookup | Compares the field with |
|
|
3297
|
+
| --------------------------------------------- | ----------------------------------------------------------- |
|
|
3298
|
+
| `in`, `not_in` | all the subquery's values: equal to one of them, or to none |
|
|
3299
|
+
| `containsall`, `containsany` | all its values: the array field holds all of them, or any |
|
|
3300
|
+
| `exact` (no suffix), `gt`, `gte`, `lt`, `lte` | its **first** value |
|
|
3301
|
+
| `contains`, `not_contains` | its first value: the array field holds it, or lacks it |
|
|
3302
|
+
|
|
3303
|
+
Order the subquery to choose its first value. A first-value lookup on an empty subquery matches
|
|
3304
|
+
**no record**, and `~Q(...)` of it every record: SurrealDB alone would compare with
|
|
3305
|
+
`array::first([])`, which is `NONE`, and `score > NONE` holds for every record, so the ORM guards
|
|
3306
|
+
the comparison (`$_sq0 != [] AND …`). For `in`, an empty subquery is an empty list: `in` matches
|
|
3307
|
+
no record, `not_in` every record. `isnull`, `like`, `ilike`, `startswith`, `endswith`, `match`,
|
|
3308
|
+
`regex`, `inside`, `outside` and `intersects` raise `ValueError` with a subquery.
|
|
3309
|
+
|
|
3310
|
+
```python
|
|
3311
|
+
from surreal_orm_lite import Q
|
|
3312
|
+
|
|
3313
|
+
others = await Post.objects().filter(author__not_in=active).exec() # p3, p5 (p5 has no author)
|
|
3314
|
+
how_many = await Post.objects().filter(author__not_in=active).count() # 2
|
|
3315
|
+
|
|
3316
|
+
best = Post.objects().select("score").order_by("-score").limit(1)
|
|
3317
|
+
top = await Post.objects().filter(score=Subquery(best)).exec() # p4 (the top score, 9)
|
|
3318
|
+
|
|
3319
|
+
nothing = Post.objects().filter(score__gt=100).select("score")
|
|
3320
|
+
above = await Post.objects().filter(score__gt=Subquery(nothing)).exec() # []
|
|
3321
|
+
not_above = await Post.objects().filter(~Q(score__gt=Subquery(nothing))).exec() # p1, p2, p3, p4, p5
|
|
3322
|
+
```
|
|
3323
|
+
|
|
3324
|
+
#### Ordered and limited subqueries
|
|
3325
|
+
|
|
3326
|
+
`order_by()`, `limit()` and `offset()` choose the values a subquery gives:
|
|
3327
|
+
|
|
3328
|
+
```python
|
|
3329
|
+
oldest = Person.objects().filter(active=True).order_by("-age").limit(1)
|
|
3330
|
+
theirs = await Post.objects().filter(author__in=oldest).exec() # p2 (Bob is the oldest active person)
|
|
3331
|
+
```
|
|
3332
|
+
|
|
3333
|
+
A statement with subqueries is one block, whose `LET`s bind each subquery once, innermost first:
|
|
3334
|
+
|
|
3335
|
+
```sql
|
|
3336
|
+
{ LET $_sq0 = (SELECT id AS _sqv, age FROM Person WHERE active = $_f0 ORDER BY age DESC LIMIT 1)._sqv; (SELECT * FROM Post WHERE author IN $_sq0) };
|
|
3337
|
+
```
|
|
3338
|
+
|
|
3339
|
+
- **Why a `LET`**: SurrealDB 3.2 and later can return wrong rows for an inline sub-SELECT with
|
|
3340
|
+
`ORDER BY` and `LIMIT`, which gives its value to the first outer record only
|
|
3341
|
+
([surrealdb/surrealdb#7470](https://github.com/surrealdb/surrealdb/issues/7470)). Bound once,
|
|
3342
|
+
the subquery is right on every line, and the server runs it once instead of once per record.
|
|
3343
|
+
- **Why `_sqv`**: an ordered subquery selects its column as `_sqv`, with its order fields, and
|
|
3344
|
+
reads `._sqv` back: SurrealDB 2.x refuses to order a sub-SELECT of one column by another field.
|
|
3345
|
+
- **Reserved names**: `$_sq0`, `$_sq1`, … (`_sq<N>`) are the block's `LET`s and hide a
|
|
3346
|
+
`variables()` value of the same name; a subquery can order by `_sqv` only when it selects `_sqv`
|
|
3347
|
+
itself (`ValueError` otherwise).
|
|
3348
|
+
- `limit()` and `offset()` of a subquery take an `int >= 0` (`ValueError` otherwise).
|
|
3349
|
+
|
|
3350
|
+
#### Where subqueries apply
|
|
3351
|
+
|
|
3352
|
+
Every read honours a subquery (`exec()`, `first()`, `get()` with filters, `exists()`, `count()`,
|
|
3353
|
+
`sum()`, `avg()`, `min()`, `max()`, `values(…).annotate(…)`, `annotate(GeoDistance)`), and so do
|
|
3354
|
+
the writes by filter (`bulk_update()`, `bulk_delete()`, `QuerySet.patch()`) and the lookups of
|
|
3355
|
+
`get_or_create()` and `update_or_create()`. Subqueries nest, and combine with `Q` (`&`, `|`, `~`):
|
|
3356
|
+
|
|
3357
|
+
```python
|
|
3358
|
+
from surreal_orm_lite import Count
|
|
3359
|
+
|
|
3360
|
+
wrote_a_top_post = Person.objects().filter(id__in=top_authors)
|
|
3361
|
+
by_writers = await Post.objects().filter(author__in=wrote_a_top_post).exec() # p1, p4
|
|
3362
|
+
|
|
3363
|
+
inactive = Person.objects().filter(active=False)
|
|
3364
|
+
mixed = await Post.objects().filter(Q(author__in=inactive) | Q(score__gte=9)).exec() # p3, p4
|
|
3365
|
+
|
|
3366
|
+
total = await Post.objects().filter(author__in=active).sum("score") # 22
|
|
3367
|
+
per_author = Post.objects().filter(author__in=active).values("author").annotate(n=Count())
|
|
3368
|
+
groups = await per_author.exec() # ada: 2, bob: 1
|
|
3369
|
+
|
|
3370
|
+
updated = await Post.objects().filter(author__in=inactive).bulk_update(score=0) # 1
|
|
3371
|
+
post, created = await Post.objects().get_or_create(author__in=active, title="one") # p1, False
|
|
3372
|
+
```
|
|
3373
|
+
|
|
3374
|
+
- **Transactions**: in `Model.objects(tx=tx)` the statement runs in the transaction. An
|
|
3375
|
+
interactive transaction (SurrealDB 3.x over WebSocket) reads its own uncommitted writes in the
|
|
3376
|
+
subquery too; a buffered one (2.x, or HTTP) still cannot read, and applies writes by filter at
|
|
3377
|
+
commit. Build the inner queryset with the same `objects(tx=)`, or with none.
|
|
3378
|
+
- **Live queries**: `live()` and `watch()` write the sub-SELECT inline in the `LIVE SELECT`, its
|
|
3379
|
+
values as literals, and the server evaluates it again on every change: a post created once its
|
|
3380
|
+
author is active notifies, even when the author became active after the live query started.
|
|
3381
|
+
Before it starts, a live query reads each subquery table (one request): SurrealDB 3.x would
|
|
3382
|
+
accept a live query whose subquery table does not exist and never notify, so the ORM raises
|
|
3383
|
+
`SurrealDbNotFoundError` there; 2.x reads that table as empty.
|
|
3384
|
+
- **Time travel**: under `as_of()` every subquery reads at the same moment (the ORM gives it the
|
|
3385
|
+
moment's `VERSION` and the per-record check of [section 27](#27-time-travel-as_of)). Without
|
|
3386
|
+
versioned storage the read raises section 27's `SurrealDbError`; SurrealDB 3.1.5 raises its own
|
|
3387
|
+
`ThrownError` ("Failed to scan record") instead.
|
|
3388
|
+
- **`changes()`** refuses `filter()`, so subqueries too.
|
|
3389
|
+
- **A subquery table that does not exist** reads as empty, as the ORM reads any missing table.
|
|
3390
|
+
SurrealDB 2.x and the embedded engine read it so in the same request. SurrealDB 3.x raises: the
|
|
3391
|
+
ORM then asks the server whether that table exists (a table probe) and, once the server confirms
|
|
3392
|
+
it does not, sends the statement again with that subquery empty: three requests (statement,
|
|
3393
|
+
table probe, re-send) for one missing table, and only then. Any other error, even one whose
|
|
3394
|
+
text quotes "The table '…' does not exist", is the server's own: it is relayed, never read as
|
|
3395
|
+
empty. On 3.x a write by filter inside a transaction fails with the server's error
|
|
3396
|
+
(`SurrealDbError`), as any failed write in a transaction does.
|
|
3397
|
+
|
|
3398
|
+
#### What a subquery cannot do
|
|
3399
|
+
|
|
3400
|
+
Each of these raises when the outer queryset compiles, before any request (`live()` and `watch()`
|
|
3401
|
+
at the call):
|
|
3402
|
+
|
|
3403
|
+
- a lookup other than the eleven above (`isnull`, `like`, `startswith`, `inside`, …): `ValueError`;
|
|
3404
|
+
- a queryset that is its own subquery, directly or through another one: `ValueError`;
|
|
3405
|
+
- an inner `values()`, `annotate()` or `select()` of several fields: `ValueError`;
|
|
3406
|
+
- an inner `as_of()`: `SurrealDbError` (call `as_of()` on the outer queryset);
|
|
3407
|
+
- an inner `objects(tx=)` whose transaction is not the outer queryset's: `SurrealDbError`;
|
|
3408
|
+
- an inner `variables()` binding a name of the statement to another value: `ValueError` (the two
|
|
3409
|
+
values must have the same type and be equal: `1` and `True`, or `1` and `1.0`, differ);
|
|
3410
|
+
- an inner `limit()` or `offset()` that is not an `int >= 0`, or an inner `order_by()` on `_sqv`
|
|
3411
|
+
(above): `ValueError`;
|
|
3412
|
+
- a subquery inside a list (`author__in=[Subquery(qs)]`): `ValueError`, give it as the whole value;
|
|
3413
|
+
- `Q(...).to_sql()` called on its own with a subquery lookup: `ValueError` (only a QuerySet binds
|
|
3414
|
+
a subquery);
|
|
3415
|
+
- a subquery written as data: `bulk_update(score=Subquery(qs))` raises `ValueError`, and an
|
|
3416
|
+
`exact` criterion or a `defaults=` value of `get_or_create()` or `update_or_create()` raises
|
|
3417
|
+
`SurrealDbError` (use a lookup such as `author__in`, and pass the value to write in `defaults=`);
|
|
3418
|
+
- `Subquery(x)` for anything but a QuerySet: `TypeError`.
|
|
3419
|
+
|
|
3420
|
+
`annotate(x=Subquery(...))` (a subquery's value on each row), correlated subqueries and `Exists`
|
|
3421
|
+
are not available yet.
|
|
3422
|
+
|
|
3423
|
+
#### Coming from the full SurrealDB-ORM
|
|
3424
|
+
|
|
3425
|
+
- **The same `Subquery(qs)`**, imported from `surreal_orm_lite`; a QuerySet given as the value is
|
|
3426
|
+
accepted too (`author__in=active`).
|
|
3427
|
+
- **No `select()` means the record ids** (`SELECT VALUE id`): the full ORM writes `SELECT *`, which
|
|
3428
|
+
`in` never matches. `select()` of several fields is refused instead of matching nothing.
|
|
3429
|
+
- **One statement**: a block whose `LET`s bind the subqueries, where the full ORM sends a `LET`
|
|
3430
|
+
prelude, two statements, whose rows the official SDK's `query()` cannot read (it returns the
|
|
3431
|
+
first statement's result only).
|
|
3432
|
+
- **A first-value lookup on an empty subquery matches nothing**: the full ORM compares with
|
|
3433
|
+
`array::first()` of it, `NONE`, so `gt` matches every record.
|
|
3434
|
+
- **`isnull`, the text lookups and the spatial lookups are refused** with a subquery.
|
|
3435
|
+
- **`annotate(x=Subquery(...))` is not available yet.**
|
|
3436
|
+
- **`live()` keeps the sub-SELECT inline**, in both.
|
|
3437
|
+
- **A subquery table that does not exist reads as empty**, like any missing table in the lite; the
|
|
3438
|
+
full ORM raises `TableNotFoundError` on SurrealDB 3.x.
|
|
3439
|
+
- **`Subquery()` raises `TypeError`** for anything but a QuerySet, and has no public `to_surql()`.
|
|
3440
|
+
- **The inner queryset's `variables()` are merged** into the statement (a clash raises
|
|
3441
|
+
`ValueError`) and its **`nearby()` applies**, where the full ORM's subquery drops both.
|
|
3442
|
+
- **The inner `fetch()` is ignored**, as in the full ORM, while `values()` and `annotate()` are
|
|
3443
|
+
refused.
|
|
3444
|
+
|
|
3218
3445
|
---
|
|
3219
3446
|
|
|
3220
3447
|
## Configuration Options
|
|
@@ -3329,7 +3556,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
3329
3556
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
3330
3557
|
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
|
|
3331
3558
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
3332
|
-
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.
|
|
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.
|
|
3333
3560
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
3334
3561
|
|
|
3335
3562
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -3430,6 +3657,10 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
3430
3657
|
| `fetch()` and dotted paths through record links under `as_of()` | `fetch()` refused (`SurrealDbError`) by `exec()`, `first()`, `get()` without an id; dotted paths in `filter()`, `select()`, `order_by()`, `values()` read the current value | as they were at the moment | v0.26.0 |
|
|
3431
3658
|
| Writing history with a raw `CREATE … VERSION` | stored at that moment, readable with `as_of()` | accepted, not readable at that moment (the table did not exist then) | v0.26.0 |
|
|
3432
3659
|
| `as_of()` moment before 1970-01-01 or after 2262-04-11T23:47:16.854775Z | refused by the ORM before any read (`ValueError`; `SurrealDbError` for a duration or expression resolving there): the server reads an earlier moment as the current state | refused by the ORM before any read, same errors: the server would fail with an internal error | v0.26.0 |
|
|
3660
|
+
| Subqueries (`Subquery`, or a QuerySet as a filter value) | one statement for every read, count, aggregation, write by filter and live query; reads inside a transaction raise (buffered) | the same, and reads inside an interactive transaction (`objects(tx=)`) see its uncommitted writes | v0.27.0 |
|
|
3661
|
+
| 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
|
+
| 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
|
+
| 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 |
|
|
3433
3664
|
| 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 |
|
|
3434
3665
|
|
|
3435
3666
|
> **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.
|
|
@@ -3501,7 +3732,8 @@ Contributions are welcome! Please:
|
|
|
3501
3732
|
| v0.24.0 | Geospatial fields | ✅ Released |
|
|
3502
3733
|
| v0.25.0 | Embedded test engine | ✅ Released |
|
|
3503
3734
|
| v0.26.0 | Time travel (versioned storage) | ✅ Released |
|
|
3504
|
-
| v0.27.0
|
|
3735
|
+
| v0.27.0 | Subqueries | ✅ Released |
|
|
3736
|
+
| v0.28.0 – v0.29.0 | Tier 2 — Extended (cache, multi-db) | 📋 Planned |
|
|
3505
3737
|
| v0.30.0 – v0.39.0 | Tier 3 — Advanced (search, DDL, migrations, CLI) | 📋 Planned |
|
|
3506
3738
|
| v0.40.0 | Beta Phase (API freeze, hardening) | 📋 Planned |
|
|
3507
3739
|
| v2.0.0 | Production / GA (aligned with SDK 2.0) | 📋 Planned |
|
|
@@ -3552,7 +3784,8 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
|
|
|
3552
3784
|
| Geospatial Fields | ✅ v0.24.0 | ✅ |
|
|
3553
3785
|
| Embedded engine | ✅ v0.25.0 (mem://, surrealkv://; rocksdb:// #233) | ❌ (HTTP/WebSocket only) |
|
|
3554
3786
|
| Time travel (`VERSION`) | ✅ v0.26.0 (`as_of()`) | ❌ |
|
|
3555
|
-
| Subqueries
|
|
3787
|
+
| Subqueries | ✅ v0.27.0 (`Subquery`, a QuerySet in `filter()`) | ✅ |
|
|
3788
|
+
| Query Cache | v0.28.0 | ✅ |
|
|
3556
3789
|
| Multi-database | v0.29.0 | ✅ |
|
|
3557
3790
|
| Schema Introspection | v0.30.0 | ✅ |
|
|
3558
3791
|
| DEFINE EVENT | v0.31.0 | ✅ |
|