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.
Files changed (50) hide show
  1. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/CHANGELOG.md +169 -0
  2. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/PKG-INFO +369 -43
  3. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/README.md +368 -42
  4. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/__init__.py +5 -1
  6. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/cache.py +11 -1
  7. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/edge.py +5 -4
  8. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/model_auth.py +10 -6
  9. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/model_base.py +88 -67
  10. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/model_ddl.py +8 -1
  11. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/query_set.py +365 -41
  12. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/search.py +187 -14
  13. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/subquery.py +9 -0
  14. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/time_travel.py +24 -0
  15. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/transaction.py +4 -2
  16. surreal_orm_lite-0.36.1/src/surreal_orm_lite/vector.py +609 -0
  17. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/.gitignore +0 -0
  18. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/LICENSE +0 -0
  19. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/Makefile +0 -0
  20. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/_sdk.py +0 -0
  21. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/aggregations.py +0 -0
  22. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/auth.py +0 -0
  23. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/changefeed.py +0 -0
  24. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/concurrency.py +0 -0
  25. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/connection_config.py +0 -0
  26. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/connection_manager.py +0 -0
  27. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/constants.py +0 -0
  28. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/decoding.py +0 -0
  29. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/define_parser.py +0 -0
  30. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/embedded.py +0 -0
  31. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/encoding.py +0 -0
  32. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/enum.py +0 -0
  33. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/exceptions.py +0 -0
  34. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/functions.py +0 -0
  35. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/geo.py +0 -0
  36. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/introspection.py +0 -0
  37. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/live.py +0 -0
  38. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/model_generator.py +0 -0
  39. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/py.typed +0 -0
  40. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/q.py +0 -0
  41. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/routing.py +0 -0
  42. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/schema.py +0 -0
  43. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/schema_state.py +0 -0
  44. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/signals.py +0 -0
  45. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/surql_literal.py +0 -0
  46. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
  47. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/testing/database.py +0 -0
  48. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  49. {surreal_orm_lite-0.35.4 → surreal_orm_lite-0.36.1}/src/surreal_orm_lite/types.py +0 -0
  50. {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