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.
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/CHANGELOG.md +81 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/PKG-INFO +29 -12
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/README.md +28 -11
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/pyproject.toml +1 -1
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/connection_manager.py +13 -5
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/model_base.py +23 -4
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/query_set.py +49 -21
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/search.py +58 -22
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/subquery.py +4 -3
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/transaction.py +46 -6
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/vector.py +76 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/.gitignore +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/LICENSE +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/Makefile +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/define_parser.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/hybrid.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/introspection.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/model_ddl.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/model_generator.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/schema.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/schema_state.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/types.py +0 -0
- {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.
|
|
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
|
|
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=`)
|
|
6654
|
-
|
|
6655
|
-
|
|
6656
|
-
|
|
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
|
|
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
|
|
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=`)
|
|
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
|
|
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=`)
|
|
6603
|
-
|
|
6604
|
-
|
|
6605
|
-
|
|
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
|
|
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
|
|
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=`)
|
|
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
|
---
|
{surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/connection_manager.py
RENAMED
|
@@ -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.
|
|
2754
|
-
|
|
2755
|
-
|
|
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
|
|
2806
|
-
|
|
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
|
|
1637
|
-
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
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)
|
|
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``,
|
|
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
|
|
1896
|
-
``None`` decides it once, right after the first compilation — the line read once per
|
|
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
|
|
1939
|
-
compilation and, below SurrealDB 3, the statement compiled again for the key; the decision is passed
|
|
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)
|
|
1971
|
-
(``compiler.knn_conditions``) is the line read, once per client
|
|
1972
|
-
connection's client, an interactive transaction's included. A version
|
|
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),
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
|
81
|
-
|
|
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
|
|
1453
|
-
|
|
1454
|
-
|
|
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
|
-
|
|
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)
|
|
1484
|
-
|
|
1485
|
-
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
|
|
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
|
-
|
|
1499
|
-
|
|
1500
|
-
|
|
1501
|
-
|
|
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
|
-
|
|
232
|
-
|
|
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
|
|
37
|
-
those that use the analyzer (issue #323). The commit and the cancel keep the note, like
|
|
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).
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/connection_config.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/testing/__init__.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/testing/database.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.37.2 → surreal_orm_lite-0.37.5}/src/surreal_orm_lite/testing/fixtures.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|