surreal-orm-lite 0.25.0__tar.gz → 0.26.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.25.0 → surreal_orm_lite-0.26.0}/CHANGELOG.md +108 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/PKG-INFO +267 -5
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/README.md +266 -4
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/pyproject.toml +1 -1
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/embedded.py +29 -2
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/model_base.py +107 -13
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/query_set.py +315 -41
- surreal_orm_lite-0.26.0/src/surreal_orm_lite/time_travel.py +264 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/.gitignore +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/LICENSE +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/Makefile +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/types.py +0 -0
- {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/utils.py +0 -0
|
@@ -5,6 +5,114 @@ 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.26.0] - 2026-10-16
|
|
9
|
+
|
|
10
|
+
Time travel: a QuerySet reads a model's records as they were at a past moment, with
|
|
11
|
+
`as_of()` (SurrealQL's `VERSION` clause), on the official SDK's embedded
|
|
12
|
+
`surrealkv+versioned://` engine and on SurrealDB servers started with versioned storage. The
|
|
13
|
+
fourth minor of Tier 2.
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- **`QuerySet.as_of(at)`** adds a moment to every read of the queryset. Records updated since
|
|
18
|
+
read as they were, a record deleted since is still found, and one created later is not. The
|
|
19
|
+
store must keep history: the embedded `surrealkv+versioned://<path>` (no server), SurrealDB 3.x
|
|
20
|
+
started on `surrealkv://<path>?versioned=true` or `rocksdb://<path>?versioned=true`, or
|
|
21
|
+
SurrealDB 2.x started on `surrealkv+versioned://<path>`.
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
from surreal_orm_lite import BaseSurrealModel, SurrealDBConnectionManager
|
|
25
|
+
|
|
26
|
+
class Product(BaseSurrealModel):
|
|
27
|
+
id: str | None = None
|
|
28
|
+
name: str
|
|
29
|
+
price: float
|
|
30
|
+
|
|
31
|
+
SurrealDBConnectionManager.set_connection(
|
|
32
|
+
url=f"surrealkv+versioned://{path}/shop", namespace="shop", database="shop"
|
|
33
|
+
)
|
|
34
|
+
client = await SurrealDBConnectionManager.get_client()
|
|
35
|
+
|
|
36
|
+
lamp = Product(id="lamp", name="Lamp", price=40.0)
|
|
37
|
+
await lamp.save()
|
|
38
|
+
opening = await client.query("RETURN time::now();") # a moment, from the database's clock
|
|
39
|
+
await lamp.merge(price=30.0)
|
|
40
|
+
|
|
41
|
+
assert (await Product.objects().as_of(opening).get("lamp")).price == 40.0
|
|
42
|
+
assert (await Product.objects().get("lamp")).price == 30.0
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
- **The moment** is an aware `datetime` (any time zone) or a naive one (UTC), an ISO-8601 string
|
|
46
|
+
(parsed by the ORM; a date alone is midnight UTC), a `timedelta` or the ORM's `Duration` (that
|
|
47
|
+
long before the database's clock), a `SurrealFunc` the database evaluates
|
|
48
|
+
(`SurrealFunc("time::now() - 1h")`), or `None` (the current state again); called again, the last
|
|
49
|
+
moment wins. The moment is always a bound parameter. A moment outside the instants SurrealDB
|
|
50
|
+
versions can address (1970-01-01T00:00:00Z to 2262-04-11T23:47:16.854775Z) is refused on every
|
|
51
|
+
line: `ValueError` at the call, or `SurrealDbError` before the read for a duration or an
|
|
52
|
+
expression the database resolved there.
|
|
53
|
+
- **Every read honours it**, with `filter()`, `Q`, `nearby()`, `order_by()`, `limit()`, `offset()`,
|
|
54
|
+
`select()` and `variables()`, on edge models too: `exec()`, `first()`, `get()` (with filters or by
|
|
55
|
+
id), `all()`, `exists()`, `count()`, `sum()`, `avg()`, `min()`, `max()`, `values(…).annotate(…)`
|
|
56
|
+
and `annotate(d=GeoDistance(…))`.
|
|
57
|
+
- **Snapshots.** The instances a time-travel read returns are read-only: `save()`, `update()`,
|
|
58
|
+
`merge()`, `patch()`, `upsert()`, `delete()`, the `atomic_*()` methods, `relate()`,
|
|
59
|
+
`remove_relation()` and `remove_all_relations()` raise `SurrealDbError` before any signal or
|
|
60
|
+
request, and `bulk_create()` refuses a snapshot in its list. `refresh()` turns a snapshot back
|
|
61
|
+
into the current record; `Product(**snapshot.model_dump()).update()` (or `.save()` for a record
|
|
62
|
+
deleted since, or `.upsert()`) writes a past state back. `model_copy()` and `pickle` keep the
|
|
63
|
+
snapshot, and a snapshot is never `==` the current instance (compare `model_dump()`s). A record
|
|
64
|
+
model nested in a snapshot's fields is a snapshot too, such as a link `fetch()` resolves into a
|
|
65
|
+
model-typed field on SurrealDB 3.x; its own `refresh()` makes it the current record.
|
|
66
|
+
- **Refusals before any request.** On a queryset with `as_of()`: `bulk_create()`, `bulk_update()`,
|
|
67
|
+
`bulk_delete()`, `patch()`, `update_or_create()`, `get_or_create()`, `delete_table()`, `query()`,
|
|
68
|
+
`live()`, `watch()` and `changes()` raise `SurrealDbError`; `Model.objects(tx=...).as_of(...)`
|
|
69
|
+
raises at the call (history cannot join a transaction); on the embedded engine, a URL that keeps
|
|
70
|
+
no history (`mem://`, `memory://`, `surrealkv://`, `file://`) raises, naming
|
|
71
|
+
`surrealkv+versioned://`. A 3.x server without versioned storage refuses the read, raised as
|
|
72
|
+
`SurrealDbError` with the SDK's error as its `__cause__`.
|
|
73
|
+
- README section 27, "Time travel (`as_of()`)" (stores that keep history, the moment, reads,
|
|
74
|
+
snapshots, refusals, SurrealDB 2.x without versioned storage, record links, writing history with
|
|
75
|
+
a raw `CREATE … VERSION`, a note for users of the full SurrealDB-ORM, which has no time travel),
|
|
76
|
+
new rows in both behaviour tables, and the example notebook `examples/v0.26.0_time_travel.ipynb`.
|
|
77
|
+
|
|
78
|
+
### Changed
|
|
79
|
+
|
|
80
|
+
- `BaseSurrealModel` declares a private attribute, the snapshot marker, so every instance now has
|
|
81
|
+
a `__pydantic_private__` dict. Two current instances compare as before; an instance pickled by
|
|
82
|
+
v0.25.x unpickles as a current record, and a model's own private attributes are kept.
|
|
83
|
+
- `refresh()` also clears the snapshot marker of an instance read with `as_of()`.
|
|
84
|
+
- CI starts a second SurrealDB per job, on versioned storage, for the time-travel tests; they find
|
|
85
|
+
it through `SURREALDB_VERSIONED_PORT` and skip without it.
|
|
86
|
+
|
|
87
|
+
### Notes
|
|
88
|
+
|
|
89
|
+
- **Every time-travel table read also reads each record by its id at the moment**, because a plain
|
|
90
|
+
`SELECT … VERSION` is wrong on both server lines: SurrealDB 3.x's table reads return the records
|
|
91
|
+
deleted before the moment, in their last state, and SurrealDB 2.x and the embedded engine
|
|
92
|
+
miscount an unfiltered `count()`. It costs about one extra point read per record scanned; a read
|
|
93
|
+
by id needs no check.
|
|
94
|
+
- **SurrealDB 2.x without versioned storage answers without an error**: in memory or on plain
|
|
95
|
+
SurrealKV, it returns only the records last written at or before the moment, in their current
|
|
96
|
+
state, and the ORM cannot tell which storage the server runs. Start 2.x with
|
|
97
|
+
`surrealkv+versioned://` for time travel. SurrealDB 2.x on RocksDB refuses `VERSION`
|
|
98
|
+
(`SurrealDbError`).
|
|
99
|
+
- **Record links**: `fetch()` resolves links as they were on SurrealDB 3.x, into read-only
|
|
100
|
+
snapshots. On SurrealDB 2.x (servers and the SDK 2.x embedded engine) they resolve to their
|
|
101
|
+
current state, so `exec()`, `first()` and `get()` without an id refuse `fetch()` under
|
|
102
|
+
`as_of()`; a dotted path through a link reads the current value there.
|
|
103
|
+
- **Writing history at a past moment** is left to raw queries (`CREATE … VERSION d'…'`, one
|
|
104
|
+
statement per `client.query()` call): stored at that moment and readable with `as_of()` on
|
|
105
|
+
SurrealDB 2.x and the embedded engine; accepted but not readable at that moment on SurrealDB 3.x.
|
|
106
|
+
- The surrealdb SDK 2.x embedded engine ignores `?versioned=true` on `surrealkv://`: use
|
|
107
|
+
`surrealkv+versioned://`. The SDK's own `surrealdb.Duration` is accepted at runtime only (the
|
|
108
|
+
annotation names the ORM's types). `_as_of` is a reserved `variables()` name on a time-travel
|
|
109
|
+
read: the moment is bound under it.
|
|
110
|
+
- A `SurrealFunc` moment is sent as written: build it in your code, never from user input, and pass
|
|
111
|
+
user values through `variables()`, bound.
|
|
112
|
+
- **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, in memory and on versioned
|
|
113
|
+
storage, plus 3.1.5 for backward compatibility (identical); the embedded tests run in every CI
|
|
114
|
+
job. Every existing call behaves as in v0.25.x.
|
|
115
|
+
|
|
8
116
|
## [0.25.0] - 2026-10-15
|
|
9
117
|
|
|
10
118
|
Embedded test engine: the ORM also runs on the official SDK's in-process SurrealDB engine
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.26.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
|
|
@@ -223,6 +223,7 @@ results = await User.objects().query(
|
|
|
223
223
|
| Rich field types (datetime, date, duration, decimal, uuid, bytes, set, range) | ✅ |
|
|
224
224
|
| Geospatial fields (nearby, distance, spatial lookups) | ✅ |
|
|
225
225
|
| Embedded engine (mem://, surrealkv://) & test fixtures | ✅ |
|
|
226
|
+
| Time travel (`as_of()`, versioned storage) | ✅ |
|
|
226
227
|
|
|
227
228
|
### Supported Filter Lookups
|
|
228
229
|
|
|
@@ -2723,7 +2724,7 @@ which one is configured.
|
|
|
2723
2724
|
| ------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------ |
|
|
2724
2725
|
| `mem://`, `memory://` | ✅ in memory, gone when the connection closes | ❌ (HTTP/WebSocket only) |
|
|
2725
2726
|
| `surrealkv://<path>` | ✅ on disk (SurrealKV) | ❌ |
|
|
2726
|
-
| `surrealkv+versioned://<path>` | ✅ on disk
|
|
2727
|
+
| `surrealkv+versioned://<path>` | ✅ on disk, keeps history: time travel with `as_of()` (section 27) | ❌ |
|
|
2727
2728
|
| `file://<path>` | ✅ a **SurrealKV** store, not the RocksDB store `file://` means for the SurrealDB server | ❌ |
|
|
2728
2729
|
| `rocksdb://<path>` | ❌ not yet supported by the official SDK (#233): the ORM raises the SDK's refusal | ❌ |
|
|
2729
2730
|
|
|
@@ -2962,6 +2963,258 @@ async with embedded_database() as client:
|
|
|
2962
2963
|
- **Lite additions**: `SurrealDBConnectionManager.is_embedded()` and `embedded_database()`.
|
|
2963
2964
|
- **`ModelFactory` and `Faker`** come in v0.39.0.
|
|
2964
2965
|
|
|
2966
|
+
### 27. Time travel (`as_of()`)
|
|
2967
|
+
|
|
2968
|
+
Since v0.26.0 a QuerySet can read a model's records **as they were at a moment**: `as_of()` adds
|
|
2969
|
+
SurrealQL's `VERSION` clause to every read of the queryset. The store must keep history (see
|
|
2970
|
+
[Stores that keep history](#stores-that-keep-history)): the embedded engine's
|
|
2971
|
+
`surrealkv+versioned://` keeps it on disk, with no server.
|
|
2972
|
+
|
|
2973
|
+
```python
|
|
2974
|
+
import tempfile
|
|
2975
|
+
|
|
2976
|
+
from surreal_orm_lite import BaseSurrealModel, SurrealDBConnectionManager, SurrealDbNotFoundError
|
|
2977
|
+
|
|
2978
|
+
|
|
2979
|
+
class Product(BaseSurrealModel):
|
|
2980
|
+
id: str | None = None
|
|
2981
|
+
name: str
|
|
2982
|
+
price: float
|
|
2983
|
+
|
|
2984
|
+
|
|
2985
|
+
path = tempfile.mkdtemp()
|
|
2986
|
+
SurrealDBConnectionManager.set_connection(
|
|
2987
|
+
url=f"surrealkv+versioned://{path}/shop", namespace="shop", database="shop"
|
|
2988
|
+
)
|
|
2989
|
+
client = await SurrealDBConnectionManager.get_client()
|
|
2990
|
+
|
|
2991
|
+
lamp = Product(id="lamp", name="Lamp", price=40.0)
|
|
2992
|
+
desk = Product(id="desk", name="Desk", price=250.0)
|
|
2993
|
+
await lamp.save()
|
|
2994
|
+
await desk.save()
|
|
2995
|
+
opening = await client.query("RETURN time::now();") # a moment, from the database's clock
|
|
2996
|
+
await lamp.merge(price=30.0)
|
|
2997
|
+
sale = await client.query("RETURN time::now();")
|
|
2998
|
+
await desk.delete()
|
|
2999
|
+
|
|
3000
|
+
then = await Product.objects().as_of(opening).order_by("name").exec()
|
|
3001
|
+
assert [(product.name, product.price) for product in then] == [("Desk", 250.0), ("Lamp", 40.0)]
|
|
3002
|
+
assert await Product.objects().as_of(sale).count() == 2
|
|
3003
|
+
assert await Product.objects().count() == 1
|
|
3004
|
+
|
|
3005
|
+
# A record deleted since is still found at that moment; one created later is not.
|
|
3006
|
+
assert (await Product.objects().as_of(sale).get("desk")).price == 250.0
|
|
3007
|
+
try:
|
|
3008
|
+
await Product.objects().get("desk")
|
|
3009
|
+
except SurrealDbNotFoundError:
|
|
3010
|
+
print("no desk now")
|
|
3011
|
+
```
|
|
3012
|
+
|
|
3013
|
+
#### Stores that keep history
|
|
3014
|
+
|
|
3015
|
+
| Where the read runs | `as_of()` |
|
|
3016
|
+
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
3017
|
+
| Embedded `surrealkv+versioned://<path>` | ✅ (SDK 2.0.0 ignores `?versioned=true` on `surrealkv://`) |
|
|
3018
|
+
| Embedded `mem://`, `memory://`, `surrealkv://`, `file://` | `SurrealDbError` before any request |
|
|
3019
|
+
| SurrealDB 3.x started on `surrealkv://<path>?versioned=true` or `rocksdb://<path>?versioned=true` | ✅ |
|
|
3020
|
+
| SurrealDB 3.x in memory, or on `surrealkv://` or `rocksdb://` without `versioned=true` | `SurrealDbError`: the server refuses `VERSION` (the SDK's error is its `__cause__`) |
|
|
3021
|
+
| SurrealDB 2.x started on `surrealkv+versioned://<path>` | ✅ |
|
|
3022
|
+
| SurrealDB 2.x on RocksDB | `SurrealDbError`: the server refuses `VERSION` |
|
|
3023
|
+
| SurrealDB 2.x in memory or on plain `surrealkv://` | no error, and the ORM cannot tell (see [below](#surrealdb-2x-without-versioned-storage)) |
|
|
3024
|
+
|
|
3025
|
+
```bash
|
|
3026
|
+
surreal start --user root --pass root "surrealkv:///var/lib/surrealdb?versioned=true" # SurrealDB 3.x
|
|
3027
|
+
surreal start --user root --pass root "surrealkv+versioned:///var/lib/surrealdb" # SurrealDB 2.x
|
|
3028
|
+
```
|
|
3029
|
+
|
|
3030
|
+
#### The moment
|
|
3031
|
+
|
|
3032
|
+
`as_of()` takes a moment, "how long ago", a server expression, or `None`:
|
|
3033
|
+
|
|
3034
|
+
```python
|
|
3035
|
+
from datetime import UTC, datetime, timedelta
|
|
3036
|
+
|
|
3037
|
+
from surreal_orm_lite import Duration, SurrealFunc
|
|
3038
|
+
|
|
3039
|
+
Product.objects().as_of(datetime(2026, 1, 1, 9, 30, tzinfo=UTC)) # an aware datetime, any time zone
|
|
3040
|
+
Product.objects().as_of(datetime(2026, 1, 1, 9, 30)) # a naive one is UTC
|
|
3041
|
+
Product.objects().as_of("2026-01-01T09:30:00+02:00") # ISO-8601, parsed by the ORM
|
|
3042
|
+
Product.objects().as_of("2026-01-01") # a date alone: midnight UTC
|
|
3043
|
+
Product.objects().as_of(timedelta(hours=1)) # an hour before the database's clock
|
|
3044
|
+
Product.objects().as_of(Duration.parse("1h")) # the ORM's Duration too
|
|
3045
|
+
Product.objects().as_of(SurrealFunc("time::floor(time::now(), 1d)")) # evaluated by the database
|
|
3046
|
+
Product.objects().variables(cutoff=opening).as_of(SurrealFunc("$cutoff"))
|
|
3047
|
+
Product.objects().as_of(opening).as_of(None) # None: the current state again
|
|
3048
|
+
|
|
3049
|
+
assert await Product.objects().as_of(timedelta(0)).count() == 1 # now
|
|
3050
|
+
assert await Product.objects().as_of(SurrealFunc("time::now() - 1h")).count() == 0 # before the shop
|
|
3051
|
+
```
|
|
3052
|
+
|
|
3053
|
+
- A naive `datetime` or ISO-8601 string is UTC, as for every datetime the ORM sends; a date alone
|
|
3054
|
+
is that day's midnight UTC, while a `date` object is refused (`TypeError`), and so are numbers,
|
|
3055
|
+
`bool` and `bytes`. A string that is not ISO-8601 raises `ValueError`.
|
|
3056
|
+
- A `timedelta` or an ORM `Duration` (>= 0) means that long before the **database's** clock, and a
|
|
3057
|
+
`SurrealFunc` is an expression the database evaluates to a datetime: both are resolved by the
|
|
3058
|
+
database just before each read (one `RETURN` request). A `SurrealFunc` is written into that
|
|
3059
|
+
`RETURN` as is: build it in your code, never from user input, and pass user values through
|
|
3060
|
+
`variables()` (bound), as `$cutoff` above. `_as_of` is a reserved `variables()` name: the
|
|
3061
|
+
moment is bound under it.
|
|
3062
|
+
- The surrealdb SDK's own `Duration` (`surrealdb.Duration`) is accepted at runtime only: the
|
|
3063
|
+
annotation names the ORM's types, so a type checker flags it. `Duration(sdk_duration.elapsed)`
|
|
3064
|
+
converts it.
|
|
3065
|
+
- Called again, the last moment wins. A moment after the last write reads the current state; a
|
|
3066
|
+
moment before the table existed reads no records.
|
|
3067
|
+
|
|
3068
|
+
**The moment must lie between 1970-01-01T00:00:00Z and 2262-04-11T23:47:16.854775Z**, the
|
|
3069
|
+
instants SurrealDB versions can address (nanoseconds since 1970 in a signed 64-bit integer).
|
|
3070
|
+
SurrealDB 2.x reads an earlier moment as the **current** state, without an error, and every line
|
|
3071
|
+
fails after the later one, so the ORM refuses both, on every line: an absolute moment at the call
|
|
3072
|
+
(`ValueError`), a duration or an expression once the database has resolved it, before the read is
|
|
3073
|
+
sent (`SurrealDbError`).
|
|
3074
|
+
|
|
3075
|
+
```python
|
|
3076
|
+
try:
|
|
3077
|
+
Product.objects().as_of(datetime(1900, 1, 1))
|
|
3078
|
+
except ValueError as error:
|
|
3079
|
+
print(error)
|
|
3080
|
+
# as_of() takes a moment from 1970-01-01T00:00:00+00:00 to 2262-04-11T23:47:16.854775+00:00, the
|
|
3081
|
+
# instants SurrealDB versions can address (SurrealDB 2.x reads an earlier moment as the current
|
|
3082
|
+
# state), got 1900-01-01T00:00:00+00:00
|
|
3083
|
+
```
|
|
3084
|
+
|
|
3085
|
+
#### Reads
|
|
3086
|
+
|
|
3087
|
+
Every read of the queryset honours the moment, with `filter()`, `Q`, `nearby()`, `order_by()`,
|
|
3088
|
+
`limit()`, `offset()`, `select()` and `variables()`, on edge models too:
|
|
3089
|
+
|
|
3090
|
+
| Read | Under `as_of()` |
|
|
3091
|
+
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
3092
|
+
| `exec()`, `first()`, `get()` with filters | the records as they were, as snapshots (a row that does not validate comes back as a dict) |
|
|
3093
|
+
| `get("id")` | the record as it was: found if deleted since, `SurrealDbNotFoundError` if created later |
|
|
3094
|
+
| `all()` | every record as it was, as snapshots (`all()` still ignores `filter()`) |
|
|
3095
|
+
| `exists()`, `count()`, `sum()`, `avg()`, `min()`, `max()` | the values at that moment |
|
|
3096
|
+
| `values(…).annotate(…)` | the groups at that moment, as dicts |
|
|
3097
|
+
| `annotate(d=GeoDistance(…))` | snapshots carrying their distances |
|
|
3098
|
+
|
|
3099
|
+
A plain `SELECT … VERSION` is wrong on both server lines, so the ORM never sends one on its own.
|
|
3100
|
+
SurrealDB 3.x's table reads return the records deleted before the moment, in their last state
|
|
3101
|
+
(so filtered counts, sums and groups count them too); SurrealDB 2.x and the embedded engine
|
|
3102
|
+
miscount an unfiltered `count()`. Every time-travel table read therefore also reads each record
|
|
3103
|
+
by its id at the moment, which is right on every versioned store:
|
|
3104
|
+
|
|
3105
|
+
```sql
|
|
3106
|
+
SELECT * FROM Product WHERE (SELECT VALUE id FROM ONLY $parent.id VERSION $_as_of) != NONE VERSION $_as_of;
|
|
3107
|
+
```
|
|
3108
|
+
|
|
3109
|
+
It costs about one extra point read per record scanned; a read by id (`get("lamp")`) needs no
|
|
3110
|
+
check. The moment is always a bound parameter.
|
|
3111
|
+
|
|
3112
|
+
#### Snapshots
|
|
3113
|
+
|
|
3114
|
+
The instances a time-travel read returns are **snapshots**, read-only: `save()`, `update()`,
|
|
3115
|
+
`merge()`, `patch()`, `upsert()`, `delete()`, the `atomic_*()` methods, `relate()`,
|
|
3116
|
+
`remove_relation()` and `remove_all_relations()` raise `SurrealDbError` before any signal or
|
|
3117
|
+
request, and `bulk_create()` refuses a snapshot in its list. To restore a past state, build a new
|
|
3118
|
+
instance from the snapshot:
|
|
3119
|
+
|
|
3120
|
+
```python
|
|
3121
|
+
from surreal_orm_lite import SurrealDbError
|
|
3122
|
+
|
|
3123
|
+
old_lamp = await Product.objects().as_of(opening).get("lamp")
|
|
3124
|
+
try:
|
|
3125
|
+
await old_lamp.save()
|
|
3126
|
+
except SurrealDbError as error:
|
|
3127
|
+
print(str(error).split(":")[0])
|
|
3128
|
+
# Product.save() cannot run on an instance read with as_of()
|
|
3129
|
+
|
|
3130
|
+
# The record exists: update() writes the past state back.
|
|
3131
|
+
await Product(**old_lamp.model_dump()).update()
|
|
3132
|
+
assert (await Product.objects().get("lamp")).price == 40.0
|
|
3133
|
+
|
|
3134
|
+
# It was deleted since: save() creates it again (an "undelete").
|
|
3135
|
+
old_desk = await Product.objects().as_of(sale).get("desk")
|
|
3136
|
+
await Product(**old_desk.model_dump()).save()
|
|
3137
|
+
assert await Product.objects().count() == 2
|
|
3138
|
+
|
|
3139
|
+
# refresh() turns a snapshot back into the current record: its writes work again.
|
|
3140
|
+
await old_lamp.refresh()
|
|
3141
|
+
await old_lamp.merge(price=35.0)
|
|
3142
|
+
|
|
3143
|
+
# A snapshot is never == the current instance, even with the same fields.
|
|
3144
|
+
current_desk = await Product.objects().get("desk")
|
|
3145
|
+
assert old_desk != current_desk and old_desk.model_dump() == current_desk.model_dump()
|
|
3146
|
+
```
|
|
3147
|
+
|
|
3148
|
+
- **Auth models**: on a model mixing `AuthenticatedUserMixin`, `refresh` is the mixin's
|
|
3149
|
+
token-exchange classmethod; call `await BaseSurrealModel.refresh(snapshot)`.
|
|
3150
|
+
- **Equality**: Pydantic compares private attributes, and the snapshot's moment is one: compare
|
|
3151
|
+
`model_dump()`s.
|
|
3152
|
+
- **`server_fields`**: `save()` leaves them out, so an undelete by `save()` lets the server's
|
|
3153
|
+
`DEFAULT` fill them again; `update()` and `upsert()` write them back.
|
|
3154
|
+
`await Product(**snapshot.model_dump()).upsert()` restores the past state exactly, whether the
|
|
3155
|
+
record still exists or not (not on edge models, whose `upsert()` always raises). Computed fields
|
|
3156
|
+
are recomputed by the server in every case.
|
|
3157
|
+
- **Copies**: `model_copy()` and `pickle` keep the snapshot; an instance pickled by v0.25.x
|
|
3158
|
+
unpickles as a current record.
|
|
3159
|
+
- **Nested records**: a record model nested in a snapshot's fields is a snapshot too, such as a
|
|
3160
|
+
link `fetch()` resolves into a model-typed field (`author: Author | RecordID | None`, see
|
|
3161
|
+
[Record links](#record-links)): it holds the linked record as it was. Its own `refresh()` makes
|
|
3162
|
+
it the current record; the snapshot's `refresh()` re-reads that record only.
|
|
3163
|
+
- **Graph reads** stay available: `get_related()` and `traverse()` read the current graph.
|
|
3164
|
+
- When the record was deleted since, `refresh()` raises its usual `SurrealDbError` and the
|
|
3165
|
+
instance stays a snapshot.
|
|
3166
|
+
|
|
3167
|
+
#### What a time-travel queryset refuses
|
|
3168
|
+
|
|
3169
|
+
A time-travel read is read-only and cannot be streamed: `bulk_create()`, `bulk_update()`,
|
|
3170
|
+
`bulk_delete()`, `patch()`, `update_or_create()`, `get_or_create()`, `delete_table()`, `query()`,
|
|
3171
|
+
`live()`, `watch()` and `changes()` raise `SurrealDbError` on a queryset with `as_of()`, before
|
|
3172
|
+
any request. History cannot join a transaction: `Model.objects(tx=...).as_of(...)` raises at the
|
|
3173
|
+
call. On the embedded engine, a URL that keeps no history raises before any request, naming
|
|
3174
|
+
`surrealkv+versioned://`.
|
|
3175
|
+
|
|
3176
|
+
#### SurrealDB 2.x without versioned storage
|
|
3177
|
+
|
|
3178
|
+
A SurrealDB 2.x server in memory or on plain SurrealKV answers a time-travel read **without an
|
|
3179
|
+
error**: it returns only the records last written at or before the moment, in their **current**
|
|
3180
|
+
state, and nothing tells the ORM which storage the server runs, so it cannot tell. Start 2.x with
|
|
3181
|
+
`surrealkv+versioned://` for time travel. A 3.x server without versioned storage refuses the read
|
|
3182
|
+
(`SurrealDbError`), and so does 2.x on RocksDB.
|
|
3183
|
+
|
|
3184
|
+
#### Record links
|
|
3185
|
+
|
|
3186
|
+
`fetch()` resolves links as they were on SurrealDB 3.x. SurrealDB 2.x (servers, and the embedded
|
|
3187
|
+
engine of the surrealdb SDK 2.x) resolves them to their current state, so on 2.x the reads that
|
|
3188
|
+
return the fetched records (`exec()`, `first()`, `get()` without an id) raise `SurrealDbError`;
|
|
3189
|
+
the other reads ignore `fetch()`, as without `as_of()`. Read the linked records with their own
|
|
3190
|
+
`as_of()` query. On 3.x, a link fetched into a model-typed field is a snapshot too, read-only. A
|
|
3191
|
+
dotted path through a link (`author.name`) in `filter()`, `select()`, `order_by()` or `values()`
|
|
3192
|
+
reads the linked record as it was on 3.x and as it is now on 2.x.
|
|
3193
|
+
|
|
3194
|
+
#### Writing history at a past moment
|
|
3195
|
+
|
|
3196
|
+
The ORM writes now. A raw query can write a record at a past moment, one statement per
|
|
3197
|
+
`client.query()` call:
|
|
3198
|
+
|
|
3199
|
+
```python
|
|
3200
|
+
await client.query("CREATE Product:stool SET name = 'Stool', price = 15.0 VERSION d'2020-01-01T00:00:00Z';")
|
|
3201
|
+
# SurrealDB 2.x and the embedded engine: stored at that moment, readable with as_of()
|
|
3202
|
+
assert await Product.objects().as_of(datetime(2021, 1, 1, tzinfo=UTC)).count() == 1
|
|
3203
|
+
```
|
|
3204
|
+
|
|
3205
|
+
SurrealDB 3.x accepts the statement, but the record is not readable at that moment (the table did
|
|
3206
|
+
not exist then), and a `CREATE` of an id that exists raises.
|
|
3207
|
+
|
|
3208
|
+
#### Coming from the full SurrealDB-ORM
|
|
3209
|
+
|
|
3210
|
+
- **The full ORM has no time travel** (no `VERSION` support): `as_of()`, snapshots and their
|
|
3211
|
+
errors are lite additions.
|
|
3212
|
+
- **`as_of()`, not `version()`**: the name is temporal SQL's `AS OF`. SurrealQL's keyword is
|
|
3213
|
+
`VERSION` and the JavaScript SDK has `select().version()`, but on the Python SDK's connection
|
|
3214
|
+
`version()` returns the server's version.
|
|
3215
|
+
- **A snapshot is never `==` the current instance**, even with identical fields: compare
|
|
3216
|
+
`model_dump()`s.
|
|
3217
|
+
|
|
2965
3218
|
---
|
|
2966
3219
|
|
|
2967
3220
|
## Configuration Options
|
|
@@ -3076,7 +3329,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
3076
3329
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
3077
3330
|
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
|
|
3078
3331
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
3079
|
-
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.
|
|
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.
|
|
3080
3333
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
3081
3334
|
|
|
3082
3335
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -3172,6 +3425,11 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
3172
3425
|
| Geometry fields, `nearby()`, `GeoDistance`, the `inside` / `outside` / `intersects` lookups | same on both lines: stored as native geometries, read back as the declared class, distances in metres identical | same on both lines (verified on 3.3.4 and 3.1.5); an SDK geometry SurrealDB refuses raises `ValueError` before anything is sent | v0.24.0 |
|
|
3173
3426
|
| A `Decimal` coordinate written with an exponent in an SDK geometry | raw SDK value: refused, or a wrong value for a long one. ORM: sent in fixed point, stored with its value | raw SDK value: stored, a long one with a wrong value. ORM: sent in fixed point, stored with its value | v0.24.0 |
|
|
3174
3427
|
| A GeoJSON dict written to an untyped field (`Any`, `dict`) | stored as a plain object, not a geometry: `nearby()` skips it, `geo::*` functions and `geometry<…>` columns refuse it; declare a geometry field | same on both lines | pre-existing (documented in v0.24.0) |
|
|
3428
|
+
| Time travel (`as_of()`) on a server without versioned storage | no error, and the ORM cannot tell: in memory or on plain SurrealKV, only records last written at or before the moment, in their current state. RocksDB: `SurrealDbError` | `SurrealDbError` (the server refuses `VERSION`) | v0.26.0 |
|
|
3429
|
+
| Time travel on versioned storage: records deleted since, counts and aggregates | right (the ORM's per-record check also corrects the server's unfiltered `count()`) | right (the ORM's per-record check hides the records deleted before the moment that the server's table reads return) | v0.26.0 |
|
|
3430
|
+
| `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
|
+
| 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
|
+
| `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 |
|
|
3175
3433
|
| 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 |
|
|
3176
3434
|
|
|
3177
3435
|
> **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.
|
|
@@ -3180,7 +3438,8 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
3180
3438
|
|
|
3181
3439
|
The official SDK's in-process engine ([section 26](#26-embedded-engine-and-test-fixtures)) is a
|
|
3182
3440
|
line of its own: SurrealDB core 2.3.10, bundled with SDK 2.0.0. Rows measured with SDK 2.0.0 on
|
|
3183
|
-
`mem
|
|
3441
|
+
`mem://` (the time-travel row on `surrealkv+versioned://`), and on the 2.7.0 and 3.3.4 servers.
|
|
3442
|
+
Capabilities not listed behave as on a 2.x server.
|
|
3184
3443
|
|
|
3185
3444
|
| ORM capability | Embedded engine (SDK 2.0.0) | Servers (2.x and 3.x) | Since |
|
|
3186
3445
|
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------- |
|
|
@@ -3200,6 +3459,7 @@ line of its own: SurrealDB core 2.3.10, bundled with SDK 2.0.0. Rows measured wi
|
|
|
3200
3459
|
| `invalidate()` | back to the in-process owner | signs in again as the configured user | v0.25.0 |
|
|
3201
3460
|
| Reading a table that does not exist | `[]`, raw queries included (as on 2.x) | the ORM reads `[]`; a raw query on 3.x raises `NotFoundError` | v0.25.0 |
|
|
3202
3461
|
| Parse errors | bare `RuntimeError` (the DDL helpers raise `SurrealDbError`) | the SDK's error classes | v0.25.0 |
|
|
3462
|
+
| Time travel (`as_of()`) | `surrealkv+versioned://` only (`?versioned=true` is ignored by SDK 2.0.0); any other URL → `SurrealDbError` before any request; `fetch()` refused (2.x core) | versioned storage required (see the 2.x/3.x table) | v0.26.0 |
|
|
3203
3463
|
| Everything else | CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields, upsert/patch, server values, computed fields, stored functions, signals: the same as on a 2.x server | unchanged | v0.25.0 |
|
|
3204
3464
|
|
|
3205
3465
|
---
|
|
@@ -3240,7 +3500,8 @@ Contributions are welcome! Please:
|
|
|
3240
3500
|
| v0.23.0 | Rich field types | ✅ Released |
|
|
3241
3501
|
| v0.24.0 | Geospatial fields | ✅ Released |
|
|
3242
3502
|
| v0.25.0 | Embedded test engine | ✅ Released |
|
|
3243
|
-
| v0.26.0
|
|
3503
|
+
| v0.26.0 | Time travel (versioned storage) | ✅ Released |
|
|
3504
|
+
| v0.27.0 – v0.29.0 | Tier 2 — Extended (subqueries, cache, multi-db) | 📋 Planned |
|
|
3244
3505
|
| v0.30.0 – v0.39.0 | Tier 3 — Advanced (search, DDL, migrations, CLI) | 📋 Planned |
|
|
3245
3506
|
| v0.40.0 | Beta Phase (API freeze, hardening) | 📋 Planned |
|
|
3246
3507
|
| v2.0.0 | Production / GA (aligned with SDK 2.0) | 📋 Planned |
|
|
@@ -3290,6 +3551,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
|
|
|
3290
3551
|
| Rich field types | ✅ v0.23.0 | ✅ |
|
|
3291
3552
|
| Geospatial Fields | ✅ v0.24.0 | ✅ |
|
|
3292
3553
|
| Embedded engine | ✅ v0.25.0 (mem://, surrealkv://; rocksdb:// #233) | ❌ (HTTP/WebSocket only) |
|
|
3554
|
+
| Time travel (`VERSION`) | ✅ v0.26.0 (`as_of()`) | ❌ |
|
|
3293
3555
|
| Subqueries & Query Cache | v0.27 – v0.28 | ✅ |
|
|
3294
3556
|
| Multi-database | v0.29.0 | ✅ |
|
|
3295
3557
|
| Schema Introspection | v0.30.0 | ✅ |
|