surreal-orm-lite 0.37.2__tar.gz → 0.37.5__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.5}/CHANGELOG.md +81 -0
  2. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/PKG-INFO +29 -12
  3. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/README.md +28 -11
  4. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/connection_manager.py +13 -5
  7. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/model_base.py +23 -4
  8. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/query_set.py +49 -21
  9. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/search.py +58 -22
  10. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/subquery.py +4 -3
  11. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/transaction.py +46 -6
  12. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/vector.py +76 -0
  13. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/.gitignore +0 -0
  14. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/LICENSE +0 -0
  15. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/Makefile +0 -0
  16. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/_sdk.py +0 -0
  17. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/aggregations.py +0 -0
  18. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/auth.py +0 -0
  19. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/cache.py +0 -0
  20. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/changefeed.py +0 -0
  21. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/concurrency.py +0 -0
  22. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/connection_config.py +0 -0
  23. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/constants.py +0 -0
  24. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/decoding.py +0 -0
  25. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/define_parser.py +0 -0
  26. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/edge.py +0 -0
  27. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/embedded.py +0 -0
  28. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/encoding.py +0 -0
  29. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/enum.py +0 -0
  30. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/exceptions.py +0 -0
  31. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/functions.py +0 -0
  32. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/geo.py +0 -0
  33. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/hybrid.py +0 -0
  34. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/introspection.py +0 -0
  35. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/live.py +0 -0
  36. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/model_auth.py +0 -0
  37. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/model_ddl.py +0 -0
  38. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/model_generator.py +0 -0
  39. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/py.typed +0 -0
  40. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/q.py +0 -0
  41. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/routing.py +0 -0
  42. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/schema.py +0 -0
  43. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/schema_state.py +0 -0
  44. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/signals.py +0 -0
  45. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/surql_literal.py +0 -0
  46. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/testing/__init__.py +0 -0
  47. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/testing/database.py +0 -0
  48. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  49. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/time_travel.py +0 -0
  50. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/types.py +0 -0
  51. {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/utils.py +0 -0
@@ -5,6 +5,87 @@ 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
+
40
+ ## [0.37.5] - 2026-10-27
41
+
42
+ Follow-up to the review of v0.36.4 (#328): analyzer DDL in a transaction now counts the indexes
43
+ that `define_indexes(tx=…)` defined earlier in the same block. No new public API.
44
+
45
+ ### Fixed
46
+
47
+ - **`remove_analyzer(tx=…)` refuses an analyzer that an index defined in the block uses**
48
+ (#329). On SurrealDB 2.x and the embedded engine, it found the indexes that use the analyzer by
49
+ reading committed state, where an index that `define_indexes(tx=…)` defined earlier in the
50
+ block does not stand yet. Such a block committed and left the index without its analyzer: every
51
+ later write to the table was then refused ("The analyzer '…' does not exist"). On SurrealDB 3.x
52
+ the server refused the removal itself, which failed the block. The removal is now refused before
53
+ any DDL, with the existing "in use by index …" message, on every engine and line, and the
54
+ refusal does not fail the block. The transaction's note costs no request.
55
+ - **`define_analyzer(…, overwrite=True, tx=…)` refuses a redefinition when an index defined in
56
+ the block uses the analyzer** (#329). The block committed without `REBUILD INDEX` on every
57
+ engine, so the index kept the tokens of the old definition and a search could miss records.
58
+ The redefinition is now refused as one with indexes to rebuild, with the existing message,
59
+ before any DDL. The v0.36.4 note "an index queued earlier in a buffered block is still not seen"
60
+ no longer holds for `define_indexes(tx=…)`: both orders are guarded, in interactive and
61
+ buffered blocks, over WebSocket, HTTP and the embedded engine.
62
+ - **The last change of an index name in the block wins** (#329). An index defined then removed in
63
+ the block (`remove_index(tx=…)`) no longer counts. One that the block defined again with
64
+ another analyzer counts for that analyzer only, so the analyzer it held in committed state can
65
+ be removed or redefined in the block. An index defined with `IF NOT EXISTS`
66
+ (`define_indexes(overwrite=False, tx=…)`) keeps the block's earlier definition (another model's
67
+ on the same table) and counts with the analyzer that one gave it. A refused
68
+ `define_indexes(tx=…)` notes nothing. A raw `tx.add("DEFINE INDEX …")` is not tracked.
69
+
70
+ ### Notes
71
+
72
+ - **Behaviour table**: a new row for `define_indexes(tx=)` then `remove_index(tx=)` in one block,
73
+ the index not stored before the block. SurrealDB 3.x fails the commit with a retryable
74
+ `SurrealDbConflictError` whatever the table holds, and nothing is committed; 2.x and the
75
+ embedded engine commit it, the index absent afterwards. An index stored before the block,
76
+ redefined and then removed in it, fails the commit the same way on 2.x too when the table held
77
+ records, the index standing as before; the embedded engine commits it (README section 36,
78
+ Transactions). Measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded
79
+ engine, identical on 3.1.5.
80
+ - **Docs**: README section 36 (Transactions) and the docstrings of `define_indexes()`,
81
+ `remove_index()`, `define_analyzer()` and `remove_analyzer()` describe the guarded orders.
82
+ - **Tests**: 76 new tests in `tests/test_search.py`: 18 unit tests of the transaction's notes and
83
+ of the analyzer DDL against them, 57 end-to-end tests over WebSocket, HTTP and the embedded
84
+ engine, in interactive and buffered blocks, and one check of the new behaviour-table row and its
85
+ intro sentence.
86
+ - Server pins unchanged: tested against SurrealDB 3.3.4 and 2.7.0 and on the embedded engine,
87
+ plus 3.1.5 for backward compatibility.
88
+
8
89
  ## [0.37.2] - 2026-10-27
9
90
 
10
91
  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.5
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
@@ -6141,13 +6141,25 @@ print(await NoteV2.objects().search(text="physics").count())
6141
6141
  - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6142
6142
  in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again; so does a
6143
6143
  block that removes an index of a table that held records and defines it again, where the index stands as before.
6144
- Nothing of such a block is committed. On an empty table both commit, as on 3.x.
6144
+ Nothing of such a block is committed. On an empty table both commit, as on 3.x. On SurrealDB 3.x, a block that
6145
+ defines an index and then removes it fails the commit the same way, whatever the table holds; 2.x and the embedded
6146
+ engine commit it when the index was not stored before the block. An index stored before the block, redefined by
6147
+ `define_indexes(tx=…)` and then removed, fails the commit the same way on 2.x too when the table held records, where
6148
+ the index stands as before; the embedded engine commits it.
6145
6149
  - `remove_analyzer(tx=…)` (on SurrealDB 2.x and the embedded engine; 3.x checks in the transaction itself) and
6146
6150
  `define_analyzer(tx=…)` read committed state to find the indexes that use the analyzer. An index `remove_index(tx=…)`
6147
6151
  removed earlier in the block no longer counts, although committed state still holds it: once the block has removed the
6148
6152
  last index that uses an analyzer, it can remove the analyzer, or redefine it without `REBUILD INDEX`, on every engine.
6149
6153
  An index removed then defined again in the block, or removed with a raw `tx.add("REMOVE INDEX …")`, still counts
6150
- there, and an index queued earlier in a buffered block is not seen.
6154
+ there.
6155
+ - An index `define_indexes(tx=…)` defined earlier in the block counts too, with the analyzer the block gave it, although
6156
+ committed state does not hold it yet, or holds it with another analyzer: `remove_analyzer(tx=…)` and
6157
+ `define_analyzer(tx=…)` of that analyzer raise `SurrealDbError` before any DDL, naming the index, on every engine —
6158
+ SurrealDB 3.x included, whose own refusal of the removal used to fail the block. The refusal does not fail the block.
6159
+ An index defined then removed in the block no longer counts, and one the block defined again with another analyzer
6160
+ counts for that analyzer only. An index defined with `IF NOT EXISTS` (`define_indexes(overwrite=False, tx=…)`) keeps the
6161
+ block's earlier definition, and counts with the analyzer that one gave it. A raw `tx.add("DEFINE INDEX …")` is not
6162
+ tracked.
6151
6163
  - Once the block has removed or redefined an analyzer, an index that uses it can no longer be defined in the block,
6152
6164
  whether the model declares the analyzer as an `Analyzer` or names it by `str`: `define_indexes(tx=…)` raises
6153
6165
  `SurrealDbError` before any DDL. A removed analyzer counts as missing, although committed state still holds it — the
@@ -6478,6 +6490,10 @@ print(await annotated.count(), await annotated.exists())
6478
6490
  that keeps a tenth of the table. Pass `dist=` for an exact scan.
6479
6491
  - Distances are computed in the index's `vector_type` (`F32` by default: single precision), so they can differ from
6480
6492
  Python's in the last digits; `dist=` computes in double precision.
6493
+ - SurrealDB 2.x's and the embedded engine's exact scan (`dist=`) picks among records at an equal distance at the
6494
+ `limit`-th place in no fixed order, so there the ORM ranks it by distance, then id: identical calls return the same
6495
+ records in the same order, the tied ones by id, and a page, a `Subquery` and the bulk writes take the same records.
6496
+ SurrealDB 3.x's own scan gives one answer.
6481
6497
  - `COSINE` has no distance for a zero vector: `similar_to()` refuses a zero query vector when the distance is
6482
6498
  `COSINE` — `dist="cosine"`, or the model's `COSINE` index on the field —, and a record holding a zero vector gets a
6483
6499
  `nan` distance.
@@ -6650,10 +6666,11 @@ except SurrealDbError as error:
6650
6666
  more than half the documents scores `0.0` on SurrealDB 3.x and below zero on 2.x and the embedded engine
6651
6667
  ([2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x)), so the full-text list, and the fused ranking with it, can
6652
6668
  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.
6669
+ - **An exact scan (`dist=`) returns the same vector list on every call**, on every line. SurrealDB 2.x's and the
6670
+ embedded engine's own scan picks among records at an equal distance at the `vector_limit`-th place in no fixed order,
6671
+ so there the ORM ranks it by distance, then id, as for `similar_to()` (section 37): the tied records are kept by id,
6672
+ and a page read with `offset()` and `limit()` never skips nor repeats one. The HNSW index (no `dist=`) returns the
6673
+ same list on every call too.
6657
6674
  - Each search needs its index. Without a full-text index on `text_field`, SurrealDB 3.3, 2.x and the embedded engine
6658
6675
  refuse the search, and `hybrid_search()` raises `SurrealDbError` naming the field, as above; SurrealDB 3.1 and 3.2
6659
6676
  match nothing, so the vector list alone is fused.
@@ -6696,8 +6713,7 @@ except ValueError as error:
6696
6713
  2.x and the embedded engine; the full ORM calls `search::rrf()` with arguments SurrealDB 3.3 refuses, and runs on
6697
6714
  3.x only.
6698
6715
  - **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.
6716
+ page, and an exact scan (`dist=`) gives the same vector list on every line, as above.
6701
6717
  - **Checked before any request**: both fields, the vector, `vector_limit` and `text_limit` (1 to 10 000), `rrf_k`
6702
6718
  (0 to 10 000), `ef` and `dist`; the full ORM checks the field names only.
6703
6719
  - **Reciprocal Rank Fusion only**: `search::linear()` (weights and score normalisation) is not offered yet.
@@ -6824,7 +6840,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6824
6840
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6825
6841
  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
6842
  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.
6843
+ 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. The row added in v0.37.5 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
6844
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6829
6845
 
6830
6846
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6989,7 +7005,8 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6989
7005
  | `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
7006
  | `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
7007
  | `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) |
7008
+ | 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 |
7009
+ | `define_indexes(tx=)` then `remove_index(tx=)` in one block, the index not stored before the block | committed: the index absent after the commit, whatever the table holds | the commit fails with a retryable `SurrealDbConflictError`, whatever the table holds: nothing committed | v0.37.5 |
6993
7010
  | 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
7011
 
6995
7012
  > **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 +7047,7 @@ Capabilities not listed behave as on a 2.x server.
7030
7047
  | `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
7048
  | 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
7049
  | `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 |
7050
+ | 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
7051
  | 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
7052
 
7036
7053
  ---
@@ -6090,13 +6090,25 @@ print(await NoteV2.objects().search(text="physics").count())
6090
6090
  - Prefer `define_indexes()` outside the block: on SurrealDB 2.x, a write to a table that held records, after its index
6091
6091
  in the same block, fails the commit with a retryable `SurrealDbConflictError` that a retry meets again; so does a
6092
6092
  block that removes an index of a table that held records and defines it again, where the index stands as before.
6093
- Nothing of such a block is committed. On an empty table both commit, as on 3.x.
6093
+ Nothing of such a block is committed. On an empty table both commit, as on 3.x. On SurrealDB 3.x, a block that
6094
+ defines an index and then removes it fails the commit the same way, whatever the table holds; 2.x and the embedded
6095
+ engine commit it when the index was not stored before the block. An index stored before the block, redefined by
6096
+ `define_indexes(tx=…)` and then removed, fails the commit the same way on 2.x too when the table held records, where
6097
+ the index stands as before; the embedded engine commits it.
6094
6098
  - `remove_analyzer(tx=…)` (on SurrealDB 2.x and the embedded engine; 3.x checks in the transaction itself) and
6095
6099
  `define_analyzer(tx=…)` read committed state to find the indexes that use the analyzer. An index `remove_index(tx=…)`
6096
6100
  removed earlier in the block no longer counts, although committed state still holds it: once the block has removed the
6097
6101
  last index that uses an analyzer, it can remove the analyzer, or redefine it without `REBUILD INDEX`, on every engine.
6098
6102
  An index removed then defined again in the block, or removed with a raw `tx.add("REMOVE INDEX …")`, still counts
6099
- there, and an index queued earlier in a buffered block is not seen.
6103
+ there.
6104
+ - An index `define_indexes(tx=…)` defined earlier in the block counts too, with the analyzer the block gave it, although
6105
+ committed state does not hold it yet, or holds it with another analyzer: `remove_analyzer(tx=…)` and
6106
+ `define_analyzer(tx=…)` of that analyzer raise `SurrealDbError` before any DDL, naming the index, on every engine —
6107
+ SurrealDB 3.x included, whose own refusal of the removal used to fail the block. The refusal does not fail the block.
6108
+ An index defined then removed in the block no longer counts, and one the block defined again with another analyzer
6109
+ counts for that analyzer only. An index defined with `IF NOT EXISTS` (`define_indexes(overwrite=False, tx=…)`) keeps the
6110
+ block's earlier definition, and counts with the analyzer that one gave it. A raw `tx.add("DEFINE INDEX …")` is not
6111
+ tracked.
6100
6112
  - Once the block has removed or redefined an analyzer, an index that uses it can no longer be defined in the block,
6101
6113
  whether the model declares the analyzer as an `Analyzer` or names it by `str`: `define_indexes(tx=…)` raises
6102
6114
  `SurrealDbError` before any DDL. A removed analyzer counts as missing, although committed state still holds it — the
@@ -6427,6 +6439,10 @@ print(await annotated.count(), await annotated.exists())
6427
6439
  that keeps a tenth of the table. Pass `dist=` for an exact scan.
6428
6440
  - Distances are computed in the index's `vector_type` (`F32` by default: single precision), so they can differ from
6429
6441
  Python's in the last digits; `dist=` computes in double precision.
6442
+ - SurrealDB 2.x's and the embedded engine's exact scan (`dist=`) picks among records at an equal distance at the
6443
+ `limit`-th place in no fixed order, so there the ORM ranks it by distance, then id: identical calls return the same
6444
+ records in the same order, the tied ones by id, and a page, a `Subquery` and the bulk writes take the same records.
6445
+ SurrealDB 3.x's own scan gives one answer.
6430
6446
  - `COSINE` has no distance for a zero vector: `similar_to()` refuses a zero query vector when the distance is
6431
6447
  `COSINE` — `dist="cosine"`, or the model's `COSINE` index on the field —, and a record holding a zero vector gets a
6432
6448
  `nan` distance.
@@ -6599,10 +6615,11 @@ except SurrealDbError as error:
6599
6615
  more than half the documents scores `0.0` on SurrealDB 3.x and below zero on 2.x and the embedded engine
6600
6616
  ([2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x)), so the full-text list, and the fused ranking with it, can
6601
6617
  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.
6618
+ - **An exact scan (`dist=`) returns the same vector list on every call**, on every line. SurrealDB 2.x's and the
6619
+ embedded engine's own scan picks among records at an equal distance at the `vector_limit`-th place in no fixed order,
6620
+ so there the ORM ranks it by distance, then id, as for `similar_to()` (section 37): the tied records are kept by id,
6621
+ and a page read with `offset()` and `limit()` never skips nor repeats one. The HNSW index (no `dist=`) returns the
6622
+ same list on every call too.
6606
6623
  - Each search needs its index. Without a full-text index on `text_field`, SurrealDB 3.3, 2.x and the embedded engine
6607
6624
  refuse the search, and `hybrid_search()` raises `SurrealDbError` naming the field, as above; SurrealDB 3.1 and 3.2
6608
6625
  match nothing, so the vector list alone is fused.
@@ -6645,8 +6662,7 @@ except ValueError as error:
6645
6662
  2.x and the embedded engine; the full ORM calls `search::rrf()` with arguments SurrealDB 3.3 refuses, and runs on
6646
6663
  3.x only.
6647
6664
  - **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.
6665
+ page, and an exact scan (`dist=`) gives the same vector list on every line, as above.
6650
6666
  - **Checked before any request**: both fields, the vector, `vector_limit` and `text_limit` (1 to 10 000), `rrf_k`
6651
6667
  (0 to 10 000), `ef` and `dist`; the full ORM checks the field names only.
6652
6668
  - **Reciprocal Rank Fusion only**: `search::linear()` (weights and score normalisation) is not offered yet.
@@ -6773,7 +6789,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
6773
6789
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
6774
6790
  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
6791
  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.
6792
+ 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. The row added in v0.37.5 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
6793
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
6778
6794
 
6779
6795
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -6938,7 +6954,8 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
6938
6954
  | `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
6955
  | `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
6956
  | `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) |
6957
+ | 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 |
6958
+ | `define_indexes(tx=)` then `remove_index(tx=)` in one block, the index not stored before the block | committed: the index absent after the commit, whatever the table holds | the commit fails with a retryable `SurrealDbConflictError`, whatever the table holds: nothing committed | v0.37.5 |
6942
6959
  | 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
6960
 
6944
6961
  > **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 +6996,7 @@ Capabilities not listed behave as on a 2.x server.
6979
6996
  | `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
6997
  | 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
6998
  | `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 |
6999
+ | 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
7000
  | 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
7001
 
6985
7002
  ---
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.37.2"
3
+ version = "0.37.5"
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.5"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -2750,9 +2750,13 @@ class SurrealDBConnectionManager:
2750
2750
  removed earlier with the same *tx* is not to rebuild, although committed state still holds it: once the block
2751
2751
  has removed every index that uses the analyzer, the redefinition joins the transaction, without
2752
2752
  ``REBUILD INDEX``. An index removed then defined again in the block (``define_indexes(tx=…)``), or removed with
2753
- a raw ``tx.add("REMOVE INDEX …")``, which the transaction does not track, still counts. The transaction notes
2754
- the analyzer it defines or redefines: ``Model.define_indexes(tx=…)`` then refuses, before any DDL, to define in
2755
- the block an index that uses it — SurrealDB would build it with the committed definition. An analyzer
2753
+ a raw ``tx.add("REMOVE INDEX …")``, which the transaction does not track, still counts. An index
2754
+ ``Model.define_indexes()`` defined earlier with the same *tx* counts with the analyzer the block gave it,
2755
+ although committed state does not hold it yet, or holds it with another analyzer (issue #329): the redefinition
2756
+ of that analyzer is refused before any DDL, and the refusal does not fail the block; an index defined then
2757
+ removed in the block no longer counts. The transaction notes the analyzer it defines or redefines:
2758
+ ``Model.define_indexes(tx=…)`` then refuses, before any DDL, to define in the block an index that uses it —
2759
+ SurrealDB would build it with the committed definition. An analyzer
2756
2760
  :meth:`remove_analyzer` removed earlier with the same *tx* counts as missing, although committed state still
2757
2761
  holds it: it is defined again after its removal.
2758
2762
 
@@ -2802,8 +2806,12 @@ class SurrealDBConnectionManager:
2802
2806
  removed earlier with the same *tx* is left out, although committed state still holds it, so a block that
2803
2807
  removes the last index using the analyzer and then the analyzer commits, as on SurrealDB 3.x, which checks in
2804
2808
  the transaction; an index removed then defined again in the block, or removed with a raw
2805
- ``tx.add("REMOVE INDEX …")``, which the transaction does not track, still counts, and an index queued earlier in
2806
- a buffered block is not seen. The transaction notes the removal: ``Model.define_indexes(tx=…)`` then counts the
2809
+ ``tx.add("REMOVE INDEX …")``, which the transaction does not track, still counts. On every line, SurrealDB 3.x
2810
+ included, an index ``Model.define_indexes()`` defined earlier with the same *tx* counts with the analyzer the
2811
+ block gave it, although committed state does not hold it yet, or holds it with another analyzer (issue #329):
2812
+ the removal of that analyzer is refused before any DDL — the transaction's note costs no request — and the
2813
+ refusal does not fail the block (on 3.x, the server's own refusal used to); an index defined then removed in the
2814
+ block no longer counts. The transaction notes the removal: ``Model.define_indexes(tx=…)`` then counts the
2807
2815
  analyzer as missing, although committed state still holds it, and refuses, before any DDL, to define in the
2808
2816
  block an index that uses it — the commit would leave that index without its analyzer, and every write to its
2809
2817
  table refused; :meth:`define_analyzer` with the same *tx* defines it again. No cached read is dropped: a
@@ -1523,6 +1523,15 @@ class BaseSurrealModel(BaseModel):
1523
1523
  ``define_analyzer()`` redefined with the same *tx* is refused too, whether the model declares it or names it:
1524
1524
  SurrealDB would build it with the committed definition. Call ``define_analyzer()`` without *tx* first.
1525
1525
 
1526
+ **The indexes defined in the transaction** (issue #329). With *tx*, the transaction notes each index this call
1527
+ defines or redefines, with its analyzer, once the statements are applied or queued — nothing when the call
1528
+ refuses or a statement is refused at once. ``remove_analyzer()`` and ``define_analyzer()`` with the same *tx*
1529
+ count those indexes, although committed state does not hold them yet (or holds them with another analyzer):
1530
+ removing or redefining their analyzer later in the block is refused before any DDL, on every engine. An index
1531
+ :meth:`remove_index` then removes with the same *tx* no longer counts. Without *overwrite*, an index defined
1532
+ with ``IF NOT EXISTS`` keeps the block's earlier definition — another model's on the same table, with another
1533
+ analyzer — and so does the note: that index counts with the analyzer the block gave it first.
1534
+
1526
1535
  Names are written in backticks, filters re-rendered from a closed grammar, numbers from Python numbers,
1527
1536
  comments as string literals. A refusal names the analyzer or the index and its table, never the statement:
1528
1537
  ``Can't apply index definition: 'post_title' on table 'post' -> <reason>``. Applying needs a session allowed to
@@ -1534,7 +1543,8 @@ class BaseSurrealModel(BaseModel):
1534
1543
  what is missing (``IF NOT EXISTS``) and leaves what exists as it is.
1535
1544
  tx: optional transaction the index statements are applied with; the reads happen before anything is
1536
1545
  queued. An index :meth:`remove_index` removed with it counts as missing, and so does an analyzer
1537
- ``remove_analyzer()`` removed with it.
1546
+ ``remove_analyzer()`` removed with it. It notes the indexes defined, for ``remove_analyzer()`` and
1547
+ ``define_analyzer()``.
1538
1548
 
1539
1549
  Raises:
1540
1550
  TypeError: *overwrite* is not a ``bool`` — before any request.
@@ -1633,8 +1643,13 @@ class BaseSurrealModel(BaseModel):
1633
1643
  classify=True,
1634
1644
  subjects=[index_subject(name, table) for name, _ in definitions],
1635
1645
  )
1636
- if removed and isinstance(tx, Transaction):
1637
- tx._forget_index_removals(table, (name for name, _ in definitions))
1646
+ if isinstance(tx, Transaction):
1647
+ # Noted once applied or queued: every refusal above notes nothing. Issue #312: an index defined again is no
1648
+ # longer missing (its removal is forgotten). Issue #329: remove_analyzer(tx=…) and define_analyzer(tx=…)
1649
+ # read committed state, which does not hold these definitions yet, or holds them with another analyzer.
1650
+ # Without overwrite, each is a DEFINE INDEX IF NOT EXISTS: one this block defined earlier stays as it was.
1651
+ for name, _ in definitions:
1652
+ tx._note_index_definition(table, name, analyzer_of[name], if_not_exists=not overwrite)
1638
1653
  applied += await apply_rebuilds(client, tx, own_rebuilds)
1639
1654
  warn_redefined(redefine, [*other_rebuilds, *redefined_indexes, *own_rebuilds])
1640
1655
  return applied
@@ -1654,7 +1669,11 @@ class BaseSurrealModel(BaseModel):
1654
1669
  index as missing, although committed state still holds it, and defines it again after the removal when its
1655
1670
  model declares it — so removing an index and defining it again in one block keeps it. On SurrealDB 2.x, on a
1656
1671
  table that held records, such a block fails the commit with a retryable ``SurrealDbConflictError`` that a retry
1657
- meets again, and nothing of it is committed. ``SurrealDBConnectionManager.remove_analyzer(tx=…)`` and
1672
+ meets again, and nothing of it is committed. On SurrealDB 3.x, the reverse — a block that defines an index
1673
+ (:meth:`define_indexes`) and then removes it — fails the commit the same way, whatever the table holds; 2.x and
1674
+ the embedded engine commit it when the index was not stored before the block. When it was, and the block
1675
+ redefined it before removing it, 2.x fails the commit the same way on a table that held records, the index
1676
+ standing as before, and the embedded engine commits it. ``SurrealDBConnectionManager.remove_analyzer(tx=…)`` and
1658
1677
  ``define_analyzer(tx=…)`` read the note too: the removed index no longer counts as one using the analyzer (issue
1659
1678
  #323); once the block has removed or redefined that analyzer, :meth:`define_indexes` refuses to define the index
1660
1679
  again in it. A raw ``tx.add("REMOVE INDEX …")`` is not noted.
@@ -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.
@@ -60,10 +60,12 @@ warning per redefined analyzer. ``apply_analyzer()`` and ``apply_analyzer_remova
60
60
  manager's ``define_analyzer()`` and ``remove_analyzer()``; the latter refuses, below SurrealDB 3 (2.x, the embedded
61
61
  engine, which would remove it and then refuse every write to the table), an analyzer an index uses, with 3.x's own
62
62
  reason. With a transaction, both leave out the indexes ``remove_index(tx=…)`` removed earlier in it, which committed
63
- state still holds (``indexes_removed_in()``, the transaction's note — issue #323), and note the analyzer they removed
64
- or defined (``note_analyzer_change()``): ``define_analyzer(tx=…)`` and ``define_indexes(tx=…)`` count one the block
65
- removed as missing (``analyzers_after_removals()``), and ``define_indexes(tx=…)`` refuses an index whose analyzer the
66
- block redefined (``transaction_redefined_analyzer_refused()``).
63
+ state still holds (``indexes_removed_in()``, the transaction's note — issue #323), count those ``define_indexes(tx=…)``
64
+ defined earlier in it with the analyzer it gave them, which committed state does not hold yet
65
+ (``indexes_using_once_committed()``, issue #329; ``remove_analyzer(tx=…)`` on every line), and note the analyzer they
66
+ removed or defined (``note_analyzer_change()``): ``define_analyzer(tx=…)`` and ``define_indexes(tx=…)`` count one the
67
+ block removed as missing (``analyzers_after_removals()``), and ``define_indexes(tx=…)`` refuses an index whose analyzer
68
+ the block redefined (``transaction_redefined_analyzer_refused()``).
67
69
 
68
70
  **The query side.** ``QuerySet.search()`` checks its fields and texts with ``checked_search_field()`` and words its
69
71
  refusals with ``text_refused()``, ``field_refused()``, ``too_many_fields()``, ``time_travel_refused()`` (with
@@ -77,8 +79,8 @@ annotation whose match reference ``search()`` did not give it is refused with ``
77
79
  ``search()`` with ``no_search_refused()``.
78
80
 
79
81
  The module sits low in the package: it imports neither ``model_base``, ``query_set`` nor ``connection_manager``, so
80
- each of them can import it; it imports ``transaction``, which imports none of them, for its note of the removed
81
- indexes.
82
+ each of them can import it; it imports ``transaction``, which imports none of them, for its notes of the indexes
83
+ removed and defined.
82
84
  """
83
85
 
84
86
  import logging
@@ -1170,7 +1172,9 @@ async def indexes_using(
1170
1172
  the parser cannot read is left out (its analyzer is unknown), and so is one *skip* names for its table: *skip*
1171
1173
  takes a table's name, as ``INFO FOR DB`` gives it, and returns the names of its indexes to leave out —
1172
1174
  :func:`indexes_removed_in`'s, the indexes ``remove_index(tx=…)`` removed earlier in a transaction, which committed
1173
- state still holds (issue #323). Every table is read all the same.
1175
+ state still holds (issue #323). Every table is read all the same. An index ``define_indexes(tx=…)`` defined earlier
1176
+ in a transaction is not here, or with the committed analyzer: :func:`indexes_using_once_committed` gives the indexes
1177
+ once the transaction commits (issue #329).
1174
1178
 
1175
1179
  :param what: what the reads are for, for the message of a refusal (``"index"``, ``"analyzer"``).
1176
1180
  :param kind: ``"definition"``, ``"removal"`` or ``"rebuild"``, likewise.
@@ -1192,6 +1196,29 @@ def indexes_removed_in(tx: object) -> Callable[[str], frozenset[str]] | None:
1192
1196
  return tx._indexes_removed if isinstance(tx, Transaction) else None
1193
1197
 
1194
1198
 
1199
+ def indexes_using_once_committed(found: Iterable[IndexUse], analyzers: Collection[str], tx: object) -> list[IndexUse]:
1200
+ """The indexes that use one of *analyzers* once *tx* commits, as ``(table, index, analyzer)``, sorted by table then
1201
+ index — pure (issue #329).
1202
+
1203
+ *found* is committed state: :func:`indexes_using`'s answer for *analyzers*, the indexes ``remove_index(tx=…)``
1204
+ removed in *tx* already left out (:func:`indexes_removed_in`), or ``[]`` when committed state was not read. An index
1205
+ ``define_indexes(tx=…)`` defined in *tx* and did not remove since (``Transaction._indexes_defined``) replaces the
1206
+ committed one of its name on its table — the analyzer the block gave it wins — and counts when that analyzer is
1207
+ among *analyzers*: committed state does not hold it yet. *found*, sorted, when *tx* is not a ``Transaction``.
1208
+ """
1209
+ if not isinstance(tx, Transaction):
1210
+ return sorted(found)
1211
+ defined = tx._indexes_defined()
1212
+ kept = [use for use in found if use[1] not in defined.get(use[0], {})]
1213
+ kept.extend(
1214
+ (table, name, analyzer)
1215
+ for table, indexes in defined.items()
1216
+ for name, analyzer in indexes.items()
1217
+ if analyzer and analyzer in analyzers
1218
+ )
1219
+ return sorted(kept)
1220
+
1221
+
1195
1222
  def analyzers_after_removals(stored: Mapping[str, AnalyzerState | None], tx: object) -> dict[str, AnalyzerState | None]:
1196
1223
  """The analyzers *stored* holds (``INFO FOR DB``'s, committed state) without those ``remove_analyzer(tx=…)``
1197
1224
  removed earlier in *tx* and did not define again since — *tx*'s ``Transaction._analyzers_removed`` (issue #323):
@@ -1449,9 +1476,12 @@ async def apply_analyzer(client: Any, analyzer: Analyzer, *, overwrite: bool, tx
1449
1476
  follow the committed definition); a new analyzer, or a redefinition no index uses, joins the transaction. An index
1450
1477
  ``remove_index(tx=…)`` removed earlier in *tx* is not to rebuild, although committed state still holds it
1451
1478
  (:func:`indexes_removed_in`, issue #323): a redefinition whose indexes the block all removed joins the transaction,
1452
- without ``REBUILD INDEX``. An analyzer ``remove_analyzer(tx=…)`` removed earlier in *tx* counts as missing
1453
- (:func:`analyzers_after_removals`): defined again after its removal, with no index read nor rebuilt. *tx* notes the
1454
- analyzer once defined or redefined (:func:`note_analyzer_change`), for ``define_indexes(tx=…)``.
1479
+ without ``REBUILD INDEX``. An index ``define_indexes(tx=…)`` defined earlier in *tx* counts with the analyzer the
1480
+ block gave it, although committed state does not hold it yet or holds it with another analyzer
1481
+ (:func:`indexes_using_once_committed`, issue #329): a redefinition of that analyzer is refused, and one of the
1482
+ analyzer it held before no longer rebuilds it. An analyzer ``remove_analyzer(tx=…)`` removed earlier in *tx* counts
1483
+ as missing (:func:`analyzers_after_removals`): defined again after its removal, with no index read nor rebuilt. *tx*
1484
+ notes the analyzer once defined or redefined (:func:`note_analyzer_change`), for ``define_indexes(tx=…)``.
1455
1485
 
1456
1486
  :raises SurrealDbError: *tx* is given and the redefinition has indexes to rebuild; a refused read or statement.
1457
1487
  :raises SurrealDbAuthenticationError: the session may not read the definitions or define the analyzer.
@@ -1461,9 +1491,10 @@ async def apply_analyzer(client: Any, analyzer: Analyzer, *, overwrite: bool, tx
1461
1491
  define, redefine = plan_analyzers([analyzer], analyzers_after_removals(stored, tx), overwrite)
1462
1492
  rebuilds: list[IndexUse] = []
1463
1493
  if redefine:
1464
- rebuilds = await indexes_using(
1494
+ found = await indexes_using(
1465
1495
  client, tables, {analyzer.name}, what="analyzer", kind="definition", skip=indexes_removed_in(tx)
1466
1496
  )
1497
+ rebuilds = indexes_using_once_committed(found, {analyzer.name}, tx)
1467
1498
  if tx is not None and rebuilds:
1468
1499
  raise SurrealDbError(analyzer_redefinition_refused(analyzer.name, rebuilds))
1469
1500
  applied = await apply_analyzers(client, tx, define, redefine, overwrite)
@@ -1480,25 +1511,30 @@ async def apply_analyzer_removal(client: Any, name: str, statement: str, *, tx:
1480
1511
 
1481
1512
  ``client.version()`` once. Below 3 (SurrealDB 2.x, the embedded engine), which accept the removal of an analyzer an
1482
1513
  index uses and then refuse every write to that table: ``INFO FOR DB``, then ``INFO FOR TABLE`` of every table
1483
- (:func:`indexes_using`, committed state), and the first index using it, in table then index order, refused with
1484
- SurrealDB 3.x's own reason, before any DDL. An index ``remove_index(tx=…)`` removed earlier in *tx* is left out,
1485
- although committed state still holds it (:func:`indexes_removed_in`, issue #323); an index queued earlier in a
1486
- buffered *tx* is not seen. From 3 on, the server refuses it itself, in the same words, in the transaction. Then the
1487
- statement, joining *tx* when given: ``Can't apply analyzer removal: '<name>' -> <reason>`` for a refusal. *tx*
1488
- notes the removal once applied or queued (:func:`note_analyzer_change`): ``define_analyzer(tx=…)`` and
1489
- ``define_indexes(tx=…)`` then count the analyzer as missing (issue #323).
1514
+ (:func:`indexes_using`, committed state). An index ``remove_index(tx=…)`` removed earlier in *tx* is left out,
1515
+ although committed state still holds it (:func:`indexes_removed_in`, issue #323). On every line, an index
1516
+ ``define_indexes(tx=…)`` defined earlier in *tx* counts with the analyzer the block gave it, which committed state
1517
+ does not hold yet (:func:`indexes_using_once_committed`, issue #329) — the note costs no request: from 3 on, where
1518
+ the server checks committed state itself, the line is the only read. The first index using the analyzer, in table
1519
+ then index order, is refused with SurrealDB 3.x's own reason, before any DDL; the refusal does not fail *tx*. From 3
1520
+ on, the server refuses any other in the same words, in the transaction. Then the statement, joining *tx* when given:
1521
+ ``Can't apply analyzer removal: '<name>' -> <reason>`` for a refusal. *tx* notes the removal once applied or queued
1522
+ (:func:`note_analyzer_change`): ``define_analyzer(tx=…)`` and ``define_indexes(tx=…)`` then count the analyzer as
1523
+ missing (issue #323).
1490
1524
 
1491
1525
  :raises SurrealDbError: an index uses the analyzer; a refused read or statement.
1492
1526
  :raises SurrealDbNotFoundError: ``REMOVE ANALYZER`` without ``IF EXISTS`` of a missing analyzer (outside a buffered
1493
1527
  transaction).
1494
1528
  :raises SurrealDbAuthenticationError: the session may not read the definitions or remove the analyzer.
1495
1529
  """
1530
+ found: list[IndexUse] = []
1496
1531
  if line_major(await client.version()) < 3:
1497
1532
  _, tables = await read_database_info(client, what="analyzer", kind="removal", subject=repr(name))
1498
- using = await indexes_using(client, tables, {name}, what="analyzer", kind="removal", skip=indexes_removed_in(tx))
1499
- if using:
1500
- table, index, _ = using[0]
1501
- raise SurrealDbError(analyzer_in_use_refused(name, index, table))
1533
+ found = await indexes_using(client, tables, {name}, what="analyzer", kind="removal", skip=indexes_removed_in(tx))
1534
+ using = indexes_using_once_committed(found, {name}, tx)
1535
+ if using:
1536
+ table, index, _ = using[0]
1537
+ raise SurrealDbError(analyzer_in_use_refused(name, index, table))
1502
1538
  await apply_ddl_statements(
1503
1539
  [statement], client=client, tx=tx, what="analyzer", kind="removal", classify=True, subjects=[repr(name)]
1504
1540
  )
@@ -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).
@@ -32,10 +32,20 @@ records a transaction wrote before the index was defined. A raw ``tx.add()`` is
32
32
 
33
33
  Indexes removed (issue #312): ``remove_index(tx=…)`` notes the index it removes, by table (``_note_index_removal``).
34
34
  ``define_indexes(tx=…)`` reads committed state, where that index still stands: it counts the indexes noted for its table
35
- (``_indexes_removed``) as missing, plans them again, and forgets those it defines (``_forget_index_removals``).
36
- ``remove_analyzer(tx=…)`` and ``define_analyzer(tx=…)`` read committed state too, and leave the noted indexes out of
37
- those that use the analyzer (issue #323). The commit and the cancel keep the note, like the tables written. A raw
38
- ``tx.add("REMOVE INDEX …")`` is not noted.
35
+ (``_indexes_removed``) as missing, plans them again, and forgets those it defines (``_forget_index_removals``, through
36
+ ``_note_index_definition``). ``remove_analyzer(tx=…)`` and ``define_analyzer(tx=…)`` read committed state too, and
37
+ leave the noted indexes out of those that use the analyzer (issue #323). The commit and the cancel keep the note, like
38
+ the tables written. A raw ``tx.add("REMOVE INDEX …")`` is not noted.
39
+
40
+ Indexes defined (issue #329): ``define_indexes(tx=…)`` notes each index it defines or redefines, by table, with its
41
+ analyzer (``_note_index_definition``, ``""`` for none), once the statements are applied or queued — a refusal notes
42
+ nothing. ``remove_analyzer(tx=…)`` and ``define_analyzer(tx=…)`` count them among the indexes that use their analyzer
43
+ (``_indexes_defined``), although committed state does not hold them yet, or holds them with another analyzer. The last
44
+ change of an index name wins: a definition forgets the removal noted for that name and replaces an earlier definition;
45
+ a removal drops the definition. A ``DEFINE INDEX IF NOT EXISTS`` (``define_indexes(overwrite=False, tx=…)``) is the
46
+ exception: it leaves an index the block defined earlier as it is, and the note keeps that definition. The commit and
47
+ the cancel keep the note; a statement a buffered commit refuses leaves it as noted, like the other notes. A raw
48
+ ``tx.add("DEFINE INDEX …")`` is not noted.
39
49
 
40
50
  Analyzers changed (issue #323): ``remove_analyzer(tx=…)`` notes the analyzer it removes (``_note_analyzer_removal``),
41
51
  ``define_analyzer(tx=…)`` the one it defines or redefines (``_note_analyzer_definition``); the last change of a name
@@ -248,6 +258,9 @@ class Transaction(ABC):
248
258
  # Issue #312: the indexes remove_index(tx=…) removed in this transaction, by table, until define_indexes(tx=…)
249
259
  # defines them again; kept until the transaction ends.
250
260
  self._removed_indexes: dict[str, set[str]] = {}
261
+ # Issue #329: the indexes define_indexes(tx=…) defined in this transaction, by table, each with its analyzer
262
+ # ("" for none) — the last change of an index name wins; kept until the transaction ends.
263
+ self._defined_indexes: dict[str, dict[str, str]] = {}
251
264
  # Issue #323: the analyzers remove_analyzer(tx=…) removed and those define_analyzer(tx=…) defined or redefined
252
265
  # in this transaction — the last change of a name wins; kept until the transaction ends.
253
266
  self._removed_analyzers: set[str] = set()
@@ -319,9 +332,12 @@ class Transaction(ABC):
319
332
  ``remove_index(tx=…)`` calls it once its ``REMOVE INDEX`` was applied (interactive) or queued (buffered).
320
333
  ``define_indexes(tx=…)``, which reads committed state where the index still stands, counts it as missing;
321
334
  ``remove_analyzer(tx=…)`` and ``define_analyzer(tx=…)`` no longer count it among the indexes that use an
322
- analyzer (issue #323). Like the tables written, the commit and the cancel keep it. A raw ``tx.add()`` is not
323
- noted.
335
+ analyzer (issue #323). A definition noted before for the same name on *table* is forgotten (issue #329). Like
336
+ the tables written, the commit and the cancel keep it. A raw ``tx.add()`` is not noted.
324
337
  """
338
+ defined = self._defined_indexes.get(table)
339
+ if defined is not None:
340
+ defined.pop(name, None)
325
341
  self._removed_indexes.setdefault(table, set()).add(name)
326
342
 
327
343
  def _indexes_removed(self, table: str) -> frozenset[str]:
@@ -336,6 +352,30 @@ class Transaction(ABC):
336
352
  if removed is not None:
337
353
  removed.difference_update(names)
338
354
 
355
+ def _note_index_definition(self, table: str, name: str, analyzer: str, *, if_not_exists: bool = False) -> None:
356
+ """Note that the index *name* of *table* was defined or redefined in this transaction with the analyzer
357
+ *analyzer* (``""`` for none) — issue #329.
358
+
359
+ ``define_indexes(tx=…)`` calls it for each index it defines, once their ``DEFINE INDEX`` statements were applied
360
+ (interactive) or queued (buffered): a refusal notes nothing. ``remove_analyzer(tx=…)`` and
361
+ ``define_analyzer(tx=…)``, which read committed state where the index is missing or holds another analyzer,
362
+ count it among the indexes that use *analyzer*. A removal noted before for the same name on *table* is forgotten
363
+ (:meth:`_forget_index_removals`), and a definition noted before replaced: the last change of a name wins. With
364
+ *if_not_exists* (a ``DEFINE INDEX IF NOT EXISTS``, ``define_indexes(overwrite=False, tx=…)``), a definition
365
+ noted before for the name is kept instead: the statement leaves the index the block defined earlier as it is.
366
+ The commit and the cancel keep it. A raw ``tx.add("DEFINE INDEX …")`` is not noted.
367
+ """
368
+ defined = self._defined_indexes.setdefault(table, {})
369
+ if if_not_exists and name in defined:
370
+ return
371
+ self._forget_index_removals(table, (name,))
372
+ defined[name] = analyzer
373
+
374
+ def _indexes_defined(self) -> dict[str, dict[str, str]]:
375
+ """The indexes defined in this transaction and not removed since, by table, each with its analyzer (``""`` for
376
+ none) — a copy, without the tables left with none (issue #329)."""
377
+ return {table: dict(indexes) for table, indexes in self._defined_indexes.items() if indexes}
378
+
339
379
  def _note_analyzer_removal(self, name: str) -> None:
340
380
  """Note that the analyzer *name* was removed in this transaction — issue #323.
341
381
 
@@ -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