surreal-orm-lite 0.37.2__tar.gz → 0.37.4__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.37.2 → surreal_orm_lite-0.37.4}/CHANGELOG.md +32 -0
  2. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/PKG-INFO +14 -10
  3. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/README.md +13 -9
  4. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/query_set.py +49 -21
  7. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/subquery.py +4 -3
  8. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/vector.py +76 -0
  9. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/.gitignore +0 -0
  10. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/LICENSE +0 -0
  11. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/Makefile +0 -0
  12. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/_sdk.py +0 -0
  13. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/aggregations.py +0 -0
  14. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/auth.py +0 -0
  15. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/cache.py +0 -0
  16. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/changefeed.py +0 -0
  17. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/concurrency.py +0 -0
  18. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/connection_config.py +0 -0
  19. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/connection_manager.py +0 -0
  20. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/constants.py +0 -0
  21. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/decoding.py +0 -0
  22. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/define_parser.py +0 -0
  23. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/edge.py +0 -0
  24. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/embedded.py +0 -0
  25. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/encoding.py +0 -0
  26. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/enum.py +0 -0
  27. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/exceptions.py +0 -0
  28. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/functions.py +0 -0
  29. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/geo.py +0 -0
  30. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/hybrid.py +0 -0
  31. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/introspection.py +0 -0
  32. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/live.py +0 -0
  33. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/model_auth.py +0 -0
  34. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/model_base.py +0 -0
  35. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/model_ddl.py +0 -0
  36. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/model_generator.py +0 -0
  37. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/py.typed +0 -0
  38. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/q.py +0 -0
  39. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/routing.py +0 -0
  40. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/schema.py +0 -0
  41. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/schema_state.py +0 -0
  42. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/search.py +0 -0
  43. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/signals.py +0 -0
  44. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/surql_literal.py +0 -0
  45. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/testing/__init__.py +0 -0
  46. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/testing/database.py +0 -0
  47. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  48. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/time_travel.py +0 -0
  49. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/transaction.py +0 -0
  50. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/types.py +0 -0
  51. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,38 @@ 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.4] - 2026-10-27
