surreal-orm-lite 0.35.4__tar.gz → 0.36.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/CHANGELOG.md +169 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/PKG-INFO +369 -43
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/README.md +368 -42
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/pyproject.toml +1 -1
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/__init__.py +5 -1
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/cache.py +11 -1
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/edge.py +5 -4
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/model_auth.py +10 -6
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/model_base.py +88 -67
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/model_ddl.py +8 -1
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/query_set.py +365 -41
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/search.py +187 -14
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/subquery.py +9 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/time_travel.py +24 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/transaction.py +4 -2
- surreal_orm_lite-0.36.1/src/surreal_orm_lite/vector.py +609 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/.gitignore +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/LICENSE +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/Makefile +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/define_parser.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/introspection.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/model_generator.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/schema.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/schema_state.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/types.py +0 -0
- {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/utils.py +0 -0
|
@@ -5,6 +5,175 @@ 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.36.1] - 2026-10-23
|
|
9
|
+
|
|
10
|
+
Follow-ups to the review of v0.35.4 (#315): an instance write that the model refuses (a
|
|
11
|
+
materialized view, a snapshot read with `as_of()`, an auth model with an excluded signup field)
|
|
12
|
+
now leaves its transaction exactly as it was, and the docstring of `access_ddl()` lists every call
|
|
13
|
+
that refuses an excluded signup field. No new public API.
|
|
14
|
+
|
|
15
|
+
### Fixed
|
|
16
|
+
|
|
17
|
+
- **A refused instance write no longer marks its table as written on the transaction** (#315).
|
|
18
|
+
With `tx=`, the model's own refusals ran after the ORM had noted the model's table on the
|
|
19
|
+
transaction. A refused `update(tx=tx)` or `upsert(tx=tx)` (materialized view, snapshot, excluded
|
|
20
|
+
signup field), a `save()`, `merge()`, `patch()`, `atomic_*()` or `delete()` refused on a view
|
|
21
|
+
or a snapshot, or a `relate()`, `remove_relation()` or `remove_all_relations()` refused on a
|
|
22
|
+
snapshot queued no statement but left the table noted. A caller that caught the error and kept using the
|
|
23
|
+
transaction then had a later `define_indexes(tx=tx)` on that table refused by the v0.35.3 check
|
|
24
|
+
(#304), and the commit dropped the table's cached reads although nothing was written. These
|
|
25
|
+
refusals now run right after the connection check and before anything is noted: the transaction
|
|
26
|
+
keeps no statement and no table, `define_indexes(tx=tx)` is accepted, and the refused call
|
|
27
|
+
invalidates no cached read, with a transaction or without. The v0.35.4 entry's "nothing is added
|
|
28
|
+
to the transaction" now holds for the transaction's bookkeeping too. Refusal order (view,
|
|
29
|
+
snapshot, then excluded signup field) and messages are unchanged; the behaviour is the same on
|
|
30
|
+
SurrealDB 2.x and 3.x and on both transaction strategies.
|
|
31
|
+
|
|
32
|
+
### Changed
|
|
33
|
+
|
|
34
|
+
- **The atomic helpers and an edge's `save()` refuse a view or a snapshot before checking their
|
|
35
|
+
arguments** (#315). `atomic_append()`, `atomic_remove()`, `atomic_set_add()`,
|
|
36
|
+
`atomic_increment()` and the `atomic_*_many()` helpers checked the field name (`atomic_increment()`
|
|
37
|
+
a duration amount, the `atomic_*_many()` helpers a `values` that is not a list) before the view
|
|
38
|
+
and snapshot refusals: on a view or a snapshot, an invalid argument now raises the view's
|
|
39
|
+
`TypeError` or the snapshot's `SurrealDbError` instead of the argument's error. An edge read with
|
|
40
|
+
`as_of()` raises the snapshot error before the `save(server_values=…)` and `save(extra_vars=…)`
|
|
41
|
+
refusal. Valid calls are unchanged.
|
|
42
|
+
|
|
43
|
+
### Notes
|
|
44
|
+
|
|
45
|
+
- **Docs**: the `Raises` section of `access_ddl()` lists every call that refuses an auth model
|
|
46
|
+
with an excluded signup field, as `signup()` and the error message do: `table_ddl()`,
|
|
47
|
+
`define_table()`, `define_access()`, `signup()`, `signin()`, `authenticate()`, `refresh()`,
|
|
48
|
+
`update()` and `upsert()`.
|
|
49
|
+
- Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0, plus 3.1.5 for backward
|
|
50
|
+
compatibility.
|
|
51
|
+
|
|
52
|
+
## [0.36.0] - 2026-10-23
|
|
53
|
+
|
|
54
|
+
Vector search: a queryset finds the records whose vector is nearest to a query vector with the
|
|
55
|
+
full SurrealDB-ORM's `similar_to()`, each record's distance set as `_knn_distance`, over the
|
|
56
|
+
vector fields a model declares with `VectorField` and the HNSW indexes it declares with
|
|
57
|
+
`Index(hnsw=True)` and applies with `define_indexes()`. SurrealDB searches the index and computes
|
|
58
|
+
the distances on the server; the ORM binds the query vector as a query variable. The same code
|
|
59
|
+
runs on SurrealDB 2.x, 3.x and the embedded engine. The second minor of Tier 3's search phase.
|
|
60
|
+
|
|
61
|
+
### Added
|
|
62
|
+
|
|
63
|
+
- **`QuerySet.similar_to(field, vector, limit=10, *, ef=None, dist=None)`**, the full
|
|
64
|
+
SurrealDB-ORM's method: keeps the `limit` records whose `field` vector is nearest to `vector`,
|
|
65
|
+
through the field's HNSW index (SurrealDB's KNN operator). The field is a Python field name (an
|
|
66
|
+
aliased field searches its column) or a dotted path; the vector is a `list` or `tuple` of finite
|
|
67
|
+
numbers, bound, never written into the statement. `exec()`, `first()` and `get()` without an id
|
|
68
|
+
set each record's distance as `_knn_distance`, never written back (`model_dump()`, `save()` and
|
|
69
|
+
`update()` leave it out); without `order_by()` the records come nearest first, and
|
|
70
|
+
`limit()`/`offset()` page through them. A second `similar_to()` replaces the first. **`dist=`**
|
|
71
|
+
is an addition: an exact, brute-force search that needs no index. `similar_to()` applies
|
|
72
|
+
wherever `filter()` does, AND-ed with `filter()`, `Q`, `nearby()`, `search()` and a `Subquery`
|
|
73
|
+
filter: `exec()`, `first()`, `get()` without an id, `count()`, `exists()`, the aggregations,
|
|
74
|
+
`values()` groups, `bulk_update()`, `bulk_delete()`, `patch()` and a `Subquery` (the full ORM
|
|
75
|
+
applies it to `exec()` only). `get(<id>)` and `all()` ignore it, as they ignore `filter()`. With
|
|
76
|
+
`search()`, the records matching the text are ranked by the vector.
|
|
77
|
+
- **`VectorField[d]`** (or `VectorField[d, "F64"]`), the full ORM's vector field, **and its typed
|
|
78
|
+
form `Vector`**: `embedding: Annotated[list[float] | None, Vector(1536)] = None`, which type
|
|
79
|
+
checkers accept where they reject `VectorField[1536]`. Both spellings are one field, optional and
|
|
80
|
+
`None` by default: `None` or a `list`/`tuple` of exactly `d` finite real numbers, kept as a
|
|
81
|
+
`list[float]` and checked on every write and every read (a stored vector of another length makes
|
|
82
|
+
`exec()` return its row as a dict), with a fixed-length array JSON schema. `define_table()`
|
|
83
|
+
writes the column `option<array<float, d>>`. `get_vector_info()` and `is_vector_field()`, from
|
|
84
|
+
`surreal_orm_lite.vector`, read either spelling.
|
|
85
|
+
- **Vector indexes: `Index(name, field, hnsw=True, dimension=, dist=, vector_type=, efc=, m=)`**,
|
|
86
|
+
with the full ORM's `CreateIndex` arguments: `dimension` (required, 1 to 65535), `dist`
|
|
87
|
+
(`EUCLIDEAN` by default, `COSINE`, `MANHATTAN`, `CHEBYSHEV` or `HAMMING`, in any case),
|
|
88
|
+
`vector_type` (`F64`, `F32` by default, `I64`, `I32` or `I16`), `efc` (1 to 65535, 150 by
|
|
89
|
+
default) and `m` (2 to 127, 12 by default). A vector index covers one field and is listed in
|
|
90
|
+
`SurrealConfigDict(indexes=[...])` next to the full-text ones; its attributes hold what was
|
|
91
|
+
declared. When the class is defined, two vector indexes on one column are refused, and so is a
|
|
92
|
+
vector index whose dimension or storage type differs from its field's `VectorField`.
|
|
93
|
+
`index_ddl()` renders the same `HNSW` statement for SurrealDB 2.x and 3.x; `define_indexes()`
|
|
94
|
+
compares a declared vector index with the stored one and redefines it only when an option, the
|
|
95
|
+
field or the comment changed, so an unchanged vector index is never rebuilt; `remove_index()`
|
|
96
|
+
removes one by name.
|
|
97
|
+
- README section 37, "Vector search (`similar_to()`, `VectorField`, `Index(hnsw=True)`)"
|
|
98
|
+
(declaring and applying, type checkers, finding the nearest, other conditions, what SurrealDB
|
|
99
|
+
decides, what is not supported, a note for users of the full SurrealDB-ORM), eight rows of the
|
|
100
|
+
"ORM behaviour: SurrealDB 2.x vs 3.x" table and one of the embedded engine's, and the example
|
|
101
|
+
notebook `examples/v0.36.0_vector_search.ipynb`.
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
class Document(BaseSurrealModel):
|
|
105
|
+
model_config = SurrealConfigDict(
|
|
106
|
+
table_name="document",
|
|
107
|
+
indexes=[Index("document_embedding", "embedding", hnsw=True, dimension=3, dist="cosine")],
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
id: str | None = None
|
|
111
|
+
title: str
|
|
112
|
+
category: str = ""
|
|
113
|
+
embedding: VectorField[3]
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
await Document.define_table()
|
|
117
|
+
await Document.define_indexes() # [] when nothing changed: the vector index is not rebuilt
|
|
118
|
+
pets = Document.objects().filter(category="pets").similar_to("embedding", [1.0, 0.0, 0.0], 3)
|
|
119
|
+
for document in await pets.exec(): # nearest first
|
|
120
|
+
print(document.title, document._knn_distance)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Notes
|
|
124
|
+
|
|
125
|
+
- **`limit` and `ef` go from 1 to 10 000**, checked before any request with the vector's numbers,
|
|
126
|
+
its length (when the model declares the field's dimension, by its `VectorField` or its vector
|
|
127
|
+
index) and the `Index` vector arguments; the full ORM sends any value. **`ef`** (100 by default)
|
|
128
|
+
**is written raised to `limit`** on every line: SurrealDB 2.x would return at most `ef` records.
|
|
129
|
+
- **Every HNSW option is written** (`DIST`, `TYPE`, `EFC` and `M`, SurrealDB's defaults when not
|
|
130
|
+
given), so every engine stores the same index: the embedded engine would otherwise store `F64`
|
|
131
|
+
vectors where servers store `F32`. `Index` keeps the options as declared.
|
|
132
|
+
- **Other conditions select the records first, then `similar_to()` keeps the nearest among
|
|
133
|
+
them.** SurrealDB 3.x applies them during the index search. SurrealDB 2.x and the embedded engine
|
|
134
|
+
answer too few records, or none, next to many conditions (one on an indexed field among them),
|
|
135
|
+
so there the ORM selects the records matching every other condition — a full-text match
|
|
136
|
+
included — in a `LET` first, which is slower: upgrade to SurrealDB 3.x for large tables.
|
|
137
|
+
- **Search annotations combine with `similar_to()` on SurrealDB 3.x; on 2.x and the embedded
|
|
138
|
+
engine the ORM refuses them, since the matches are selected first, while `count()`, `exists()`
|
|
139
|
+
and the aggregations still answer.** The refusal is a `SurrealDbError` from `exec()`, `first()`
|
|
140
|
+
and `get()` without an id, before the statement is sent.
|
|
141
|
+
- **`bulk_update()`, `bulk_delete()` and `patch()` of a `similar_to()` queryset write the `limit`
|
|
142
|
+
nearest records by their ids**, selected first, and return their number: they write the records
|
|
143
|
+
the same read returns, on every line. A write holding the KNN operator would act on every
|
|
144
|
+
matching record on SurrealDB 2.x, and on none next to a range on an indexed field on 3.x.
|
|
145
|
+
- **HNSW is approximate**: with a condition that keeps few records, a search can return fewer than
|
|
146
|
+
`limit` records, depending on how the index was built, more often on SurrealDB 2.x and the
|
|
147
|
+
embedded engine; `dist=` is exact. Distances are computed in the index's `vector_type` (`F32`,
|
|
148
|
+
single precision, by default), `dist=`'s in double precision.
|
|
149
|
+
- **A field without an HNSW index answers no record** (`dist=` needs none). A query vector whose
|
|
150
|
+
length differs from the index's, on a model that does not declare the dimension, raises
|
|
151
|
+
`SurrealDbError` naming the field and both lengths. A zero query vector with `COSINE` raises
|
|
152
|
+
`ValueError`: it has no distance.
|
|
153
|
+
- **Refused before any request** (`SurrealDbError`): `similar_to()` with `as_of()`, in either order
|
|
154
|
+
and in a subquery under it (the index holds the records' current vectors); with `live()` and
|
|
155
|
+
`watch()`, in their condition or in a `Subquery`, since SurrealDB accepts a live query whose
|
|
156
|
+
condition holds the vector search but never notifies it — read the nearest records with
|
|
157
|
+
`similar_to()` and watch them by id; and with `changes()`.
|
|
158
|
+
- **Moving a table to another dimension** (a new embedding model): declare the field
|
|
159
|
+
`list[float] | None` without its vector index while records of both lengths exist, then the new
|
|
160
|
+
`VectorField[d]` and a matching index; README section 37 gives the steps.
|
|
161
|
+
- **SurrealDB 3.1** (tested with 3.1.5 for backward compatibility): a field without a vector index
|
|
162
|
+
answers every record, and `similar_to()` next to `search()` every match, each with no distance.
|
|
163
|
+
- **Not yet**: `MTREE` indexes (SurrealDB 3.x refuses them; one stored under a declared index's
|
|
164
|
+
name is redefined `HNSW`), the `MINKOWSKI`, `JACCARD` and `PEARSON` distances, `F16` vectors,
|
|
165
|
+
`DISKANN` indexes, `Index(concurrently=True)`, vector functions in `annotate()` and
|
|
166
|
+
`VectorField` in generated models. `hybrid_search()` comes in v0.37.0.
|
|
167
|
+
- **Undeclared keys in list items: fixed in SurrealDB 3.4** (#308): SurrealDB 3.x (measured on
|
|
168
|
+
3.1.5 and 3.3.4) keeps a key a `SCHEMAFULL` table does not define in the items of a list whose
|
|
169
|
+
items define a field, as the 0.35.2 note on #301 below says. SurrealDB 3.4 (nightly at the time
|
|
170
|
+
of writing) refuses it there too, as SurrealDB's documentation of `FLEXIBLE` says. README section
|
|
171
|
+
35 and the 3.x cell of the v0.34.0 row of "ORM behaviour: SurrealDB 2.x vs 3.x" now say so. The
|
|
172
|
+
raw test also measures an object inside a list item that defines no key: refused on 3.x
|
|
173
|
+
(`no such field exists`), emptied on 2.x and the embedded engine. No ORM behaviour changes.
|
|
174
|
+
- Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
|
|
175
|
+
plus 3.1.5 for backward compatibility.
|
|
176
|
+
|
|
8
177
|
## [0.35.4] - 2026-10-23
|
|
9
178
|
|
|
10
179
|
`update()`, `upsert()`, `authenticate()` and `refresh()` refuse an auth model whose signup field
|