surreal-orm-lite 0.36.5__tar.gz → 0.37.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 (51) hide show
  1. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/CHANGELOG.md +148 -1
  2. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/PKG-INFO +210 -16
  3. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/README.md +209 -15
  4. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/__init__.py +1 -1
  6. surreal_orm_lite-0.37.1/src/surreal_orm_lite/hybrid.py +186 -0
  7. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/model_base.py +106 -11
  8. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/query_set.py +345 -15
  9. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/search.py +18 -15
  10. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/utils.py +22 -0
  11. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/vector.py +68 -50
  12. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/.gitignore +0 -0
  13. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/LICENSE +0 -0
  14. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/Makefile +0 -0
  15. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/_sdk.py +0 -0
  16. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/aggregations.py +0 -0
  17. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/auth.py +0 -0
  18. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/cache.py +0 -0
  19. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/changefeed.py +0 -0
  20. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/concurrency.py +0 -0
  21. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/connection_config.py +0 -0
  22. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/connection_manager.py +0 -0
  23. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/constants.py +0 -0
  24. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/decoding.py +0 -0
  25. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/define_parser.py +0 -0
  26. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/edge.py +0 -0
  27. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/embedded.py +0 -0
  28. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/encoding.py +0 -0
  29. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/enum.py +0 -0
  30. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/exceptions.py +0 -0
  31. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/functions.py +0 -0
  32. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/geo.py +0 -0
  33. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/introspection.py +0 -0
  34. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/live.py +0 -0
  35. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/model_auth.py +0 -0
  36. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/model_ddl.py +0 -0
  37. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/model_generator.py +0 -0
  38. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/py.typed +0 -0
  39. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/q.py +0 -0
  40. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/routing.py +0 -0
  41. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/schema.py +0 -0
  42. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/schema_state.py +0 -0
  43. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/signals.py +0 -0
  44. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/subquery.py +0 -0
  45. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/surql_literal.py +0 -0
  46. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
  47. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/testing/database.py +0 -0
  48. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  49. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/time_travel.py +0 -0
  50. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/transaction.py +0 -0
  51. {surreal_orm_lite-0.36.5 → surreal_orm_lite-0.37.1}/src/surreal_orm_lite/types.py +0 -0
