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.
Files changed (38) hide show
  1. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/CHANGELOG.md +108 -0
  2. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/PKG-INFO +267 -5
  3. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/README.md +266 -4
  4. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/embedded.py +29 -2
  7. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/model_base.py +107 -13
  8. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/query_set.py +315 -41
  9. surreal_orm_lite-0.26.0/src/surreal_orm_lite/time_travel.py +264 -0
  10. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/.gitignore +0 -0
  11. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/LICENSE +0 -0
  12. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/Makefile +0 -0
  13. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/_sdk.py +0 -0
  14. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/aggregations.py +0 -0
  15. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/auth.py +0 -0
  16. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/changefeed.py +0 -0
  17. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/concurrency.py +0 -0
  18. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/connection_manager.py +0 -0
  19. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/constants.py +0 -0
  20. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/decoding.py +0 -0
  21. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/edge.py +0 -0
  22. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/encoding.py +0 -0
  23. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/enum.py +0 -0
  24. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/exceptions.py +0 -0
  25. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/functions.py +0 -0
  26. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/geo.py +0 -0
  27. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/live.py +0 -0
  28. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/model_auth.py +0 -0
  29. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/py.typed +0 -0
  30. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/q.py +0 -0
  31. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/signals.py +0 -0
  32. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/surql_literal.py +0 -0
  33. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/testing/__init__.py +0 -0
  34. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/testing/database.py +0 -0
  35. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  36. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/transaction.py +0 -0
  37. {surreal_orm_lite-0.25.0 → surreal_orm_lite-0.26.0}/src/surreal_orm_lite/types.py +0 -0
  38. {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.25.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; behaves as `surrealkv://` until time travel (v0.26.0) | ❌ |
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://`, and on the 2.7.0 and 3.3.4 servers. Capabilities not listed behave as on a 2.x server.
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 – v0.29.0 | Tier 2 — Extended (time travel, subqueries) | 📋 Planned |
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 | ✅ |