9
+
10
+ Follow-up to the review of v0.37.0 (#340): the exact scan (`dist=`) of `similar_to()` and
11
+ `hybrid_search()` now keeps the same records on every identical call on SurrealDB 2.x and the
12
+ embedded engine. No new public API.
13
+
14
+ ### Fixed
15
+
16
+ - **The exact scan keeps records at an equal distance by id below SurrealDB 3** (#341). On
17
+ SurrealDB 2.x and the embedded engine, the engine's own exact scan picks among the records at an
18
+ equal distance at the `limit`-th place in no fixed order, so identical calls of
19
+ `similar_to(dist=...)` and `hybrid_search(dist=...)` could return other records, and a page
20
+ (`offset()`/`limit()`) or a bulk write (`bulk_update()`, `bulk_delete()`, `patch()`) could take
21
+ others than the read. Below 3 the ORM now selects the nearest records first, ranked by distance
22
+ then id, and the KNN operator searches exactly those ids: each `_knn_distance` is still
23
+ `vector::distance::knn()`'s, and without a tie at the last place the records and distances are
24
+ those the scan alone returned. The read ends `ORDER BY _knn_distance, id` when its projection
25
+ reads `id`. The statement sent to SurrealDB 3.x, whose exact scan gives one answer, is unchanged.
26
+ An exact scan now reads the server line (once per client) even without another condition.
27
+
28
+ ### Changed
29
+
30
+ - The README documents the exact scan's ties in section 37 (*What SurrealDB decides*) and section 38,
31
+ and in the "ORM behaviour: SurrealDB 2.x vs 3.x" table; the embedded engine's hybrid row says the
32
+ tied records are kept by id. The `v0.37.0` hybrid notebook no longer describes an exact scan that
33
+ changes between two identical calls.
34
+
35
+ ### Notes
36
+
37
+ - `TestExactScanTiesE2E` now expects one answer on every engine. Measured on SurrealDB 2.7.0 and
38
+ 3.3.4 over WebSocket and HTTP, and on the embedded engine; 3.1.5 behaves as 3.3.4.
39
+
8
40
  ## [0.37.2] - 2026-10-27
9
41
 
10
42
  A model with a `primary_key` can have its access defined on SurrealDB 3.x. No new public API.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.37.2
3
+ Version: 0.37.4
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
@@ -6478,6 +6478,10 @@ print(await annotated.count(), await annotated.exists())
6478
6478
  that keeps a tenth of the table. Pass `dist=` for an exact scan.
6479
6479
  - Distances are computed in the index's `vector_type` (`F32` by default: single precision), so they can differ from
6480
6480
  Python's in the last digits; `dist=` computes in double precision.
6481
+ - SurrealDB 2.x's and the embedded engine's exact scan (`dist=`) picks among records at an equal distance at the
6482
+ `limit`-th place in no fixed order, so there the ORM ranks it by distance, then id: identical calls return the same
6483
+ records in the same order, the tied ones by id, and a page, a `Subquery` and the bulk writes take the same records.
6484
+ SurrealDB 3.x's own scan gives one answer.
6481
6485
  - `COSINE` has no distance for a zero vector: `similar_to()` refuses a zero query vector when the distance is
6482
6486
  `COSINE` — `dist="cosine"`, or the model's `COSINE` index on the field —, and a record holding a zero vector gets a
6483
6487
  `nan` distance.
@@ -6650,10 +6654,11 @@ except SurrealDbError as error:
6650
6654
  more than half the documents scores `0.0` on SurrealDB 3.x and below zero on 2.x and the embedded engine
6651
6655
  ([2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x)), so the full-text list, and the fused ranking with it, can
6652
6656
  differ between lines.
6653
- - **An exact scan (`dist=`) on SurrealDB 2.x and the embedded engine** picks among records at an equal distance at the
6654
- `vector_limit`-th place in no fixed order, as `similar_to()`'s does: the vector list, and the fused records with it,
6655
- can change between two identical calls, and a page read with `offset()` and `limit()` can then skip or repeat a
6656
- record. The HNSW index (no `dist=`), and SurrealDB 3.x's exact scan, return the same list on every call.
6657
+ - **An exact scan (`dist=`) returns the same vector list on every call**, on every line. SurrealDB 2.x's and the
6658
+ embedded engine's own scan picks among records at an equal distance at the `vector_limit`-th place in no fixed order,
6659
+ so there the ORM ranks it by distance, then id, as for `similar_to()` (section 37): the tied records are kept by id,
6660
+ and a page read with `offset()` and `limit()` never skips nor repeats one. The HNSW index (no `dist=`) returns the
6661
+ same list on every call too.
6657
6662
  - Each search needs its index. Without a full-text index on `text_field`, SurrealDB 3.3, 2.x and the embedded engine
6658
6663
  refuse the search, and `hybrid_search()` raises `SurrealDbError` naming the field, as above; SurrealDB 3.1 and 3.2
6659
6664
  match nothing, so the vector list alone is fused.
@@ -6696,8 +6701,7 @@ except ValueError as error:
6696
6701
  2.x and the embedded engine; the full ORM calls `search::rrf()` with arguments SurrealDB 3.3 refuses, and runs on
6697
6702
  3.x only.
6698
6703
  - **Equal fused scores have a fixed order** (the vector list's first), so the same two lists always give the same
6699
- page; on SurrealDB 2.x and the embedded engine, an exact scan (`dist=`) can change the vector list itself between
6700
- two identical calls, as above.
6704
+ page, and an exact scan (`dist=`) gives the same vector list on every line, as above.
6701
6705
  - **Checked before any request**: both fields, the vector, `vector_limit` and `text_limit` (1 to 10 000), `rrf_k`
6702
6706
  (0 to 10 000), `ef` and `dist`; the full ORM checks the field names only.
6703
6707
  - **Reciprocal Rank Fusion only**: `search::linear()` (weights and score normalisation) is not offered yet.
@@ -6824,7 +6828,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6824
6828
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6825
6829
  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
6826
6830
  otherwise. The full suite and every divergence below were re-verified on both new versions.
6827
- 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. The row added in v0.37.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5.
6831
+ 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. The row added in v0.37.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.37.4 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
6828
6832
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6829
6833
 
6830
6834
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6989,7 +6993,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6989
6993
  | `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 |
6990
6994
  | `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 |
6991
6995
  | `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 |
6992
- | 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) |
6996
+ | An exact scan (`similar_to(dist=…)`, `hybrid_search(dist=…)`) with records at an equal distance at the last place | the ORM ranks the scan by distance, then id: the same records on every call, the tied ones by id (2.x's own scan picks among them in no fixed order) | the same records on every call, as with the HNSW index | v0.37.4 |
6993
6997
  | 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 |
6994
6998
 
6995
6999
  > **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.
@@ -7030,7 +7034,7 @@ Capabilities not listed behave as on a 2.x server.
7030
7034
  | `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 |
7031
7035
  | 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 |
7032
7036
  | `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 |
7033
- | 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 |
7037
+ | 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=`) keeps the records at an equal distance at the `vector_limit`-th place by id (since v0.37.4), 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 |
7034
7038
  | 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 |
7035
7039
 
7036
7040
  ---
@@ -6427,6 +6427,10 @@ print(await annotated.count(), await annotated.exists())
6427
6427
  that keeps a tenth of the table. Pass `dist=` for an exact scan.
6428
6428
  - Distances are computed in the index's `vector_type` (`F32` by default: single precision), so they can differ from
6429
6429
  Python's in the last digits; `dist=` computes in double precision.
6430
+ - SurrealDB 2.x's and the embedded engine's exact scan (`dist=`) picks among records at an equal distance at the
6431
+ `limit`-th place in no fixed order, so there the ORM ranks it by distance, then id: identical calls return the same
6432
+ records in the same order, the tied ones by id, and a page, a `Subquery` and the bulk writes take the same records.
6433
+ SurrealDB 3.x's own scan gives one answer.
6430
6434
  - `COSINE` has no distance for a zero vector: `similar_to()` refuses a zero query vector when the distance is
6431
6435
  `COSINE` — `dist="cosine"`, or the model's `COSINE` index on the field —, and a record holding a zero vector gets a
6432
6436
  `nan` distance.
@@ -6599,10 +6603,11 @@ except SurrealDbError as error:
6599
6603
  more than half the documents scores `0.0` on SurrealDB 3.x and below zero on 2.x and the embedded engine
6600
6604
  ([2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x)), so the full-text list, and the fused ranking with it, can
6601
6605
  differ between lines.
6602
- - **An exact scan (`dist=`) on SurrealDB 2.x and the embedded engine** picks among records at an equal distance at the
6603
- `vector_limit`-th place in no fixed order, as `similar_to()`'s does: the vector list, and the fused records with it,
6604
- can change between two identical calls, and a page read with `offset()` and `limit()` can then skip or repeat a
6605
- record. The HNSW index (no `dist=`), and SurrealDB 3.x's exact scan, return the same list on every call.
6606
+ - **An exact scan (`dist=`) returns the same vector list on every call**, on every line. SurrealDB 2.x's and the
6607
+ embedded engine's own scan picks among records at an equal distance at the `vector_limit`-th place in no fixed order,
6608
+ so there the ORM ranks it by distance, then id, as for `similar_to()` (section 37): the tied records are kept by id,
6609
+ and a page read with `offset()` and `limit()` never skips nor repeats one. The HNSW index (no `dist=`) returns the
6610
+ same list on every call too.
6606
6611
  - Each search needs its index. Without a full-text index on `text_field`, SurrealDB 3.3, 2.x and the embedded engine
6607
6612
  refuse the search, and `hybrid_search()` raises `SurrealDbError` naming the field, as above; SurrealDB 3.1 and 3.2
6608
6613
  match nothing, so the vector list alone is fused.
@@ -6645,8 +6650,7 @@ except ValueError as error:
6645
6650
  2.x and the embedded engine; the full ORM calls `search::rrf()` with arguments SurrealDB 3.3 refuses, and runs on
6646
6651
  3.x only.
6647
6652
  - **Equal fused scores have a fixed order** (the vector list's first), so the same two lists always give the same
6648
- page; on SurrealDB 2.x and the embedded engine, an exact scan (`dist=`) can change the vector list itself between
6649
- two identical calls, as above.
6653
+ page, and an exact scan (`dist=`) gives the same vector list on every line, as above.
6650
6654
  - **Checked before any request**: both fields, the vector, `vector_limit` and `text_limit` (1 to 10 000), `rrf_k`
6651
6655
  (0 to 10 000), `ef` and `dist`; the full ORM checks the field names only.
6652
6656
  - **Reciprocal Rank Fusion only**: `search::linear()` (weights and score normalisation) is not offered yet.
@@ -6773,7 +6777,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6773
6777
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6774
6778
  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
6775
6779
  otherwise. The full suite and every divergence below were re-verified on both new versions.
6776
- 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. The row added in v0.37.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5.
6780
+ 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. The row added in v0.37.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.37.4 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
6777
6781
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6778
6782
 
6779
6783
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6938,7 +6942,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6938
6942
  | `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 |
6939
6943
  | `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 |
6940
6944
  | `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 |
6941
- | 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) |
6945
+ | An exact scan (`similar_to(dist=…)`, `hybrid_search(dist=…)`) with records at an equal distance at the last place | the ORM ranks the scan by distance, then id: the same records on every call, the tied ones by id (2.x's own scan picks among them in no fixed order) | the same records on every call, as with the HNSW index | v0.37.4 |
6942
6946
  | 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 |
6943
6947
 
6944
6948
  > **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.
@@ -6979,7 +6983,7 @@ Capabilities not listed behave as on a 2.x server.
6979
6983
  | `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 |
6980
6984
  | 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 |
6981
6985
  | `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 |
6982
- | 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 |
6986
+ | 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=`) keeps the records at an equal distance at the `vector_limit`-th place by id (since v0.37.4), 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 |
6983
6987
  | 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 |
6984
6988
 
6985
6989
  ---
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.37.2"
3
+ version = "0.37.4"
4
4
  description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,4 +1,4 @@
1
- __version__ = "0.37.2"
1
+ __version__ = "0.37.4"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -690,7 +690,10 @@ class QuerySet:
690
690
  ``limit``, so without other conditions every line returns ``limit`` records when the table holds them. With a
691
691
  condition that keeps few records the search can return fewer than ``limit``, more often on SurrealDB 2.x and the
692
692
  embedded engine; ``dist=`` is exact. Distances are computed in the index's storage type (``F32`` by default),
693
- ``dist=`` in double precision.
693
+ ``dist=`` in double precision. Records at an equal distance at the ``limit``-th place are kept, and returned, by
694
+ id on SurrealDB 2.x and the embedded engine, whose own exact scan picks among them in no fixed order: the ORM
695
+ ranks the scan by distance then id there (SurrealDB 3.x's scan gives one answer), so identical calls, a page of
696
+ them and the bulk writes take the same records.
694
697
 
695
698
  The other conditions — ``filter()``, ``Q``, ``nearby()``, ``search()`` and a ``Subquery`` filter — select the
696
699
  records first, then the ``limit`` nearest among them are kept: SurrealDB 3.x applies them during the index
@@ -1098,7 +1101,11 @@ class QuerySet:
1098
1101
  indexed column, a function call, a negation, a group, a dotted path or a full-text match, while it answers
1099
1102
  right through ids selected first — and the ORM cannot know a column's indexes. The ``LET`` reads the
1100
1103
  statement's own table and follows the ``LET`` s of the parts' own subqueries; inside a ``Subquery``, it
1101
- precedes the subquery's own. Without a compiler the KNN is written inline. With
1104
+ precedes the subquery's own. An exact scan (``dist=``) sets ``subqueries.knn_conditions`` too, with or without
1105
+ other parts: below 3 its ``LET`` holds the ids of the ``K`` nearest records matching every part, the id
1106
+ subqueries included, ranked by distance then id (``vector.exact_scan_select()``), and the ``WHERE`` keeps
1107
+ ``id IN $_sq<N>`` and the KNN — SurrealDB 2.x's and the embedded engine's own exact scan picks among records at
1108
+ an equal distance at the ``K``-th place in no fixed order. Without a compiler the KNN is written inline. With
1102
1109
  ``as_of=True`` (a time-travel table read, v0.26.0) the per-record check ``time_travel.GUARD`` is the last
1103
1110
  condition, after the ``nearby()`` ones (``search()`` never reads at a moment): every other part is a single
1104
1111
  comparison or a parenthesised group, so the check applies to every row they keep.
@@ -1162,20 +1169,26 @@ class QuerySet:
1162
1169
  variables[variable] = list(self._similar.vector)
1163
1170
  counter += 1
1164
1171
  others = [part for part in parts if not _vector.id_subquery_part(part)]
1165
- if subqueries is None or not others:
1172
+ exact = self._similar.dist is not None
1173
+ if subqueries is None or not (others or exact):
1166
1174
  parts.append(knn)
1167
1175
  elif not subqueries.knn_prefilter:
1168
- # The form for SurrealDB 3.x, which applies every condition during the index search.
1176
+ # The form for SurrealDB 3.x, which applies every condition during the index search and gives its exact
1177
+ # scan one answer.
1169
1178
  subqueries.knn_conditions = True
1170
1179
  parts.append(knn)
1171
1180
  else:
1172
- # Below SurrealDB 3: the records matching the other conditions selected first, by their ids.
1173
1181
  subqueries.knn_conditions = True
1174
1182
  name = f"{_subquery.LET_PREFIX}{len(subqueries.lets)}"
1175
- subqueries.lets.append(
1176
- f"LET ${name} = (SELECT VALUE id FROM {self._model_table} WHERE {' AND '.join(others)});"
1177
- )
1178
- kept = [part for part in parts if _vector.id_subquery_part(part)]
1183
+ if exact:
1184
+ # Below SurrealDB 3, an exact scan: its K nearest ranked by distance then id, every condition first.
1185
+ select = _vector.exact_scan_select(self._model_table, self._similar, variable, parts)
1186
+ kept = []
1187
+ else:
1188
+ # Below SurrealDB 3: the records matching the other conditions selected first, by their ids.
1189
+ select = f"(SELECT VALUE id FROM {self._model_table} WHERE {' AND '.join(others)})"
1190
+ kept = [part for part in parts if _vector.id_subquery_part(part)]
1191
+ subqueries.lets.append(f"LET ${name} = {select};")
1179
1192
  parts = [*kept, f"${name} CONTAINS id" if view else f"id IN ${name}", knn]
1180
1193
 
1181
1194
  if as_of:
@@ -1363,7 +1376,9 @@ class QuerySet:
1363
1376
 
1364
1377
  With ``similar_to()`` (v0.36.0) the distance is projected as ``vector::distance::knn() AS _knn_distance``,
1365
1378
  after the ``GeoDistance`` and search annotations, and without ``order_by()`` the statement ends
1366
- ``ORDER BY _knn_distance`` (nearest first). Its search annotations are projected in the form for SurrealDB
1379
+ ``ORDER BY _knn_distance`` (nearest first) — ``ORDER BY _knn_distance, id`` for an exact scan (``dist=``) in the
1380
+ form below SurrealDB 3 when the projection reads ``id`` (``*``, or ``select()`` naming it), so its records at
1381
+ one distance come in one order on every call. Its search annotations are projected in the form for SurrealDB
1367
1382
  3.x only: the form below 3 (``subqueries.knn_prefilter``) selects the full-text matches in a ``LET``, so its
1368
1383
  outer statement holds no match to score, highlight or locate, and SurrealDB 2.x would answer ``NONE`` for each.
1369
1384
 
@@ -1411,6 +1426,10 @@ class QuerySet:
1411
1426
  query += f" ORDER BY {self._order_by}"
1412
1427
  elif self._similar is not None:
1413
1428
  query += f" ORDER BY {_vector.DISTANCE_ALIAS}"
1429
+ # Below SurrealDB 3 the exact scan's records at one distance come by id; SurrealDB 2.x refuses to order by a
1430
+ # column the projection does not read.
1431
+ if compiler.knn_prefilter and self._similar.dist is not None and self._reads_id():
1432
+ query += ", id"
1414
1433
 
1415
1434
  if self._limit is not None:
1416
1435
  query += f" LIMIT {self._limit}"
@@ -1424,6 +1443,11 @@ class QuerySet:
1424
1443
  query, variables = self._terminate(query, {**compiler.variables, **where_vars, **distance_vars, **search_vars}, moment)
1425
1444
  return compiler.wrap(query), variables
1426
1445
 
1446
+ def _reads_id(self) -> bool:
1447
+ """Whether the projection of :meth:`_compile_query` reads ``id``: ``*`` (no ``select()``, or ``select("*")``) or a
1448
+ ``select()`` naming it."""
1449
+ return not self.select_item or "*" in self.select_item or RECORD_ID_COLUMN in self.select_item
1450
+
1427
1451
  def _search_projection(self) -> tuple[list[str], dict[str, Any]]:
1428
1452
  """The projections of the search annotations, in ``annotate()`` order, and the highlight tags they bind
1429
1453
  (v0.35.0).
@@ -1512,7 +1536,8 @@ class QuerySet:
1512
1536
  is a ``LET``: inline, every 3.x line reports a vector of the wrong length and a missing table as errors the ORM
1513
1537
  reads. Below 3 (SurrealDB 2.x, the embedded engine: no ``search::rrf()``) each list is a ``LET`` of the block,
1514
1538
  named once its own conditions are compiled — the vector list's conditions selected first under
1515
- ``compiler.knn_prefilter``, as for ``similar_to()`` —, without ``OMIT``, and the block's value is both lists:
1539
+ ``compiler.knn_prefilter``, and an exact scan's nearest ranked by distance then id, as for ``similar_to()`` —,
1540
+ without ``OMIT``, and the block's value is both lists:
1516
1541
  ``hybrid.fuse()`` fuses them, which drops the same keys, and the ORM pages.
1517
1542
 
1518
1543
  The filter values' warnings are given once for the statement, as :meth:`_build_where` gives them. Every number
@@ -1892,9 +1917,9 @@ class QuerySet:
1892
1917
  subqueries search are passed on (v0.35.0, ``searched=``), so a missing-index error names them, and so are the
1893
1918
  fields their ``similar_to()`` searches (v0.36.0, ``knn_fields=``), so a dimension error names them.
1894
1919
 
1895
- A KNN next to other conditions (v0.36.0, ``compiler.knn_conditions``) is compiled for the line: *knn_prefilter*
1896
- ``None`` decides it once, right after the first compilation — the line read once per client
1897
- (``time_travel.cached_major()``), the form below SurrealDB 3 compiled again before anything is checked,
1920
+ A KNN next to other conditions (v0.36.0), or an exact scan (``compiler.knn_conditions``), is compiled for the
1921
+ line: *knn_prefilter* ``None`` decides it once, right after the first compilation — the line read once per
1922
+ client (``time_travel.cached_major()``), the form below SurrealDB 3 compiled again before anything is checked,
1898
1923
  queued or sent — and every later compilation of this read or write (a re-send for a missing subquery table
1899
1924
  included) uses that decision; :meth:`_run_cached` passes the one it took."""
1900
1925
  empty: frozenset[str] = frozenset()
@@ -1935,9 +1960,9 @@ class QuerySet:
1935
1960
  (compilation is pure), so the missing-subquery-table re-send happens inside the read; only the first
1936
1961
  compilation gives the filter values' warnings, once per read.
1937
1962
 
1938
- A KNN next to other conditions (v0.36.0) is keyed in its line's form: the line is read after the first
1939
- compilation and, below SurrealDB 3, the statement compiled again for the key; the decision is passed on to
1940
- :meth:`_run_uncached`, so a read the compilation refuses stores nothing.
1963
+ A KNN next to other conditions (v0.36.0), or an exact scan, is keyed in its line's form: the line is read after
1964
+ the first compilation and, below SurrealDB 3, the statement compiled again for the key; the decision is passed
1965
+ on to :meth:`_run_uncached`, so a read the compilation refuses stores nothing.
1941
1966
  """
1942
1967
  compiler = self._subquery_compiler()
1943
1968
  query, variables = compile_statement(compiler)
@@ -1967,9 +1992,10 @@ class QuerySet:
1967
1992
 
1968
1993
  async def _below_3(self, compiler: SubqueryCompiler) -> bool:
1969
1994
  """Whether the statement *compiler* compiled is for a line below SurrealDB 3 and needs the form with the
1970
- conditions next to its KNN selected first (v0.36.0): only when it has such conditions
1971
- (``compiler.knn_conditions``) is the line read, once per client (``time_travel.cached_major()``) — on the
1972
- connection's client, an interactive transaction's included. A version that cannot be read counts as 3."""
1995
+ conditions next to its KNN selected first (v0.36.0), or an exact scan's nearest ranked by distance then id: only
1996
+ when it has such conditions or such a scan (``compiler.knn_conditions``) is the line read, once per client
1997
+ (``time_travel.cached_major()``) — on the connection's client, an interactive transaction's included. A version
1998
+ that cannot be read counts as 3."""
1973
1999
  if not compiler.knn_conditions:
1974
2000
  return False
1975
2001
  return await _time_travel.cached_major(await self._manager().get_client()) < 3
@@ -2138,7 +2164,9 @@ class QuerySet:
2138
2164
 
2139
2165
  Each record is a dict — the full SurrealDB-ORM's result: its fields keyed by their Python names and
2140
2166
  ``_rrf_score``, plus ``_knn_distance`` (its distance, ``None`` when only the full-text search found it) and
2141
- ``_search_score`` (its BM25 score, ``None`` when only the vector search found it).
2167
+ ``_search_score`` (its BM25 score, ``None`` when only the vector search found it). An exact scan (``dist=``)
2168
+ gives identical calls one vector list on every line: records at an equal distance at the ``vector_limit``-th
2169
+ place are kept by id on SurrealDB 2.x and the embedded engine, as ``similar_to(dist=...)`` keeps them.
2142
2170
 
2143
2171
  Each search needs its index. Without a full-text index on ``text_field``, SurrealDB 3.3, 2.x and the embedded
2144
2172
  engine refuse the search (``SurrealDbError`` naming the field), while SurrealDB 3.1 and 3.2 match nothing.
@@ -227,9 +227,10 @@ class SubqueryCompiler:
227
227
  knn_fields: (table, column) → the field as given, for each ``similar_to()`` of the statement's subqueries:
228
228
  the dimension error names the field (v0.36.0).
229
229
  knn_prefilter: the statement is for a line below SurrealDB 3 (2.x, the embedded engine): every condition of a
230
- KNN's ``WHERE`` but an id subquery goes into a ``LET`` id subquery (v0.36.0).
231
- knn_conditions: a KNN of the statement shares its ``WHERE`` with a condition that is not an id subquery: the
232
- caller reads the line (v0.36.0).
230
+ KNN's ``WHERE`` but an id subquery goes into a ``LET`` id subquery (v0.36.0), and an exact scan's ``LET``
231
+ holds its nearest ranked by distance then id, every condition applied first.
232
+ knn_conditions: a KNN of the statement shares its ``WHERE`` with a condition that is not an id subquery
233
+ (v0.36.0), or is an exact scan (``dist=``): the caller reads the line.
233
234
  warn: emit the warnings of the statement's filter values (the ``"$$"`` escape, a string naming a variable):
234
235
  ``False`` when the statement is compiled again for a read that compiled it once (a ``cache()`` miss, a
235
236
  re-send for a missing subquery table), so each read warns once (v0.28.1).
@@ -42,6 +42,13 @@ column, a function call, a negation, a group, a dotted path, a full-text match
42
42
  records matching them first, in a ``LET`` of the statement, and the KNN searches those ids. ``id_subquery_part()``
43
43
  tells the only parts that stay next to the KNN on every line: the ORM's own id subqueries.
44
44
 
45
+ **The exact scan below SurrealDB 3.** SurrealDB 2.x's and the embedded engine's exact scan (``<|K,DIST|>``) picks among
46
+ records at an equal distance at the ``K``-th place in no fixed order, so the same read can return other records, and a
47
+ page skip or repeat one. Below 3 the queryset selects the ``K`` nearest first, in a ``LET`` ranked by distance then id
48
+ (``exact_scan_select()``): the distance is the function SurrealDB's scan computes (``exact_distance()``), bit for bit,
49
+ on the records its scan scores (``scored_vector()``). The KNN then searches exactly those ids, so each record's
50
+ ``vector::distance::knn()`` stays SurrealDB's own; SurrealDB 3.x's exact scan, which gives one answer, is unchanged.
51
+
45
52
  **The server's dimension error.** When the model does not declare a field's dimension, SurrealDB checks the query
46
53
  vector against the vector index and refuses one of another length; ``dimension_refusal()`` reads that refusal into the
47
54
  ORM's error, naming the field and both lengths (``is_dimension_error()`` tells it).
@@ -89,6 +96,17 @@ DEFAULT_EF = 100
89
96
  #: The distances the ORM writes, in SurrealDB's spelling.
90
97
  DISTANCES = ("EUCLIDEAN", "COSINE", "MANHATTAN", "CHEBYSHEV", "HAMMING")
91
98
 
99
+ #: The function call that computes each distance as SurrealDB's exact scan does, on a vector ``{column}`` and the query
100
+ #: vector ``${variable}``: the same value and type as ``vector::distance::knn()`` on SurrealDB 2.x and the embedded engine.
101
+ #: SurrealDB has no ``vector::distance::cosine()``: its scan's ``COSINE`` distance is 1 minus the cosine similarity.
102
+ _DISTANCE_CALLS = {
103
+ "EUCLIDEAN": "vector::distance::euclidean({column}, ${variable})",
104
+ "COSINE": "1 - vector::similarity::cosine({column}, ${variable})",
105
+ "MANHATTAN": "vector::distance::manhattan({column}, ${variable})",
106
+ "CHEBYSHEV": "vector::distance::chebyshev({column}, ${variable})",
107
+ "HAMMING": "vector::distance::hamming({column}, ${variable})",
108
+ }
109
+
92
110
  #: The storage types of a vector field and of an HNSW index, in SurrealDB's spelling.
93
111
  VECTOR_TYPES = ("F64", "F32", "I64", "I32", "I16")
94
112
 
@@ -554,6 +572,64 @@ def knn_condition(column: str, k: int, ef: int | None, dist: str | None, variabl
554
572
  return f"{column} <|{limit},{checked_distance(dist, subject='similar_to()')}|> ${variable}"
555
573
 
556
574
 
575
+ def exact_distance(column: str, dist: str, variable: str) -> str:
576
+ """The distance *dist* of *column* from the query vector ``$<variable>``, written as the function SurrealDB's exact
577
+ scan computes it: ``vector::distance::<dist>(<column>, $<variable>)``, ``1 - vector::similarity::cosine(<column>,
578
+ $<variable>)`` for ``COSINE``. Pure.
579
+
580
+ On SurrealDB 2.x and the embedded engine the value is ``vector::distance::knn()``'s for the same record: bit for bit
581
+ and of the same type (an ``int`` with ``HAMMING``) on a vector of floats or integers, the same number on one of
582
+ decimals (which may come as a decimal). The call raises on a record whose column is not a vector of the query's
583
+ length: :func:`scored_vector` keeps such records out. ``dist`` is written as the ORM's own constant, ``column`` must
584
+ be a field path and ``variable`` the name the ORM bound the query vector under (``_f<N>``).
585
+ """
586
+ validate_field_name(column, "similar_to field")
587
+ if not variable.startswith("_f") or not variable[2:].isdigit():
588
+ raise ValueError(f"exact_distance() binds the query vector as $_f<N>, not ${variable}.")
589
+ return _DISTANCE_CALLS[checked_distance(dist, subject="similar_to()")].format(column=column, variable=variable)
590
+
591
+
592
+ def scored_vector(column: str, dimension: int) -> str:
593
+ """The condition that *column* is a vector SurrealDB's exact scan scores against a query vector of *dimension*
594
+ numbers: ``type::is::array(<column>) AND array::len(<column>) = <dimension> AND type::is::number(array::min(<column>))
595
+ AND type::is::number(array::max(<column>))``. Pure; for SurrealDB 2.x and the embedded engine only (3.x renamed
596
+ ``type::is::array()``).
597
+
598
+ The scan skips, silently, a record whose column is missing, ``NULL``, not an array, an array of another length or
599
+ one holding an item that is not a number; :func:`exact_distance` would raise on it. SurrealDB orders values by their
600
+ type first, numbers between booleans and strings, so an array whose least and greatest items are numbers holds
601
+ numbers only: two passes over the array, where a closure on each item costs several times the scan.
602
+ """
603
+ validate_field_name(column, "similar_to field")
604
+ length = checked_count(dimension, subject="scored_vector()", arg="dimension", low=1, high=MAX_DIMENSION)
605
+ return (
606
+ f"type::is::array({column}) AND array::len({column}) = {length} AND type::is::number(array::min({column})) AND "
607
+ f"type::is::number(array::max({column}))"
608
+ )
609
+
610
+
611
+ def exact_scan_select(table: str, search: "KnnSearch", variable: str, conditions: Sequence[str]) -> str:
612
+ """The ids of the ``K`` nearest records of an exact scan, ranked by distance then id, for SurrealDB 2.x and the
613
+ embedded engine: ``(SELECT id, <distance> AS _knn_distance FROM <table> WHERE <conditions AND> <scored vector> ORDER
614
+ BY _knn_distance, id LIMIT <K>).id``. Pure.
615
+
616
+ *search* is the queryset's ``similar_to()`` with ``dist``, its query vector bound as ``$<variable>``; *conditions*
617
+ the other parts of the statement's ``WHERE``, already compiled, each AND-ed before the records are ranked. The
618
+ distance is :func:`exact_distance`'s and only the records the scan scores are ranked (:func:`scored_vector`), so
619
+ without a tie at the ``K``-th place the ids are the ones SurrealDB's scan returns, and with one the tied records
620
+ kept are the first by id, on every call. SurrealDB orders a ``NaN`` distance (a zero vector with ``COSINE``) first,
621
+ as its scan does.
622
+ """
623
+ if search.dist is None:
624
+ raise ValueError("exact_scan_select() ranks an exact scan: the search has no distance.")
625
+ where = " AND ".join([*conditions, scored_vector(search.column, len(search.vector))])
626
+ distance = exact_distance(search.column, search.dist, variable)
627
+ return (
628
+ f"(SELECT id, {distance} AS {DISTANCE_ALIAS} FROM {table} WHERE {where} ORDER BY {DISTANCE_ALIAS}, id "
629
+ f"LIMIT {checked_limit(search.k)}).id"
630
+ )
631
+
632
+
557
633
  def id_subquery_part(part: str) -> bool:
558
634
  """Whether *part*, one AND-ed condition the queryset wrote for a KNN statement's ``WHERE``, is exactly one of the
559
635
  ORM's id subqueries — ``id IN $_sq<N>`` (``filter(id__in=Subquery(...))``) or ``$_sq<N> CONTAINS id`` (its form on a