@@ -5,6 +5,152 @@ 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.37.1] - 2026-10-24
9
+
10
+ Follow-ups to the review of v0.36.3 (#327): a `Literal[None]` member of a vector field's union
11
+ reads as `None`, and a vector field declared through a forward reference gets the vector checks
12
+ of the `class` statement once its name resolves. Any model a forward reference left incomplete is
13
+ completed before the ORM writes its DDL or builds a queryset. No new public API.
14
+
15
+ ### Fixed
16
+
17
+ - **`VectorField[d] | Literal[None]` is read as a vector field** (#327). Since v0.36.3 a
18
+ `Literal[None]` union member counted as a type other than `None`: `get_vector_info()` and
19
+ `is_vector_field()` raised `ValueError` for that annotation and the `class` statement refused
20
+ the field, although `Literal[None]` admits only `None` and `define_table()` already read it as
21
+ `None`. Such a member now counts as `None`: the annotation gives `(d, 'F32')` wherever
22
+ `VectorField[d] | None` does (`get_vector_info()`, `is_vector_field()`, the `class`-statement
23
+ checks of a vector index, `similar_to()`, and `define_table()` with
24
+ `option<array<float, d>>`). A `Literal` holding another value (`Literal[None, "x"]`) next to a
25
+ marker is still refused.
26
+ - **A vector field declared through a forward reference is checked once its name resolves**
27
+ (#327). A field annotated with a name defined after the class (`e: "Later" = None`, then
28
+ `Later = VectorField[3]`) has no `Vector` marker at the `class` statement, so since v0.36.0 the
29
+ vector checks skipped it: a vector index of another dimension or storage type, or an ambiguous
30
+ annotation such as `Later = VectorField[3] | str`, was accepted once `model_rebuild()` or the
31
+ model's first use resolved the name. Until then, `table_ddl()` and `define_table()` wrote the
32
+ column as `any`, `define_indexes()` defined the index unchecked and `similar_to()` accepted a
33
+ query vector of any length, without an error. The checks now run again when Pydantic completes
34
+ the model (at `model_rebuild()`, or at its first instantiation, validation or JSON schema), and
35
+ the ORM completes such a model before `table_ddl()`, `define_table()`, `index_ddl()`,
36
+ `define_indexes()`, `get_indexes()` or a queryset (`similar_to()` included) reads it, resolving
37
+ the name as Pydantic's first instantiation does: with the local names of the caller, then the
38
+ names of the model's module (a caller's local name wins, and the field keeps what it resolved
39
+ to). The refusals are those of the field written directly, naming the model, the index and
40
+ the field, raised before anything is sent; a refused model stays incomplete, so each of these
41
+ calls raises the same error again. A matching index is accepted, and `similar_to()` checks the
42
+ query vector against the field's dimension. A name still undefined leaves the model incomplete
43
+ and read as before. A model complete at its `class` statement is checked there only, in the same
44
+ order and with the same messages.
45
+ - **Every model a forward reference left incomplete is completed before the ORM reads it**
46
+ (#327). The completion of the previous bullet applies to any model Pydantic could not complete
47
+ at its `class` statement, with or without a vector field: `table_ddl()`, `define_table()`,
48
+ `index_ddl()`, `define_indexes()`, `get_indexes()` and every queryset complete it first. Until
49
+ now such a model was read with its unresolved fields as `any` until `model_rebuild()` or its
50
+ first instance: in `Author` with `best: "Book | None" = None` and `score: "Score" = 0`, `Book`
51
+ and `Score = int` defined after it, `table_ddl()` and `define_table()` wrote `best TYPE any`
52
+ and `score TYPE any DEFAULT 0`, and the cross-connection check of a queryset that follows a
53
+ link (`fetch()`) saw no linked model in such a field. Its columns now get the resolved kinds,
54
+ whether or not the model was instantiated first — what these calls already wrote after an
55
+ instance: `best TYPE option<object> FLEXIBLE` and `score TYPE int DEFAULT 0` on a `SCHEMAFULL`
56
+ table —, and its links are resolved for the cross-connection check, without `model_rebuild()`.
57
+ **Upgrading**: `define_table()` on such a model now redefines a column it wrote `any` with its
58
+ kind, and SurrealDB checks the values written to that column against it from then on. A name
59
+ still undefined leaves the model read as before.
60
+
61
+ ### Notes
62
+
63
+ - **CHANGELOG correction**: the `### Changed` bullet of `## [0.36.3]` said that every spelling
64
+ v0.36.2 read as a vector field gives the same result. A field with two different `Vector`
65
+ markers, which v0.36.2 read by its first marker, is refused since v0.36.3: the sentence now
66
+ reads "Every spelling with a single `Vector` marker that v0.36.2 read as a vector field gives
67
+ the same result."
68
+ - **Docs**: README section 37 (Vector search) says that `get_vector_info()` and
69
+ `is_vector_field()` raise `ValueError` for a field or annotation with no single dimension (code
70
+ that scans the fields of a plain Pydantic model has no `class`-statement check, so it gets the
71
+ exception where v0.36.2 returned `False`), that a `Literal[None]` member counts as `None`, and
72
+ which calls check a field declared through a forward reference. Section 35 (Model table DDL)
73
+ says that such a field gets the kind of the type its name resolves to, before or after an
74
+ instance.
75
+ - The fixes are in the ORM's model checks, built on Pydantic's `__pydantic_on_complete__` hook
76
+ (available in the supported `pydantic>=2.13.4`): the behaviour is the same on SurrealDB 2.x and
77
+ 3.x and on the embedded engine. Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0,
78
+ plus 3.1.5 for backward compatibility.
79
+
80
+ ## [0.37.0] - 2026-10-24
81
+
82
+ Hybrid search: a queryset fuses the records nearest to a query vector, as `similar_to()` finds
83
+ them, and the best matches of a text, as `search()` ranks them, into one ranking by Reciprocal
84
+ Rank Fusion, with the full SurrealDB-ORM's `hybrid_search()`. SurrealDB 3.x fuses the two lists
85
+ with `search::rrf()`; SurrealDB 2.x and the embedded engine have no such function, so the ORM
86
+ fuses them with the same formula: the same two lists give the same records, scores and order on
87
+ every line. The third and last minor of Tier 3's search phase.
88
+
89
+ ### Added
90
+
91
+ - **`QuerySet.hybrid_search(*, vector_field, vector, vector_limit=20, text_field, text_query, text_limit=20, rrf_k=60, ef=None, dist=None)`**,
92
+ the full SurrealDB-ORM's method: each record gets 1 / (`rrf_k` + rank) from each list it is in,
93
+ its rank counted from 1, and the records come best fused score first. It returns a list of
94
+ dicts, as the full ORM does, each holding the record's fields keyed by their Python names (as
95
+ `exec()`'s dict rows are), `_rrf_score`, and `_knn_distance` and `_search_score` (`None` for a
96
+ record that only the other search found). The query vector and the text are bound as query
97
+ variables, never written into the statement. **`dist=`** is an addition: an exact scan that
98
+ needs no vector index, as in `similar_to()`. The queryset applies: its conditions select the
99
+ records of both lists, `select()` and `fetch()` apply to both (`id` always read),
100
+ `limit()`/`offset()` page through the fused records (at most `vector_limit + text_limit`), and
101
+ `cache()`, `objects(tx=)` and named connections apply as for `exec()`; the full ORM ignores them.
102
+ - README section 38, "Hybrid search (`hybrid_search()`, Reciprocal Rank Fusion)" (search, with the
103
+ queryset, what SurrealDB decides, what is not supported, a note for users of the full
104
+ SurrealDB-ORM), four rows of the "ORM behaviour: SurrealDB 2.x vs 3.x" table and one of the
105
+ embedded engine's, and the example notebook `examples/v0.37.0_hybrid_search.ipynb`.
106
+
107
+ ```python
108
+ results = await Passage.objects().filter(topic="tech").hybrid_search(
109
+ vector_field="embedding", vector=[0.0, 1.0, 0.0], vector_limit=4,
110
+ text_field="title", text_query="programming", text_limit=4,
111
+ )
112
+ for row in results: # best fused score first
113
+ print(row["id"], row["_rrf_score"], row["_knn_distance"], row["_search_score"])
114
+ ```
115
+
116
+ ### Notes
117
+
118
+ - **SurrealDB 3.x fuses with `search::rrf()`**, given both lists in one statement; **SurrealDB
119
+ 2.x and the embedded engine get the same fusion from the ORM**: the same records, scores and
120
+ order for the same two lists. The line is read from `client.version()`, as for `search()`'s
121
+ index keyword. Other conditions apply to both lists; on SurrealDB 2.x and the embedded engine
122
+ the vector list selects the records matching them first, as `similar_to()` does.
123
+ - **Equal fused scores come in a fixed order**: the vector list's first, then the full-text list's
124
+ for the records it alone found, on every line (SurrealDB's `search::rrf()` alone returns them in
125
+ no fixed order), so the same two lists always give the same page. Each list is SurrealDB's own:
126
+ BM25 scores depend on the line (a term found in more than half the documents scores `0.0` on 3.x
127
+ and below zero on 2.x and the embedded engine), and on SurrealDB 2.x and the embedded engine an
128
+ exact scan (`dist=`) picks among records at an equal distance at the `vector_limit`-th place in
129
+ no fixed order, as `similar_to()`'s does since v0.36.0: the vector list, and a page of the fused
130
+ records, can then change between two identical calls. The HNSW index, and SurrealDB 3.x's exact
131
+ scan, return the same list on every call.
132
+ - **Checked before any request**: both fields, the vector, `vector_limit` and `text_limit` (1 to
133
+ 10 000), `rrf_k` (0 to 10 000), `ef` and `dist`; the full ORM checks the field names only.
134
+ - **Refused before any request**: `order_by()`, `annotate()`, `values()`, `search()` and
135
+ `similar_to()` on the queryset (`ValueError`), and `as_of()` (`SurrealDbError`: the indexes hold
136
+ the records' current values). A model field stored under one of the seven names the method uses
137
+ for its own values (`rrf_score`, `_rrf_score`, `_knn_distance`, `_search_score`, `_hybrid_pos`,
138
+ `_hybrid_vec_pos`, `_hybrid_text_pos`) raises `ValueError`: store it under another name with
139
+ `Field(alias=...)`. On a SCHEMALESS table, a column with one of these names that the model does
140
+ not declare is not returned, even when `select()` names it.
141
+ - **Each search needs its index.** Without a full-text index on `text_field`, SurrealDB 3.3, 2.x
142
+ and the embedded engine refuse the search and `hybrid_search()` raises `SurrealDbError` naming
143
+ the field; SurrealDB 3.1 and 3.2 match nothing, so the vector list alone is fused. Without a
144
+ vector index on `vector_field`, the vector list is empty on SurrealDB 3.3, 2.x and the embedded
145
+ engine, so the full-text ranking alone is fused; SurrealDB 3.1 and 3.2 list the first
146
+ `vector_limit` records by id, with no distance. `dist=` needs no index.
147
+ - **Not yet**: `search::linear()` (weights and score normalisation), several full-text fields,
148
+ the full-text side's highlights, and search annotations next to `similar_to()` on SurrealDB 2.x
149
+ and the embedded engine, which the ORM still refuses there; `hybrid_search()` gives each record
150
+ found by both searches its BM25 score and its distance, on every line.
151
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
152
+ plus 3.1.5 for backward compatibility; the new behaviour rows were also measured on 3.2.6.
153
+
8
154
  ## [0.36.5] - 2026-10-24
9
155
 
10
156
  Follow-up to v0.36.1 (#315): a queryset write that the ORM refuses, and an instance write
@@ -138,7 +284,8 @@ Follow-up to the review of v0.36.0 (#316): a vector field declared with `| None`
138
284
  whether or not it declares indexes. Until v0.36.2 such a model was accepted (the first of two
139
285
  markers decided the checks, a union with another type was not a vector field).
140
286
  `get_vector_info()` and `is_vector_field()` raise the same `ValueError` for such a field or
141
- annotation. Every spelling that v0.36.2 read as a vector field gives the same result.
287
+ annotation. Every spelling with a single `Vector` marker that v0.36.2 read as a vector field
288
+ gives the same result.
142
289
 
143
290
  ### Notes
144
291
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.36.5
3
+ Version: 0.37.1
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
@@ -271,6 +271,7 @@ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads
271
271
  | Model table DDL (`define_table()`, `schema_mode`, `permissions`) | ✅ |
272
272
  | Full-text search (`search()`, BM25 score and highlights) | ✅ |
273
273
  | Vector search (`similar_to()`, KNN, HNSW indexes) | ✅ |
274
+ | Hybrid search (`hybrid_search()`, Reciprocal Rank Fusion) | ✅ |
274
275
 
275
276
  ### Supported Filter Lookups
276
277
 
@@ -5507,6 +5508,12 @@ Each column's `TYPE` comes from its annotation (`Annotated` unwrapped):
5507
5508
 
5508
5509
  Anything else is `any`.
5509
5510
 
5511
+ A field annotated with a name defined after the class (a forward reference: `score: "Score" = 0`, then `Score = int`)
5512
+ gets the kind of the type its name resolves to. Since v0.37.1, `table_ddl()` and `define_table()` complete such a model
5513
+ first, as its first instantiation does, so they write the same statements before and after an instance (`score` is
5514
+ `TYPE int DEFAULT 0`, which earlier versions wrote `TYPE any DEFAULT 0` until the model was instantiated or rebuilt). A
5515
+ name still undefined gives `any`.
5516
+
5510
5517
  - **Columns**: every field but `id` (and an edge's `in_` and `out`), under its column — its alias, if any
5511
5518
  ([section 20](#20-field-aliases-server_fields-and-mergerefreshfalse)) —, then the Pydantic `@computed_field`s; a
5512
5519
  `Field(exclude=True)` field is left out. A sub-model's fields follow its column (`address.city`, `subs.*.city`), its
@@ -6109,10 +6116,25 @@ print(await NoteV2.objects().search(text="physics").count())
6109
6116
  has already written records to the model's table with the ORM (`save()`, `objects(tx=…).bulk_create()`, …). The
6110
6117
  refusal covers every kind of index, not only full-text ones: a search would miss those records, and a `UNIQUE` index
6111
6118
  missing them would not enforce uniqueness for them. The refusal does not fail the block. `define_table(tx=…)`,
6112
- `define_relation(tx=…)` and a write to another table do not count, nor does a write the ORM refused for a
6113
- materialized view or a snapshot read with `as_of()` (a snapshot in `bulk_create()`'s list included), an `update()`,
6114
- `merge()`, `patch()`, `delete()` or `atomic_*()` call refused for a missing id, or a `patch()` refused for its
6115
- operations; a raw `tx.add()` is not tracked.
6119
+ `define_relation(tx=…)` and a write to another table do not count, nor does a write the ORM refused before sending or
6120
+ queuing it: one refused for a materialized view, a snapshot read with `as_of()`, an auth model with a
6121
+ `Field(exclude=True)` field SIGNUP writes, a `tx=` of another connection, or one of its arguments (a missing id,
6122
+ invalid patch operations, an invalid `server_values`/`extra_vars` pair or either one on an edge's `save()`, a computed
6123
+ field or an edge endpoint among the fields written, an atomic helper's field, amount or values, a subquery value in
6124
+ `bulk_update()`, a snapshot in `bulk_create()`'s list); a raw `tx.add()` is not tracked. Until
6125
+ [EulogySnowfall/SurrealDB-ORM-lite#325](https://github.com/EulogySnowfall/SurrealDB-ORM-lite/issues/325) is fixed,
6126
+ some refusals made while the write is built or its values are encoded still count, although nothing was sent or
6127
+ queued: `upsert()` without an id, `save(tx=…)` without an id in a buffered transaction, a field name or an
6128
+ `extra_vars` key refused while the statement of `save(server_values=…)` or `merge(server_values=…)` is compiled (an
6129
+ invalid name, a key that collides with an internal binding), the argument checks of `relate()`, `remove_relation()`
6130
+ and `remove_all_relations()` (an invalid edge name, or an empty list of edges, counts as a write to every table, so
6131
+ every later `define_indexes(tx=…)` in the block is refused), a field name `bulk_update()` refuses, a filter refused
6132
+ while the statement of `objects(tx=…).bulk_update()`, `bulk_delete()` or `patch()` is compiled, an edge id of another
6133
+ table in an edge's `save()` or `bulk_create()`, and a value the ORM cannot send, in any write (a field, a filter, a
6134
+ patch operation, an atomic helper's value or amount, a relation's data, `extra_vars`): a `field_serializer` that
6135
+ raises, or one of the [values refused before sending](#values-refused-before-sending), such as a negative duration,
6136
+ an `int` outside the signed 64-bit range or a `Decimal` out of range. A write refused first for one of the arguments
6137
+ listed above, such as an `update()` or a `merge()` without an id, does not count.
6116
6138
  - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6117
6139
  in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again; so does a
6118
6140
  block that removes an index of a table that held records and defines it again, where the index stands as before.
@@ -6186,7 +6208,7 @@ print(await NoteV2.objects().search(text="physics").count())
6186
6208
  indexes (section 37).
6187
6209
  - **`filter(x__match=...)` stays a regular expression**: this library's `match` lookup, not SurrealDB's `@@`;
6188
6210
  `search()` is the full-text path.
6189
- - **`hybrid_search()` comes in v0.37.0.**
6211
+ - **`hybrid_search()` fuses `search()`'s ranking with `similar_to()`'s** (section 38, v0.37.0).
6190
6212
 
6191
6213
  ### 37. Vector search (`similar_to()`, `VectorField`, `Index(hnsw=True)`)
6192
6214
 
@@ -6209,7 +6231,11 @@ the default —, `I64`, `I32` or `I16`). An `Index` with `hnsw=True` is a vector
6209
6231
  `SurrealConfigDict(indexes=[...])` next to the full-text indexes of
6210
6232
  [section 36](#36-full-text-search-search-searchscore-searchhighlight-analyzer-index). Its attributes hold what was
6211
6233
  declared (`None` for an option not given). When the class is defined, two vector indexes on one column are refused,
6212
- and so is a vector index whose dimension or storage type differs from its field's `VectorField`.
6234
+ and so is a vector index whose dimension or storage type differs from its field's `VectorField`. A field annotated
6235
+ with a name defined after the class (a forward reference) is checked once the name resolves, with the same error: at
6236
+ `model_rebuild()`, at the model's first instantiation, validation or JSON schema, and before `table_ddl()`,
6237
+ `define_table()`, `index_ddl()`, `define_indexes()`, `get_indexes()` or a queryset (`similar_to()` included) reads the
6238
+ model. Once refused, each of these raises it again.
6213
6239
 
6214
6240
  ```python
6215
6241
  from surreal_orm_lite import (
@@ -6321,10 +6347,11 @@ print(get_vector_info(Document.model_fields["embedding"]), is_vector_field(Passa
6321
6347
  `VectorField[d]` is already optional, so it needs no `| None`. Written `VectorField[d] | None` or
6322
6348
  `Optional[VectorField[d]]`, its `None` default sits inside a union member, where Pydantic ignores it with an
6323
6349
  `UnsupportedFieldAttributeWarning`: write `= None`, or the field is required. The ORM reads these spellings, and
6324
- `Annotated[list[float], Vector(d)] | None`, like the plain ones: the same column, the same checks of the vector index
6325
- when the class is defined, the same dimension for `similar_to()`, the same answer from `get_vector_info()`. A union
6326
- that holds a vector next to a type other than `None`, or two different `Vector` markers, has no single dimension: the
6327
- class statement refuses it, naming the field.
6350
+ `Annotated[list[float], Vector(d)] | None`, like the plain ones (a `Literal[None]` member counts as `None`): the same
6351
+ column, the same checks of the vector index when the class is defined, the same dimension for `similar_to()`, the same
6352
+ answer from `get_vector_info()`. A union that holds a vector next to a type other than `None`, or two different
6353
+ `Vector` markers, has no single dimension: the class statement refuses it, naming the field, and `get_vector_info()`
6354
+ and `is_vector_field()` raise `ValueError` for such a field or annotation.
6328
6355
 
6329
6356
  #### Find the nearest
6330
6357
 
@@ -6468,7 +6495,8 @@ except ValueError as error:
6468
6495
 
6469
6496
  - Search annotations with `similar_to()` on SurrealDB 2.x and the embedded engine, for the reads that return records
6470
6497
  (`exec()`, `first()`, `get()` without an id): `SurrealDbError` before the statement is sent. `search()` as a
6471
- condition stays available there, and `count()`, `exists()` and the aggregations answer.
6498
+ condition stays available there, and `count()`, `exists()` and the aggregations answer. `hybrid_search()` gives each
6499
+ record found by both searches its BM25 score and its distance, on every line.
6472
6500
  - `as_of()` ([section 27](#27-time-travel-as_of)): `similar_to()` with `as_of()` raises `SurrealDbError` before any
6473
6501
  request, in either order and in a subquery under it. The index holds the records' current vectors, so a time-travel
6474
6502
  read would pick its neighbours by their vectors now.
@@ -6505,12 +6533,172 @@ except ValueError as error:
6505
6533
  - **No `MTREE`, `MINKOWSKI`, `JACCARD` or `PEARSON`, and no `concurrently` yet**; the full ORM writes `MINKOWSKI`
6506
6534
  without its order, which SurrealDB refuses.
6507
6535
  - **Vector functions in `annotate()`** (`vector::similarity::cosine()`…) are not available yet; `hybrid_search()`
6508
- comes in v0.37.0.
6536
+ (section 38) fuses this ranking with `search()`'s.
6509
6537
  - **`get_vector_info()` and `is_vector_field()` are imported from `surreal_orm_lite.vector`**: the full ORM has them
6510
6538
  in `surreal_orm.fields`, a module this library does not have.
6511
6539
  - **`generate_models_from_db()` does not write `VectorField` yet**, while the full ORM's generator writes it for a
6512
6540
  field with an HNSW index.
6513
6541
 
6542
+ ### 38. Hybrid search (`hybrid_search()`, Reciprocal Rank Fusion)
6543
+
6544
+ Since v0.37.0 a queryset fuses two rankings of its records with the full SurrealDB-ORM's `hybrid_search()`: the
6545
+ records nearest to a query vector, as `similar_to()` finds them
6546
+ ([section 37](#37-vector-search-similar_to-vectorfield-indexhnswtrue)), and the best matches of a text, as `search()`
6547
+ ranks them by BM25 score ([section 36](#36-full-text-search-search-searchscore-searchhighlight-analyzer-index)), are
6548
+ fused into one ranking by Reciprocal Rank Fusion. SurrealDB 3.x fuses the two lists with its `search::rrf()`;
6549
+ SurrealDB 2.x and the embedded engine have no such function, so the ORM fuses them with the same formula: the same
6550
+ two lists give the same records, scores and order on every line. Each record comes back as a dict, as in the full
6551
+ ORM. The examples assume a configured connection: they run as written, in order, on the embedded engine (`mem://`).
6552
+
6553
+ #### Search
6554
+
6555
+ ```python
6556
+ from surreal_orm_lite import Analyzer, BaseSurrealModel, Index, SurrealConfigDict, SurrealDbError, VectorField
6557
+
6558
+ WORDS = Analyzer("words", ["blank"], ["lowercase"])
6559
+
6560
+
6561
+ class Passage(BaseSurrealModel):
6562
+ model_config = SurrealConfigDict(
6563
+ table_name="passage",
6564
+ indexes=[
6565
+ Index("passage_embedding", "embedding", hnsw=True, dimension=3, dist="cosine"),
6566
+ Index("passage_title", "title", search_analyzer=WORDS),
6567
+ ],
6568
+ )
6569
+
6570
+ id: str | None = None
6571
+ title: str
6572
+ topic: str = ""
6573
+ embedding: VectorField[3]
6574
+
6575
+
6576
+ await Passage.define_table()
6577
+ await Passage.define_indexes()
6578
+ for key, title, topic, embedding in [
6579
+ ("p1", "Cats and dogs", "pets", [1.0, 0.0, 0.0]),
6580
+ ("p2", "Cats at home", "pets", [0.9, 0.1, 0.0]),
6581
+ ("p3", "Rust programming", "tech", [0.0, 1.0, 0.0]),
6582
+ ("p4", "Python programming", "tech", [0.1, 0.9, 0.0]),
6583
+ ("p5", "Gardening", "home", [0.0, 0.0, 1.0]),
6584
+ ("p6", "Cats and code", "news", [0.5, 0.5, 0.0]),
6585
+ ("p7", "Rust and Python programming", "tech", [0.2, 0.8, 0.0]),
6586
+ ("p8", "Cooking", "home", [0.0, 0.2, 0.8]),
6587
+ ]:
6588
+ await Passage(id=key, title=title, topic=topic, embedding=embedding).save()
6589
+
6590
+ results = await Passage.objects().hybrid_search(
6591
+ vector_field="embedding", vector=[1.0, 0.0, 0.0], vector_limit=3,
6592
+ text_field="title", text_query="programming", text_limit=3,
6593
+ )
6594
+ for row in results:
6595
+ print(row["id"], f"{row['_rrf_score']:.4f}", row["_knn_distance"] is not None, row["_search_score"] is not None)
6596
+ # passage:p1 0.0164 True False
6597
+ # passage:p3 0.0164 False True
6598
+ # passage:p2 0.0161 True False
6599
+ # passage:p4 0.0161 False True
6600
+ # passage:p6 0.0159 True False
6601
+ # passage:p7 0.0159 False True
6602
+ ```
6603
+
6604
+ Each record gets 1 / (`rrf_k` + rank) from each list it is in, its rank counted from 1 (`rrf_k` is 60 by default):
6605
+ `p1`, nearest, and `p3`, the best match, both score 1/61. Records with equal scores keep the vector list's order
6606
+ first, then the full-text list's for the records it alone found, on every line — SurrealDB's `search::rrf()` alone
6607
+ returns them in no fixed order. `_knn_distance` is `None` for a record only the full-text search found,
6608
+ `_search_score` for one only the vector search found.
6609
+
6610
+ #### With the queryset
6611
+
6612
+ ```python
6613
+ tech = await Passage.objects().filter(topic="tech").limit(2).hybrid_search(
6614
+ vector_field="embedding", vector=[0.0, 1.0, 0.0], vector_limit=4,
6615
+ text_field="title", text_query="programming", text_limit=4,
6616
+ )
6617
+ for row in tech:
6618
+ print(row["id"], f"{row['_rrf_score']:.4f}")
6619
+ # passage:p3 0.0328
6620
+ # passage:p4 0.0323
6621
+ page = await Passage.objects().offset(1).limit(2).hybrid_search(
6622
+ vector_field="embedding", vector=[1.0, 0.0, 0.0], vector_limit=3,
6623
+ text_field="title", text_query="programming", text_limit=3,
6624
+ )
6625
+ print([str(row["id"]) for row in page])
6626
+ # ['passage:p3', 'passage:p2']
6627
+ ```
6628
+
6629
+ The queryset's conditions select the records of both lists. `select()` and `fetch()` apply to both, `id` always read;
6630
+ `limit()` and `offset()` page through the fused records, of which there are at most `vector_limit + text_limit`.
6631
+ `cache()`, `objects(tx=)` and named connections apply as for `exec()`, and `dist=` scans exactly, as in section 37.
6632
+
6633
+ #### What SurrealDB decides
6634
+
6635
+ ```python
6636
+ try:
6637
+ await Passage.objects().hybrid_search(
6638
+ vector_field="embedding", vector=[1.0, 0.0, 0.0], text_field="topic", text_query="tech",
6639
+ )
6640
+ except SurrealDbError as error:
6641
+ print(error)
6642
+ # hybrid_search(): no full-text index on field 'topic'. SurrealDB matches only a field with a FULLTEXT (3.x) or SEARCH (2.x) index: declare Index(..., search_analyzer=...) on the model and apply define_indexes().
6643
+ ```
6644
+
6645
+ - Each list is SurrealDB's own: the vector list as `similar_to()` finds it — HNSW is approximate (section 37) — and
6646
+ the full-text list as `search()` ranks it, with section 36's BM25 scores. Those depend on the line: a term found in
6647
+ more than half the documents scores `0.0` on SurrealDB 3.x and below zero on 2.x and the embedded engine
6648
+ ([2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x)), so the full-text list, and the fused ranking with it, can
6649
+ differ between lines.
6650
+ - **An exact scan (`dist=`) on SurrealDB 2.x and the embedded engine** picks among records at an equal distance at the
6651
+ `vector_limit`-th place in no fixed order, as `similar_to()`'s does: the vector list, and the fused records with it,
6652
+ can change between two identical calls, and a page read with `offset()` and `limit()` can then skip or repeat a
6653
+ record. The HNSW index (no `dist=`), and SurrealDB 3.x's exact scan, return the same list on every call.
6654
+ - Each search needs its index. Without a full-text index on `text_field`, SurrealDB 3.3, 2.x and the embedded engine
6655
+ refuse the search, and `hybrid_search()` raises `SurrealDbError` naming the field, as above; SurrealDB 3.1 and 3.2
6656
+ match nothing, so the vector list alone is fused.
6657
+ - Without a vector index on `vector_field`, the vector search finds nothing on SurrealDB 3.3, 2.x and the embedded
6658
+ engine, so the full-text ranking alone is fused, every `_knn_distance` `None`; SurrealDB 3.1 and 3.2 list the first
6659
+ `vector_limit` records by id, with no distance. Pass `dist=` for an exact scan that needs no index.
6660
+
6661
+ #### Not supported
6662
+
6663
+ ```python
6664
+ try:
6665
+ await Passage.objects().order_by("title").hybrid_search(
6666
+ vector_field="embedding", vector=[1.0, 0.0, 0.0], text_field="title", text_query="cats",
6667
+ )
6668
+ except ValueError as error:
6669
+ print(error)
6670
+ # hybrid_search() cannot be combined with order_by(): it runs its own vector and full-text searches and orders the records by their fused score. Remove them from the queryset.
6671
+ ```
6672
+
6673
+ - `order_by()`, `annotate()`, `values()`, `search()` and `similar_to()` raise `ValueError` before any request, as
6674
+ above; `as_of()` raises `SurrealDbError`: the indexes hold the records' current values.
6675
+ - Several full-text fields, weights and score normalisation (`search::linear()`), and the full-text side's highlights
6676
+ are not available yet.
6677
+ - **A field stored under a name `hybrid_search()` uses for its own values** — `rrf_score`, `_rrf_score`,
6678
+ `_knn_distance`, `_search_score`, `_hybrid_pos`, `_hybrid_vec_pos` or `_hybrid_text_pos` — raises `ValueError`
6679
+ before any request: store it under another name (`Field(alias=...)`). On a SCHEMALESS table, a column with one of
6680
+ these names that the model does not declare is not returned, on every line, even when `select()` names it.
6681
+
6682
+ #### Coming from the full SurrealDB-ORM
6683
+
6684
+ - **`hybrid_search()` keeps the full ORM's signature**: keyword-only `vector_field`, `vector`, `vector_limit=20`,
6685
+ `text_field`, `text_query`, `text_limit=20`, `rrf_k=60`; `ef` is `None` for 100, so that `dist=` (an exact scan,
6686
+ section 37) can be given instead.
6687
+ - **It returns dicts, as the full ORM does**: each holds the record's fields, keyed by their Python names as
6688
+ `exec()`'s dict rows are, and `_rrf_score`, plus `_knn_distance` and `_search_score`, which the full ORM does not
6689
+ return.
6690
+ - **It applies the queryset**: its conditions, `select()`, `fetch()`, `limit()`/`offset()`, `cache()`, transactions
6691
+ and named connections; the full ORM ignores them.
6692
+ - **SurrealDB's `search::rrf()` fuses the lists on 3.x**, given both lists in one statement, and the ORM fuses them on
6693
+ 2.x and the embedded engine; the full ORM calls `search::rrf()` with arguments SurrealDB 3.3 refuses, and runs on
6694
+ 3.x only.
6695
+ - **Equal fused scores have a fixed order** (the vector list's first), so the same two lists always give the same
6696
+ page; on SurrealDB 2.x and the embedded engine, an exact scan (`dist=`) can change the vector list itself between
6697
+ two identical calls, as above.
6698
+ - **Checked before any request**: both fields, the vector, `vector_limit` and `text_limit` (1 to 10 000), `rrf_k`
6699
+ (0 to 10 000), `ef` and `dist`; the full ORM checks the field names only.
6700
+ - **Reciprocal Rank Fusion only**: `search::linear()` (weights and score normalisation) is not offered yet.
6701
+
6514
6702
  ---
6515
6703
 
6516
6704
  ## Configuration Options
@@ -6633,7 +6821,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6633
6821
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6634
6822
  on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
6635
6823
  otherwise. The full suite and every divergence below were re-verified on both new versions.
6636
- Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.36.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.36.2 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
6824
+ Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.36.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.36.2 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.37.0 were measured on 2.7.0, 3.3.4, 3.2.6 and the embedded engine, with 3.1.5 and 3.2.6 where they differ from 3.3.4.
6637
6825
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6638
6826
 
6639
6827
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6794,6 +6982,10 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6794
6982
  | `similar_to(dist=…)` with a condition on a linked record's field | the ORM selects the matching records first (a `LET`): 2.x's exact scan would return every matching record, ignoring `limit` | the condition stays next to the KNN operator | v0.36.0 |
6795
6983
  | `similar_to()` on a field without a vector index | no record | no record; 3.1 answers every record, with no distance | v0.36.0 |
6796
6984
  | `remove_index(tx=)` then `define_indexes(tx=)` in one block, the index stored before the block | on a table holding records, the commit fails with a retryable `SurrealDbConflictError`, again on retry: nothing committed, the index kept; on an empty table, defined again | the index is defined again after its removal and committed, serving the records committed before the block | v0.36.2 |
6985
+ | `hybrid_search()`: the fusion | the ORM fuses the two lists with `search::rrf()`'s formula, which SurrealDB 2.x does not have: the same records, scores and order for the same two lists | SurrealDB's `search::rrf()` fuses them; the ORM orders equal scores, which SurrealDB returns in no fixed order | v0.37.0 |
6986
+ | `hybrid_search()` with other conditions | applied to both lists; the vector list selects the records first (a `LET`), as `similar_to()` does | applied to both lists, during each search | v0.37.0 |
6987
+ | `hybrid_search()` on a field without a vector or full-text index | no vector index: the vector list is empty, so the full-text ranking alone is fused; no full-text index: `SurrealDbError` naming the field | the same; 3.1 and 3.2 put the first `vector_limit` records by id in the vector list, with no distance, and match no record for the text | v0.37.0 |
6988
+ | An exact scan (`similar_to(dist=…)`, `hybrid_search(dist=…)`) with records at an equal distance at the last place | the scan picks among them in no fixed order: the records, and a page of them, can change between two identical calls; the HNSW index (no `dist=`) returns the same ones | the same records on every call, as with the HNSW index | pre-existing (documented in v0.37.0) |
6797
6989
  | Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0 | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips) | 3.3.0 identical to 3.2.4, except the system-user signin row | v0.19.1 |
6798
6990
 
6799
6991
  > **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
@@ -6834,6 +7026,7 @@ Capabilities not listed behave as on a 2.x server.
6834
7026
  | `define_indexes(tx=)` in a block that writes to the model's table | an ORM write before it: refused all the same, although this engine indexes its records; a write after it is committed and indexed | refused (left out of the index); on 2.x a write after it, to a table holding records, fails the commit | v0.35.3 |
6835
7027
  | Vector search (v0.36.0) | as on a 2.x server: `MTREE` accepted, at most `ef` records returned (the ORM raises `ef` to `limit`), other conditions selected first in a `LET` (search annotations refused), writes made by the ids of the nearest, fewer records with a selective condition; an index without `TYPE` is `F64` (servers: `F32`), so the ORM always writes `TYPE` | 3.x refuses `MTREE`, applies the conditions during the index search and keeps search annotations | v0.36.0 |
6836
7028
  | `remove_index(tx=)` then `define_indexes(tx=)` in one block | the index is defined again after its removal and committed, on a table holding records too | the same on 3.x; on 2.x, on a table holding records, the commit fails with a retryable conflict | v0.36.2 |
7029
+ | Hybrid search (v0.37.0) | as on a 2.x server: the ORM fuses the two lists with `search::rrf()`'s formula, which the engine does not have, and the vector list selects the other conditions first (a `LET`); an exact scan (`dist=`) picks among records at an equal distance at the `vector_limit`-th place in no fixed order, as `similar_to(dist=…)` does | 3.x fuses with `search::rrf()`, each list applying the conditions; its exact scan returns the same list | v0.37.0 |
6837
7030
  | Everything else | CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields, upsert/patch, server values, computed fields, stored functions, signals: the same as on a 2.x server | unchanged | v0.25.0 |
6838
7031
 
6839
7032
  ---
@@ -6885,7 +7078,8 @@ Contributions are welcome! Please:
6885
7078
  | v0.34.0 | Tier 3 — Model table DDL | ✅ Released |
6886
7079
  | v0.35.0 | Tier 3 — Full-text search | ✅ Released |
6887
7080
  | v0.36.0 | Tier 3 — Vector search | ✅ Released |
6888
- | v0.37.0 – v0.40.0 | Tier 3 — Advanced (hybrid search, migrations, CLI) | 📋 Planned |
7081
+ | v0.37.0 | Tier 3 — Hybrid search | ✅ Released |
7082
+ | v0.38.0 – v0.40.0 | Tier 3 — Advanced (migrations, CLI) | 📋 Planned |
6889
7083
  | v0.41.0 | Beta Phase (API freeze, hardening) | 📋 Planned |
6890
7084
  | v2.0.0 | Production / GA (aligned with SDK 2.0) | 📋 Planned |
6891
7085
 
@@ -6946,7 +7140,7 @@ SDK) and **server support**. Everything below is on the lite roadmap via the off
6946
7140
  | Model table DDL | ✅ v0.34.0 (`define_table()`) | ✅ |
6947
7141
  | Full-Text Search | ✅ v0.35.0 (`search()`) | ✅ |
6948
7142
  | Vector Search (KNN/HNSW) | ✅ v0.36.0 (`similar_to()`) | ✅ |
6949
- | Hybrid Search (RRF) | v0.37.0 | ✅ |
7143
+ | Hybrid Search (RRF) | ✅ v0.37.0 (`hybrid_search()`) | ✅ |
6950
7144
  | Migrations & CLI | v0.38 – v0.39 | ✅ |
6951
7145
  | Test Fixtures & Factories | ✅ v0.25.0 SurrealFixture; factories v0.40.0 | ✅ |
6952
7146
  | Retry, Logging, Metrics | v0.41.0 | ✅ |