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