surreal-orm-lite 0.24.1__tar.gz → 0.24.3__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.24.1 → surreal_orm_lite-0.24.3}/CHANGELOG.md +95 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/PKG-INFO +100 -63
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/README.md +99 -62
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/pyproject.toml +1 -1
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/_sdk.py +25 -1
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/connection_manager.py +9 -0
- surreal_orm_lite-0.24.3/src/surreal_orm_lite/decoding.py +338 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/encoding.py +19 -27
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/geo.py +4 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/model_base.py +649 -16
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/surql_literal.py +11 -7
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/.gitignore +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/LICENSE +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/Makefile +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/query_set.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/types.py +0 -0
- {surreal_orm_lite-0.24.1 → surreal_orm_lite-0.24.3}/src/surreal_orm_lite/utils.py +0 -0
|
@@ -5,6 +5,101 @@ 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.24.3] - 2026-10-15
|
|
9
|
+
|
|
10
|
+
The clients the ORM opens now read the values the surrealdb SDK 2.0.0 cannot decode (zero
|
|
11
|
+
durations, SurrealDB 3.x native sets, degenerate geometries), and a zero duration can be stored.
|
|
12
|
+
No new public API.
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
|
|
16
|
+
- **Some values SurrealDB returns could not be read** (#235). The surrealdb SDK 2.0.0 cannot
|
|
17
|
+
decode a zero duration, a SurrealDB 3.x native set (a `TYPE set<…>` column on SurrealDB 3.3) or
|
|
18
|
+
a degenerate geometry another client wrote (a line of fewer than 2 points, alone or inside
|
|
19
|
+
another geometry, or a polygon ring of fewer than 4 points): one such value failed the whole
|
|
20
|
+
response it was in. The clients the ORM opens (`SurrealDBConnectionManager.get_client()`,
|
|
21
|
+
`ephemeral_client()`) now read them, over WebSocket, HTTP and embedded connections, and later
|
|
22
|
+
calls on the same client keep working:
|
|
23
|
+
- a zero duration reads as zero: `timedelta(0)` or `Duration(0)` in a typed field, the SDK's
|
|
24
|
+
`Duration(0)` in an untyped one;
|
|
25
|
+
- a native set reads as a Python `set`, which `set[X]` and `frozenset[X]` fields validate, or as
|
|
26
|
+
a `list` when its items are unhashable (record ids, objects, nested sets) or two of them are
|
|
27
|
+
equal in Python, like `1` and `true`: every item the server holds comes back;
|
|
28
|
+
- a degenerate geometry reads as its GeoJSON dict, such as
|
|
29
|
+
`{"type": "LineString", "coordinates": [[1.0, 2.0]]}`, in an untyped field, `raw_query()` and
|
|
30
|
+
live notifications; a geometry field refuses it with a `ValidationError` naming the field.
|
|
31
|
+
|
|
32
|
+
Every other value reads exactly as the SDK reads it, and a malformed value still raises the
|
|
33
|
+
SDK's error. The values go through a hook around the SDK's own CBOR decoder, installed only on
|
|
34
|
+
the ORM's clients and only while the installed SDK cannot decode them: the SDK's modules are not
|
|
35
|
+
modified, and an `AsyncSurreal` client the application builds itself keeps the SDK's behaviour.
|
|
36
|
+
Written back through the ORM (`merge()`, or `update()`, which rewrites the whole row), a native
|
|
37
|
+
set is stored as an array, unless its column is `TYPE set<…>`, and a degenerate geometry's dict
|
|
38
|
+
as a plain object, on both lines.
|
|
39
|
+
|
|
40
|
+
- **A zero duration was refused** since v0.23.0 (`ValueError` for a field, a filter value or a
|
|
41
|
+
bound parameter, `TypeError` from `live()`), because the SDK could not read it back. The ORM's
|
|
42
|
+
clients now read it, so `timedelta(0)` and `Duration(0)` are written, filtered and read back like
|
|
43
|
+
any other duration, on both lines; filter "longer than zero" with `__gt=Duration(0)`. The refusal
|
|
44
|
+
remains only for an SDK that reads no zero duration and whose decoder the ORM cannot hook.
|
|
45
|
+
Upgrade note: a record the ORM writes can now hold a zero duration, which a reader that does not
|
|
46
|
+
go through the ORM's clients cannot read (an `AsyncSurreal` client the application builds itself,
|
|
47
|
+
another service on the SDK 2.0.0).
|
|
48
|
+
|
|
49
|
+
### Notes
|
|
50
|
+
|
|
51
|
+
- **SurrealDB 2.x vs 3.x**: zero durations and degenerate geometries read the same on both lines.
|
|
52
|
+
Native sets exist only on 3.x: on 3.3 a `TYPE set<…>` column stores a `set[X]` field's array as a
|
|
53
|
+
native set, which now reads back as the declared set; 3.1 still refuses an array in such a
|
|
54
|
+
column, so declare `array<…>` columns to support 3.1. On 2.x the column holds an array, as
|
|
55
|
+
before.
|
|
56
|
+
- The README's "Values the SDK cannot read", "Geometries the SDK cannot read" and "Sets" sections,
|
|
57
|
+
the refusals table and the 2.x/3.x row for `TYPE set<…>` columns describe the new behaviour; the
|
|
58
|
+
v0.23.0 rich field types notebook stores and reads back a zero duration.
|
|
59
|
+
- A later SDK reads zero durations and native sets itself
|
|
60
|
+
([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)); the hook then leaves
|
|
61
|
+
them to it.
|
|
62
|
+
- Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
|
|
63
|
+
|
|
64
|
+
## [0.24.2] - 2026-10-15
|
|
65
|
+
|
|
66
|
+
Sub-models keep their rich values after a write that returns the row, and a `timedelta` below the
|
|
67
|
+
top level reads the server's duration. No new public API.
|
|
68
|
+
|
|
69
|
+
### Fixed
|
|
70
|
+
|
|
71
|
+
- **A sub-model's durations, ranges and geometries were written back as plain objects** (#228).
|
|
72
|
+
`save()` without an id, `upsert()`, `refresh()`, `merge()`, `patch()` and the `atomic_*` helpers
|
|
73
|
+
applied the returned row without validation, so a sub-model field (a Pydantic model, a dataclass
|
|
74
|
+
or a `TypedDict`, also inside `list[...]`, `dict[..., ...]` or `X | None`) held the row's `dict`
|
|
75
|
+
with the SDK's values. The next full write (`update()`, `upsert()`) stored their fields
|
|
76
|
+
(`{elapsed: 300000000000}`) instead of SurrealDB's durations, ranges and geometries, warned
|
|
77
|
+
`PydanticSerializationUnexpectedValue`, and the next `get()` of the record failed validation.
|
|
78
|
+
These calls now give a sub-model field the value a read gives: its model instance, with the ORM's
|
|
79
|
+
`Duration`, `timedelta`, `Range` and geometry values inside, so writing the instance back is safe.
|
|
80
|
+
- The returned row goes through the model's validation, as in `get()`, so the model's own
|
|
81
|
+
validators (`field_validator`, `model_validator`, `model_post_init`) run on it too.
|
|
82
|
+
- When the row as a whole does not validate, each sub-model field is validated on its own, except
|
|
83
|
+
one that the model's own validators could reshape; that one, like a value that does not
|
|
84
|
+
validate, is applied as received. These calls raise nothing new.
|
|
85
|
+
- A GeoJSON object stored in a top-level geometry field (the full SurrealDB-ORM's format) now
|
|
86
|
+
becomes the ORM geometry after `refresh()`, `merge()` and `patch()`, as after `get()`.
|
|
87
|
+
- **A `timedelta` below the top level failed to read the server's duration.** A sub-model's
|
|
88
|
+
`timedelta` field, `list[timedelta]`, `dict[str, timedelta]` or `timedelta | str` refused the
|
|
89
|
+
SDK's `Duration` on every read, as before v0.23.0. They now read a `timedelta`, floored to the
|
|
90
|
+
microsecond (declare `Duration` to keep the nanoseconds), in a read and in the row a write
|
|
91
|
+
returns. A row holding many such values is converted in one pass, without mutating the data,
|
|
92
|
+
and the model's own validators (any mode) and `model_post_init` still apply once, even when they
|
|
93
|
+
change the data in place.
|
|
94
|
+
|
|
95
|
+
### Notes
|
|
96
|
+
|
|
97
|
+
- **Identical on SurrealDB 2.x and 3.x**: the cause was in how the ORM applied the SDK's values,
|
|
98
|
+
not in the server. The README's "Rich values inside sub-models" limitation of section 25 is
|
|
99
|
+
removed, and "After a write that returns the row" describes the new behaviour; top-level `date`,
|
|
100
|
+
`set` and `Range` fields still hold the SDK's value until the record is loaded again.
|
|
101
|
+
- Tested against SurrealDB 3.3.4 and 2.7.0 (the CI pins), plus 3.1.5 for backward compatibility.
|
|
102
|
+
|
|
8
103
|
## [0.24.0] - 2026-10-15
|
|
9
104
|
|
|
10
105
|
Geospatial fields: a model can declare geometry fields stored as SurrealDB's native geometries and
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.24.
|
|
3
|
+
Version: 0.24.3
|
|
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
|
|
@@ -2057,10 +2057,12 @@ sub.active_hours # Range(begin=BoundIncluded(value=9), end=BoundExcluded(value=
|
|
|
2057
2057
|
|
|
2058
2058
|
Optional fields (`ttl: timedelta | None = None`) behave the same. Values nested in containers
|
|
2059
2059
|
(`list[timedelta]`, `dict[str, date]`, a sub-model's fields) are sent the same way at any depth. On
|
|
2060
|
-
reads, a `timedelta` is converted from the SDK's duration
|
|
2061
|
-
|
|
2062
|
-
|
|
2063
|
-
|
|
2060
|
+
reads, a `timedelta` is converted from the SDK's duration at any depth too: a top-level field,
|
|
2061
|
+
`list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
|
|
2062
|
+
all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
|
|
2063
|
+
Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
|
|
2064
|
+
change it in place. A naive `datetime` stays naive on the instance and is read back as an aware UTC
|
|
2065
|
+
`datetime`, as before.
|
|
2064
2066
|
|
|
2065
2067
|
#### `Duration`
|
|
2066
2068
|
|
|
@@ -2197,10 +2199,10 @@ both lines.
|
|
|
2197
2199
|
|
|
2198
2200
|
#### Sets
|
|
2199
2201
|
|
|
2200
|
-
`set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.
|
|
2201
|
-
|
|
2202
|
-
SDK
|
|
2203
|
-
with `VALUE $value.distinct()`:
|
|
2202
|
+
`set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.3 a `TYPE set<…>` column
|
|
2203
|
+
stores the array as a native set, which the field reads back as the declared set (see
|
|
2204
|
+
[Values the SDK cannot read](#values-the-sdk-cannot-read)), but 3.1 refuses an array in it; to
|
|
2205
|
+
support 3.1, declare such columns `array<…>`, optionally with `VALUE $value.distinct()`:
|
|
2204
2206
|
|
|
2205
2207
|
```sql
|
|
2206
2208
|
DEFINE FIELD tags ON subscription TYPE array<string> VALUE $value.distinct();
|
|
@@ -2216,22 +2218,28 @@ Every value the ORM sends (a field, a filter value, a `call_function()` argument
|
|
|
2216
2218
|
variable) goes through the same check. A value SurrealDB would reject is refused before anything
|
|
2217
2219
|
is sent, with a plain `ValueError` that says why, never re-wrapped in a `SurrealDbError`:
|
|
2218
2220
|
|
|
2219
|
-
| Value
|
|
2220
|
-
|
|
|
2221
|
-
| A negative duration (a `timedelta`, the SDK's `Duration`)
|
|
2222
|
-
| A duration of `2**64` seconds or more
|
|
2223
|
-
| A zero duration,
|
|
2224
|
-
| A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1`
|
|
2225
|
-
| An `int` outside the signed 64-bit range
|
|
2226
|
-
| A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side
|
|
2227
|
-
| `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out`
|
|
2228
|
-
| `atomic_increment(field, <a duration>)`
|
|
2229
|
-
| In a live filter, a
|
|
2230
|
-
| A `Duration` or `Range` field given a value it does not accept
|
|
2231
|
-
|
|
2232
|
-
|
|
2233
|
-
|
|
2234
|
-
|
|
2221
|
+
| Value | Raised |
|
|
2222
|
+
| ----------------------------------------------------------------------------------------- | ---------------------------- |
|
|
2223
|
+
| A negative duration (a `timedelta`, the SDK's `Duration`) | `ValueError` |
|
|
2224
|
+
| A duration of `2**64` seconds or more | `ValueError` |
|
|
2225
|
+
| A zero duration, if neither the SDK nor the ORM reads one back (never with SDK 2.0.0) | `ValueError` |
|
|
2226
|
+
| A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1` | `ValueError` |
|
|
2227
|
+
| An `int` outside the signed 64-bit range | `ValueError` (use `Decimal`) |
|
|
2228
|
+
| A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side | `ValueError` |
|
|
2229
|
+
| `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out` | `ValueError` |
|
|
2230
|
+
| `atomic_increment(field, <a duration>)` | `TypeError` (use `merge()`) |
|
|
2231
|
+
| In a live filter, a negative or oversized duration, or a range bound with no literal form | `TypeError` from `live()` |
|
|
2232
|
+
| A `Duration` or `Range` field given a value it does not accept | Pydantic's `ValidationError` |
|
|
2233
|
+
|
|
2234
|
+
A zero duration (`timedelta(0)`, `Duration(0)`) is written, filtered and read back like any
|
|
2235
|
+
other, on both lines: the surrealdb SDK 2.0.0 cannot read one, but the clients the ORM opens do
|
|
2236
|
+
(see [Values the SDK cannot read](#values-the-sdk-cannot-read)); in the one case where nothing
|
|
2237
|
+
reads it back, a live filter refuses it with `TypeError` too. Since v0.24.3 the ORM stores zero
|
|
2238
|
+
durations, so a record it writes can hold one that a reader outside its clients cannot read: an
|
|
2239
|
+
`AsyncSurreal` client the application builds itself, or another service on the SDK 2.0.0. Filter
|
|
2240
|
+
"longer than zero" with `__gt=Duration(0)` or `__gte=Duration(1)`. `atomic_increment()` adds
|
|
2241
|
+
numbers only: SurrealDB 2.x ignores `+=` with a duration, so the ORM refuses it on both lines; set
|
|
2242
|
+
the new value with `merge()`:
|
|
2235
2243
|
|
|
2236
2244
|
```python
|
|
2237
2245
|
nonzero = await Subscription.objects().filter(trial__gte=Duration(1)).exec() # longer than zero
|
|
@@ -2241,25 +2249,50 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
|
|
|
2241
2249
|
#### After a write that returns the row
|
|
2242
2250
|
|
|
2243
2251
|
`save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and the `atomic_*` helpers
|
|
2244
|
-
apply the row the server returns
|
|
2245
|
-
|
|
2246
|
-
|
|
2247
|
-
`
|
|
2248
|
-
|
|
2249
|
-
|
|
2250
|
-
`
|
|
2251
|
-
|
|
2252
|
-
|
|
2252
|
+
apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
|
|
2253
|
+
fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
|
|
2254
|
+
that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
|
|
2255
|
+
`dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
|
|
2256
|
+
`timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
|
|
2257
|
+
model's own validators included, and a sub-model field holds its model instance, not the row's
|
|
2258
|
+
`dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
|
|
2259
|
+
whole does not validate, each such field is validated on its own, except one that the model's own
|
|
2260
|
+
validators could reshape (a `field_validator` on that field, a `model_validator`, a
|
|
2261
|
+
`model_post_init`): that one, like a value that does not validate, is applied as received, so
|
|
2262
|
+
these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
|
|
2263
|
+
(a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
|
|
2264
|
+
`filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
|
|
2265
|
+
stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
|
|
2266
|
+
top-level `date` and `set` fields while serialising them.
|
|
2253
2267
|
|
|
2254
2268
|
#### Values the SDK cannot read
|
|
2255
2269
|
|
|
2256
|
-
The surrealdb SDK 2.0.0 cannot decode a zero duration
|
|
2257
|
-
|
|
2258
|
-
|
|
2259
|
-
|
|
2260
|
-
|
|
2261
|
-
|
|
2262
|
-
|
|
2270
|
+
The surrealdb SDK 2.0.0 cannot decode a zero duration, a SurrealDB 3.x native set (a
|
|
2271
|
+
`TYPE set<…>` column on SurrealDB 3.3, see [Sets](#sets)) or a degenerate geometry (see
|
|
2272
|
+
[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)): one such value fails the whole
|
|
2273
|
+
response it is in. The clients the ORM opens read them anyway, through a hook around the SDK's own
|
|
2274
|
+
CBOR decoder that handles only these values; everything else reads exactly as the SDK reads it:
|
|
2275
|
+
|
|
2276
|
+
- a zero duration reads as zero: `timedelta(0)` or `Duration(0)` in a typed field, the SDK's
|
|
2277
|
+
`Duration(0)` in an untyped one;
|
|
2278
|
+
- a native set reads as a Python `set`, which `set[X]` and `frozenset[X]` fields validate, or as a
|
|
2279
|
+
`list` when its items are unhashable (record ids, objects, nested sets) or two of them are equal
|
|
2280
|
+
in Python, like `1` and `true`: every item the server holds comes back.
|
|
2281
|
+
|
|
2282
|
+
Written back through the ORM (`merge(v=row.v)`, or `update()`, which rewrites the whole row, the
|
|
2283
|
+
untouched fields included), a zero duration stays a duration, but a native set is stored as an
|
|
2284
|
+
array, like every set the ORM writes, unless its column is `TYPE set<…>` (see [Sets](#sets)), and
|
|
2285
|
+
a degenerate geometry as a plain object (see
|
|
2286
|
+
[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)). In an untyped field, `update()`
|
|
2287
|
+
flattens the SDK's `Duration(0)` into an object, like any SDK value there
|
|
2288
|
+
([#222](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/222)).
|
|
2289
|
+
|
|
2290
|
+
The hook is installed only while the installed SDK cannot decode these values, and only on the
|
|
2291
|
+
ORM's own clients (`SurrealDBConnectionManager.get_client()`, `ephemeral_client()`). An
|
|
2292
|
+
`AsyncSurreal` client the application builds itself keeps the SDK's behaviour and fails on them.
|
|
2293
|
+
A later SDK reads zero durations and native sets itself
|
|
2294
|
+
([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)), and the hook then
|
|
2295
|
+
leaves them to it.
|
|
2263
2296
|
|
|
2264
2297
|
#### Authentication
|
|
2265
2298
|
|
|
@@ -2273,8 +2306,10 @@ refused value raises `ValueError` before anything is sent.
|
|
|
2273
2306
|
|
|
2274
2307
|
Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
|
|
2275
2308
|
`timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
|
|
2276
|
-
`Range[T]` fields are lite additions. The full ORM also validates the rows its writes return
|
|
2277
|
-
|
|
2309
|
+
`Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
|
|
2310
|
+
validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
|
|
2311
|
+
top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
|
|
2312
|
+
[After a write that returns the row](#after-a-write-that-returns-the-row)).
|
|
2278
2313
|
|
|
2279
2314
|
### 25. Geospatial fields
|
|
2280
2315
|
|
|
@@ -2572,19 +2607,9 @@ for restaurant in await Restaurant.objects().all():
|
|
|
2572
2607
|
SurrealDB keeps a GeoJSON dict as a plain object, not a geometry: the full SurrealDB-ORM stores its
|
|
2573
2608
|
geometry fields that way, and so does any client that writes GeoJSON dicts. `nearby()` skips such
|
|
2574
2609
|
objects, `geo::*` functions and `geometry<…>` columns refuse them, and no SurrealQL cast turns them
|
|
2575
|
-
into geometries. A geometry field reads them (a GeoJSON object validates
|
|
2576
|
-
the instance back with a native geometry, so loading and
|
|
2577
|
-
|
|
2578
|
-
#### Rich values inside sub-models
|
|
2579
|
-
|
|
2580
|
-
After a call that applies the row the server returns (`refresh()`, `upsert()`, `merge()`,
|
|
2581
|
-
`patch()`, the `atomic_*` helpers, `save()` with an auto-generated id), a sub-model field holds the
|
|
2582
|
-
row's `dict`, as for every type (see [After a write that returns the row](#after-a-write-that-returns-the-row)).
|
|
2583
|
-
Geometries, durations and ranges inside it are written back as plain objects by a later `update()`
|
|
2584
|
-
or `upsert()`, and the next read of that record fails validation: read the record again with
|
|
2585
|
-
`get()` before writing it back. Top-level geometry fields and top-level typed containers
|
|
2586
|
-
(`list[GeometryPoint]`) are not affected: they are written back as geometries. A fix is tracked in
|
|
2587
|
-
[#228](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/228).
|
|
2610
|
+
into geometries. A geometry field reads them (a GeoJSON object validates, in a read and in the row
|
|
2611
|
+
a write returns), and `update()` writes the instance back with a native geometry, so loading and
|
|
2612
|
+
updating every record migrates a table.
|
|
2588
2613
|
|
|
2589
2614
|
#### Untyped fields
|
|
2590
2615
|
|
|
@@ -2609,10 +2634,24 @@ in type-checked code, use the aliases or the classes.
|
|
|
2609
2634
|
|
|
2610
2635
|
#### Geometries the SDK cannot read
|
|
2611
2636
|
|
|
2612
|
-
A degenerate geometry written by another client (a
|
|
2613
|
-
|
|
2614
|
-
|
|
2615
|
-
|
|
2637
|
+
A degenerate geometry written by another client (a line of fewer than 2 points, alone or inside
|
|
2638
|
+
another geometry, or a polygon ring of fewer than 4 points) cannot be decoded by the surrealdb SDK
|
|
2639
|
+
2.0.0, nor by its 3.0 pre-releases. The clients the ORM opens read it as its GeoJSON dict, such as
|
|
2640
|
+
`{"type": "LineString", "coordinates": [[1.0, 2.0]]}`; a multi-geometry or a collection holding
|
|
2641
|
+
one reads as GeoJSON as a whole (see
|
|
2642
|
+
[Values the SDK cannot read](#values-the-sdk-cannot-read) for where this applies):
|
|
2643
|
+
|
|
2644
|
+
- an untyped field (`Any`, `dict`), `raw_query()` and live notifications give that dict;
|
|
2645
|
+
- a geometry field refuses it with a `ValidationError` naming the field, since the ORM's geometry
|
|
2646
|
+
classes refuse degenerate values: `get()` raises it, and `filter().exec()` and `raw_query()`
|
|
2647
|
+
return such rows as dicts, as for any row that does not validate.
|
|
2648
|
+
|
|
2649
|
+
The ORM never writes one: its classes refuse such values, and so does the check of the SDK
|
|
2650
|
+
geometries it sends (see [Decimal coordinates of SDK geometries](#decimal-coordinates-of-sdk-geometries)).
|
|
2651
|
+
Written back, the dict an untyped field holds is stored as a plain object, not a geometry, on both
|
|
2652
|
+
lines, like any GeoJSON dict (see [Migrating stored GeoJSON](#migrating-stored-geojson)):
|
|
2653
|
+
`merge(v=row.v)` does it, and so does `update()` after a change to another field, since it
|
|
2654
|
+
rewrites the whole row.
|
|
2616
2655
|
|
|
2617
2656
|
#### Coming from the full SurrealDB-ORM
|
|
2618
2657
|
|
|
@@ -2642,8 +2681,6 @@ writes one: its classes refuse such values, and so does the check of the SDK geo
|
|
|
2642
2681
|
`surreal_orm`, `surreal_orm.fields`, `surreal_orm.geo`); `is_geo_field` and `get_geo_info` come
|
|
2643
2682
|
from `surreal_orm_lite.geo` (the full ORM: `surreal_orm.fields`). There is no
|
|
2644
2683
|
`surreal_orm_lite.fields` module.
|
|
2645
|
-
- **Sub-models after a write that returns the row** keep the row's `dict` (the full ORM validates
|
|
2646
|
-
those rows): see [Rich values inside sub-models](#rich-values-inside-sub-models).
|
|
2647
2684
|
|
|
2648
2685
|
---
|
|
2649
2686
|
|
|
@@ -2843,7 +2880,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
|
|
|
2843
2880
|
| `get_related(direction="both")` | out-neighbours, then in-neighbours; the order inside each group differs between versions | same on both lines | v0.22.0 |
|
|
2844
2881
|
| `UNIQUE` index on an edge table's `in, out`: a second edge for the same ordered pair | raises ("index … already contains"), through `insert_relation()` and `RELATE`; the reverse pair is allowed | same on both lines | v0.22.0 |
|
|
2845
2882
|
| Rich field types (`datetime`, `date`, `timedelta`/`Duration`, `Decimal`, `UUID`, `bytes`, `Range`, `set[X]`) | same on both lines: stored natively (sets as arrays) and read back as the declared type; a value the server would reject is refused with `ValueError` before anything is sent | same on both lines (verified on 3.3.4 and 3.1.5) | v0.23.0 |
|
|
2846
|
-
| `TYPE set<…>` columns (a `set[X]` or `frozenset[X]` field) | an array: the ORM reads back the declared set | 3.1: writing the array is refused. 3.3: stored as a native set the
|
|
2883
|
+
| `TYPE set<…>` columns (a `set[X]` or `frozenset[X]` field) | an array: the ORM reads back the declared set | 3.1: writing the array is refused. 3.3: stored as a native set, read back as the declared set (the SDK 2.0.0 alone cannot read it, section 24). Declare `array<…>` columns on 3.1.x | v0.23.0 |
|
|
2847
2884
|
| Reading a `Decimal` | trailing zeros kept (`Decimal("12.50")` reads `12.50`) | normalised (`12.5`); the values are equal | pre-existing (documented in v0.23.0) |
|
|
2848
2885
|
| 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 |
|
|
2849
2886
|
| 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 |
|
|
@@ -2006,10 +2006,12 @@ sub.active_hours # Range(begin=BoundIncluded(value=9), end=BoundExcluded(value=
|
|
|
2006
2006
|
|
|
2007
2007
|
Optional fields (`ttl: timedelta | None = None`) behave the same. Values nested in containers
|
|
2008
2008
|
(`list[timedelta]`, `dict[str, date]`, a sub-model's fields) are sent the same way at any depth. On
|
|
2009
|
-
reads, a `timedelta` is converted from the SDK's duration
|
|
2010
|
-
|
|
2011
|
-
|
|
2012
|
-
|
|
2009
|
+
reads, a `timedelta` is converted from the SDK's duration at any depth too: a top-level field,
|
|
2010
|
+
`list[timedelta]`, `dict[str, timedelta]`, `timedelta | str` or a sub-model's `timedelta` field
|
|
2011
|
+
all read a `timedelta`, floored to the microsecond (declare `Duration` to keep the nanoseconds).
|
|
2012
|
+
Your validators (any mode) and `model_post_init` still apply once to the value read, even when they
|
|
2013
|
+
change it in place. A naive `datetime` stays naive on the instance and is read back as an aware UTC
|
|
2014
|
+
`datetime`, as before.
|
|
2013
2015
|
|
|
2014
2016
|
#### `Duration`
|
|
2015
2017
|
|
|
@@ -2146,10 +2148,10 @@ both lines.
|
|
|
2146
2148
|
|
|
2147
2149
|
#### Sets
|
|
2148
2150
|
|
|
2149
|
-
`set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.
|
|
2150
|
-
|
|
2151
|
-
SDK
|
|
2152
|
-
with `VALUE $value.distinct()`:
|
|
2151
|
+
`set[X]`/`frozenset[X]` fields are stored as arrays. On SurrealDB 3.3 a `TYPE set<…>` column
|
|
2152
|
+
stores the array as a native set, which the field reads back as the declared set (see
|
|
2153
|
+
[Values the SDK cannot read](#values-the-sdk-cannot-read)), but 3.1 refuses an array in it; to
|
|
2154
|
+
support 3.1, declare such columns `array<…>`, optionally with `VALUE $value.distinct()`:
|
|
2153
2155
|
|
|
2154
2156
|
```sql
|
|
2155
2157
|
DEFINE FIELD tags ON subscription TYPE array<string> VALUE $value.distinct();
|
|
@@ -2165,22 +2167,28 @@ Every value the ORM sends (a field, a filter value, a `call_function()` argument
|
|
|
2165
2167
|
variable) goes through the same check. A value SurrealDB would reject is refused before anything
|
|
2166
2168
|
is sent, with a plain `ValueError` that says why, never re-wrapped in a `SurrealDbError`:
|
|
2167
2169
|
|
|
2168
|
-
| Value
|
|
2169
|
-
|
|
|
2170
|
-
| A negative duration (a `timedelta`, the SDK's `Duration`)
|
|
2171
|
-
| A duration of `2**64` seconds or more
|
|
2172
|
-
| A zero duration,
|
|
2173
|
-
| A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1`
|
|
2174
|
-
| An `int` outside the signed 64-bit range
|
|
2175
|
-
| A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side
|
|
2176
|
-
| `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out`
|
|
2177
|
-
| `atomic_increment(field, <a duration>)`
|
|
2178
|
-
| In a live filter, a
|
|
2179
|
-
| A `Duration` or `Range` field given a value it does not accept
|
|
2180
|
-
|
|
2181
|
-
|
|
2182
|
-
|
|
2183
|
-
|
|
2170
|
+
| Value | Raised |
|
|
2171
|
+
| ----------------------------------------------------------------------------------------- | ---------------------------- |
|
|
2172
|
+
| A negative duration (a `timedelta`, the SDK's `Duration`) | `ValueError` |
|
|
2173
|
+
| A duration of `2**64` seconds or more | `ValueError` |
|
|
2174
|
+
| A zero duration, if neither the SDK nor the ORM reads one back (never with SDK 2.0.0) | `ValueError` |
|
|
2175
|
+
| A finite `Decimal` whose integer part, rounded, exceeds `2**96 - 1` | `ValueError` |
|
|
2176
|
+
| An `int` outside the signed 64-bit range | `ValueError` (use `Decimal`) |
|
|
2177
|
+
| A `Range` side that is neither `BoundIncluded`/`BoundExcluded` nor an open side | `ValueError` |
|
|
2178
|
+
| `id__in=Range(…)`, `id__not_in=Range(…)`, or the same on an edge's `in`/`out` | `ValueError` |
|
|
2179
|
+
| `atomic_increment(field, <a duration>)` | `TypeError` (use `merge()`) |
|
|
2180
|
+
| In a live filter, a negative or oversized duration, or a range bound with no literal form | `TypeError` from `live()` |
|
|
2181
|
+
| A `Duration` or `Range` field given a value it does not accept | Pydantic's `ValidationError` |
|
|
2182
|
+
|
|
2183
|
+
A zero duration (`timedelta(0)`, `Duration(0)`) is written, filtered and read back like any
|
|
2184
|
+
other, on both lines: the surrealdb SDK 2.0.0 cannot read one, but the clients the ORM opens do
|
|
2185
|
+
(see [Values the SDK cannot read](#values-the-sdk-cannot-read)); in the one case where nothing
|
|
2186
|
+
reads it back, a live filter refuses it with `TypeError` too. Since v0.24.3 the ORM stores zero
|
|
2187
|
+
durations, so a record it writes can hold one that a reader outside its clients cannot read: an
|
|
2188
|
+
`AsyncSurreal` client the application builds itself, or another service on the SDK 2.0.0. Filter
|
|
2189
|
+
"longer than zero" with `__gt=Duration(0)` or `__gte=Duration(1)`. `atomic_increment()` adds
|
|
2190
|
+
numbers only: SurrealDB 2.x ignores `+=` with a duration, so the ORM refuses it on both lines; set
|
|
2191
|
+
the new value with `merge()`:
|
|
2184
2192
|
|
|
2185
2193
|
```python
|
|
2186
2194
|
nonzero = await Subscription.objects().filter(trial__gte=Duration(1)).exec() # longer than zero
|
|
@@ -2190,25 +2198,50 @@ await sub.merge(trial=sub.trial + timedelta(days=7)) #
|
|
|
2190
2198
|
#### After a write that returns the row
|
|
2191
2199
|
|
|
2192
2200
|
`save()` without an id, `refresh()`, `merge()`, `upsert()`, `patch()` and the `atomic_*` helpers
|
|
2193
|
-
apply the row the server returns
|
|
2194
|
-
|
|
2195
|
-
|
|
2196
|
-
`
|
|
2197
|
-
|
|
2198
|
-
|
|
2199
|
-
`
|
|
2200
|
-
|
|
2201
|
-
|
|
2201
|
+
apply the row the server returns to the instance. Top-level `timedelta`, `Duration` and geometry
|
|
2202
|
+
fields (since v0.24.0, see [section 25](#25-geospatial-fields)) are converted on the way. A field
|
|
2203
|
+
that holds a sub-model (a Pydantic model, a dataclass or a `TypedDict`, also inside `list[...]`,
|
|
2204
|
+
`dict[..., ...]` or `X | None`) or a `timedelta` below the top level (`list[timedelta]`,
|
|
2205
|
+
`timedelta | str`…) gets the value a read gives: the row goes through the model's validation, the
|
|
2206
|
+
model's own validators included, and a sub-model field holds its model instance, not the row's
|
|
2207
|
+
`dict`, with the ORM's durations, `timedelta`s, ranges and geometries inside. When the row as a
|
|
2208
|
+
whole does not validate, each such field is validated on its own, except one that the model's own
|
|
2209
|
+
validators could reshape (a `field_validator` on that field, a `model_validator`, a
|
|
2210
|
+
`model_post_init`): that one, like a value that does not validate, is applied as received, so
|
|
2211
|
+
these calls never fail on it. Other top-level `date`, `set` and `Range` fields hold the SDK's value
|
|
2212
|
+
(a midnight `datetime`, a `list`, the SDK's `Range`) until the record is loaded again (`get()`,
|
|
2213
|
+
`filter()`, …). Writing such an instance back is safe, sub-models included, since those values are
|
|
2214
|
+
stored the same way, although Pydantic warns (`PydanticSerializationUnexpectedValue`) about the
|
|
2215
|
+
top-level `date` and `set` fields while serialising them.
|
|
2202
2216
|
|
|
2203
2217
|
#### Values the SDK cannot read
|
|
2204
2218
|
|
|
2205
|
-
The surrealdb SDK 2.0.0 cannot decode a zero duration
|
|
2206
|
-
|
|
2207
|
-
|
|
2208
|
-
|
|
2209
|
-
|
|
2210
|
-
|
|
2211
|
-
|
|
2219
|
+
The surrealdb SDK 2.0.0 cannot decode a zero duration, a SurrealDB 3.x native set (a
|
|
2220
|
+
`TYPE set<…>` column on SurrealDB 3.3, see [Sets](#sets)) or a degenerate geometry (see
|
|
2221
|
+
[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)): one such value fails the whole
|
|
2222
|
+
response it is in. The clients the ORM opens read them anyway, through a hook around the SDK's own
|
|
2223
|
+
CBOR decoder that handles only these values; everything else reads exactly as the SDK reads it:
|
|
2224
|
+
|
|
2225
|
+
- a zero duration reads as zero: `timedelta(0)` or `Duration(0)` in a typed field, the SDK's
|
|
2226
|
+
`Duration(0)` in an untyped one;
|
|
2227
|
+
- a native set reads as a Python `set`, which `set[X]` and `frozenset[X]` fields validate, or as a
|
|
2228
|
+
`list` when its items are unhashable (record ids, objects, nested sets) or two of them are equal
|
|
2229
|
+
in Python, like `1` and `true`: every item the server holds comes back.
|
|
2230
|
+
|
|
2231
|
+
Written back through the ORM (`merge(v=row.v)`, or `update()`, which rewrites the whole row, the
|
|
2232
|
+
untouched fields included), a zero duration stays a duration, but a native set is stored as an
|
|
2233
|
+
array, like every set the ORM writes, unless its column is `TYPE set<…>` (see [Sets](#sets)), and
|
|
2234
|
+
a degenerate geometry as a plain object (see
|
|
2235
|
+
[Geometries the SDK cannot read](#geometries-the-sdk-cannot-read)). In an untyped field, `update()`
|
|
2236
|
+
flattens the SDK's `Duration(0)` into an object, like any SDK value there
|
|
2237
|
+
([#222](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/222)).
|
|
2238
|
+
|
|
2239
|
+
The hook is installed only while the installed SDK cannot decode these values, and only on the
|
|
2240
|
+
ORM's own clients (`SurrealDBConnectionManager.get_client()`, `ephemeral_client()`). An
|
|
2241
|
+
`AsyncSurreal` client the application builds itself keeps the SDK's behaviour and fails on them.
|
|
2242
|
+
A later SDK reads zero durations and native sets itself
|
|
2243
|
+
([#205](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/205)), and the hook then
|
|
2244
|
+
leaves them to it.
|
|
2212
2245
|
|
|
2213
2246
|
#### Authentication
|
|
2214
2247
|
|
|
@@ -2222,8 +2255,10 @@ refused value raises `ValueError` before anything is sent.
|
|
|
2222
2255
|
|
|
2223
2256
|
Plain `datetime`, `Decimal` and `UUID` annotations work as they do there. The full ORM has no
|
|
2224
2257
|
`timedelta` or `Range` fields and its `Duration` is a string: `timedelta`, `Duration` and
|
|
2225
|
-
`Range[T]` fields are lite additions. The full ORM also validates the rows its writes return
|
|
2226
|
-
|
|
2258
|
+
`Range[T]` fields are lite additions. The full ORM also validates the rows its writes return; lite
|
|
2259
|
+
validates the sub-model, geometry and nested `timedelta` fields of those rows and converts
|
|
2260
|
+
top-level durations, while top-level `date`, `set` and `Range` fields keep the SDK's value (see
|
|
2261
|
+
[After a write that returns the row](#after-a-write-that-returns-the-row)).
|
|
2227
2262
|
|
|
2228
2263
|
### 25. Geospatial fields
|
|
2229
2264
|
|
|
@@ -2521,19 +2556,9 @@ for restaurant in await Restaurant.objects().all():
|
|
|
2521
2556
|
SurrealDB keeps a GeoJSON dict as a plain object, not a geometry: the full SurrealDB-ORM stores its
|
|
2522
2557
|
geometry fields that way, and so does any client that writes GeoJSON dicts. `nearby()` skips such
|
|
2523
2558
|
objects, `geo::*` functions and `geometry<…>` columns refuse them, and no SurrealQL cast turns them
|
|
2524
|
-
into geometries. A geometry field reads them (a GeoJSON object validates
|
|
2525
|
-
the instance back with a native geometry, so loading and
|
|
2526
|
-
|
|
2527
|
-
#### Rich values inside sub-models
|
|
2528
|
-
|
|
2529
|
-
After a call that applies the row the server returns (`refresh()`, `upsert()`, `merge()`,
|
|
2530
|
-
`patch()`, the `atomic_*` helpers, `save()` with an auto-generated id), a sub-model field holds the
|
|
2531
|
-
row's `dict`, as for every type (see [After a write that returns the row](#after-a-write-that-returns-the-row)).
|
|
2532
|
-
Geometries, durations and ranges inside it are written back as plain objects by a later `update()`
|
|
2533
|
-
or `upsert()`, and the next read of that record fails validation: read the record again with
|
|
2534
|
-
`get()` before writing it back. Top-level geometry fields and top-level typed containers
|
|
2535
|
-
(`list[GeometryPoint]`) are not affected: they are written back as geometries. A fix is tracked in
|
|
2536
|
-
[#228](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/228).
|
|
2559
|
+
into geometries. A geometry field reads them (a GeoJSON object validates, in a read and in the row
|
|
2560
|
+
a write returns), and `update()` writes the instance back with a native geometry, so loading and
|
|
2561
|
+
updating every record migrates a table.
|
|
2537
2562
|
|
|
2538
2563
|
#### Untyped fields
|
|
2539
2564
|
|
|
@@ -2558,10 +2583,24 @@ in type-checked code, use the aliases or the classes.
|
|
|
2558
2583
|
|
|
2559
2584
|
#### Geometries the SDK cannot read
|
|
2560
2585
|
|
|
2561
|
-
A degenerate geometry written by another client (a
|
|
2562
|
-
|
|
2563
|
-
|
|
2564
|
-
|
|
2586
|
+
A degenerate geometry written by another client (a line of fewer than 2 points, alone or inside
|
|
2587
|
+
another geometry, or a polygon ring of fewer than 4 points) cannot be decoded by the surrealdb SDK
|
|
2588
|
+
2.0.0, nor by its 3.0 pre-releases. The clients the ORM opens read it as its GeoJSON dict, such as
|
|
2589
|
+
`{"type": "LineString", "coordinates": [[1.0, 2.0]]}`; a multi-geometry or a collection holding
|
|
2590
|
+
one reads as GeoJSON as a whole (see
|
|
2591
|
+
[Values the SDK cannot read](#values-the-sdk-cannot-read) for where this applies):
|
|
2592
|
+
|
|
2593
|
+
- an untyped field (`Any`, `dict`), `raw_query()` and live notifications give that dict;
|
|
2594
|
+
- a geometry field refuses it with a `ValidationError` naming the field, since the ORM's geometry
|
|
2595
|
+
classes refuse degenerate values: `get()` raises it, and `filter().exec()` and `raw_query()`
|
|
2596
|
+
return such rows as dicts, as for any row that does not validate.
|
|
2597
|
+
|
|
2598
|
+
The ORM never writes one: its classes refuse such values, and so does the check of the SDK
|
|
2599
|
+
geometries it sends (see [Decimal coordinates of SDK geometries](#decimal-coordinates-of-sdk-geometries)).
|
|
2600
|
+
Written back, the dict an untyped field holds is stored as a plain object, not a geometry, on both
|
|
2601
|
+
lines, like any GeoJSON dict (see [Migrating stored GeoJSON](#migrating-stored-geojson)):
|
|
2602
|
+
`merge(v=row.v)` does it, and so does `update()` after a change to another field, since it
|
|
2603
|
+
rewrites the whole row.
|
|
2565
2604
|
|
|
2566
2605
|
#### Coming from the full SurrealDB-ORM
|
|
2567
2606
|
|
|
@@ -2591,8 +2630,6 @@ writes one: its classes refuse such values, and so does the check of the SDK geo
|
|
|
2591
2630
|
`surreal_orm`, `surreal_orm.fields`, `surreal_orm.geo`); `is_geo_field` and `get_geo_info` come
|
|
2592
2631
|
from `surreal_orm_lite.geo` (the full ORM: `surreal_orm.fields`). There is no
|
|
2593
2632
|
`surreal_orm_lite.fields` module.
|
|
2594
|
-
- **Sub-models after a write that returns the row** keep the row's `dict` (the full ORM validates
|
|
2595
|
-
those rows): see [Rich values inside sub-models](#rich-values-inside-sub-models).
|
|
2596
2633
|
|
|
2597
2634
|
---
|
|
2598
2635
|
|
|
@@ -2792,7 +2829,7 @@ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v
|
|
|
2792
2829
|
| `get_related(direction="both")` | out-neighbours, then in-neighbours; the order inside each group differs between versions | same on both lines | v0.22.0 |
|
|
2793
2830
|
| `UNIQUE` index on an edge table's `in, out`: a second edge for the same ordered pair | raises ("index … already contains"), through `insert_relation()` and `RELATE`; the reverse pair is allowed | same on both lines | v0.22.0 |
|
|
2794
2831
|
| Rich field types (`datetime`, `date`, `timedelta`/`Duration`, `Decimal`, `UUID`, `bytes`, `Range`, `set[X]`) | same on both lines: stored natively (sets as arrays) and read back as the declared type; a value the server would reject is refused with `ValueError` before anything is sent | same on both lines (verified on 3.3.4 and 3.1.5) | v0.23.0 |
|
|
2795
|
-
| `TYPE set<…>` columns (a `set[X]` or `frozenset[X]` field) | an array: the ORM reads back the declared set | 3.1: writing the array is refused. 3.3: stored as a native set the
|
|
2832
|
+
| `TYPE set<…>` columns (a `set[X]` or `frozenset[X]` field) | an array: the ORM reads back the declared set | 3.1: writing the array is refused. 3.3: stored as a native set, read back as the declared set (the SDK 2.0.0 alone cannot read it, section 24). Declare `array<…>` columns on 3.1.x | v0.23.0 |
|
|
2796
2833
|
| Reading a `Decimal` | trailing zeros kept (`Decimal("12.50")` reads `12.50`) | normalised (`12.5`); the values are equal | pre-existing (documented in v0.23.0) |
|
|
2797
2834
|
| 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 |
|
|
2798
2835
|
| 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 |
|