surreal-orm-lite 0.37.1__tar.gz → 0.37.4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/CHANGELOG.md +56 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/PKG-INFO +23 -15
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/README.md +22 -14
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/pyproject.toml +1 -1
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/define_parser.py +4 -2
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/model_auth.py +33 -12
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/query_set.py +49 -21
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/schema_state.py +3 -2
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/subquery.py +4 -3
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/vector.py +76 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/.gitignore +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/LICENSE +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/Makefile +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/constants.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/hybrid.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/introspection.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/model_ddl.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/model_generator.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/schema.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/search.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/types.py +0 -0
- {surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/utils.py +0 -0
|
@@ -5,6 +5,62 @@ 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.2] - 2026-10-27
|
|
41
|
+
|
|
42
|
+
A model with a `primary_key` can have its access defined on SurrealDB 3.x. No new public API.
|
|
43
|
+
|
|
44
|
+
### Fixed
|
|
45
|
+
|
|
46
|
+
- **`access_ddl()` and `define_access()` work for a model with a `primary_key` on SurrealDB 3.x** (#338).
|
|
47
|
+
The SIGNUP clause built the record id with `type::thing('<table>', $<key>)`, which 3.x refuses at
|
|
48
|
+
`DEFINE`, so `define_access()` failed there; `type::record(table, key)` is no replacement, since 2.x
|
|
49
|
+
reads it as a type check that fails every signup. SIGNUP now sets the id from the bound key,
|
|
50
|
+
`CREATE <table> SET id = $<key>, ...`, a statement accepted by 3.x, 2.x and the embedded engine
|
|
51
|
+
that gives the record id `<table>:<key>` on all of them. `access_ddl()` stays pure, with no
|
|
52
|
+
version parameter, and a model without a `primary_key` is unchanged.
|
|
53
|
+
- **A signup leaving the `primary_key` as `None` is refused before the exchange.** `SET id = NONE`
|
|
54
|
+
would have the server mint a random record id, one no `objects().get(<key>)` addresses; the
|
|
55
|
+
`ValueError` names the key.
|
|
56
|
+
- **`parse_define_access()` reads the new form**: the `id = $<key>` item is one of `signup_fields`.
|
|
57
|
+
The older `type::thing(...)` and `type::record(...)` targets are still read.
|
|
58
|
+
|
|
59
|
+
### Notes
|
|
60
|
+
|
|
61
|
+
- **Upgrading**: re-run `define_access()` for such a model to replace the old SIGNUP clause. Accesses
|
|
62
|
+
already defined on 2.x keep working; on 2.x the old clause and the new one create the same records.
|
|
63
|
+
|
|
8
64
|
## [0.37.1] - 2026-10-24
|
|
9
65
|
|
|
10
66
|
Follow-ups to the review of v0.36.3 (#327): a `Literal[None]` member of a vector field's union
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.37.
|
|
3
|
+
Version: 0.37.4
|
|
4
4
|
Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
|
|
5
5
|
Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
|
|
6
6
|
Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
|
|
@@ -1297,7 +1297,9 @@ a concurrent server).
|
|
|
1297
1297
|
|
|
1298
1298
|
The model must declare either an `id` field or a `primary_key`, as every ORM model must. Prefer
|
|
1299
1299
|
`id` here so the server mints the record id during SIGNUP; configure `primary_key` when identity
|
|
1300
|
-
_is_ a column, and the SIGNUP clause
|
|
1300
|
+
_is_ a column, and the SIGNUP clause sets the record id from it to match
|
|
1301
|
+
(`CREATE User SET id = $email, email = $email, …`): the same statement on SurrealDB 2.x, 3.x and the embedded engine,
|
|
1302
|
+
and the record id is the key on all of them.
|
|
1301
1303
|
|
|
1302
1304
|
#### Configuration
|
|
1303
1305
|
|
|
@@ -4505,10 +4507,11 @@ reads, stores, logs or writes them.
|
|
|
4505
4507
|
for a field without `TYPE`, as in the full ORM.
|
|
4506
4508
|
- **Accesses are database-level**: they are in `schema.accesses`, and `TableState` has no `access` attribute; find
|
|
4507
4509
|
a table's with `[a for a in schema.accesses.values() if a.table == "user"]`. `table`, `signup_fields` and
|
|
4508
|
-
`signin_where` are read from `SIGNUP (CREATE <table> SET …)` (
|
|
4509
|
-
`CREATE type::
|
|
4510
|
-
`SIGNIN (SELECT … FROM <table> WHERE …)`. The full ORM reads the
|
|
4511
|
-
empty, with field names unescaped; durations are kept as rendered,
|
|
4510
|
+
`signin_where` are read from `SIGNUP (CREATE <table> SET …)` (the form `define_access()` uses, whose
|
|
4511
|
+
`id = $<key>` for a `primary_key` is one of the `signup_fields`; also `CREATE type::thing('<table>', …) SET …` and
|
|
4512
|
+
`CREATE type::record('<table>', …) SET …`) and `SIGNIN (SELECT … FROM <table> WHERE …)`. The full ORM reads the
|
|
4513
|
+
first form only, and another shape leaves them empty, with field names unescaped; durations are kept as rendered,
|
|
4514
|
+
`'NONE'` included.
|
|
4512
4515
|
- **`encrypted` is not provided**: the lite has no `Encrypted` type, so a hashing `VALUE`
|
|
4513
4516
|
(`crypto::argon2::generate($value)`) stays in `FieldState.value` and the field is generated as a writable field.
|
|
4514
4517
|
- **APIs and the GraphQL config are not typed**: their definitions are in `SchemaState.other["apis"]` and
|
|
@@ -6475,6 +6478,10 @@ print(await annotated.count(), await annotated.exists())
|
|
|
6475
6478
|
that keeps a tenth of the table. Pass `dist=` for an exact scan.
|
|
6476
6479
|
- Distances are computed in the index's `vector_type` (`F32` by default: single precision), so they can differ from
|
|
6477
6480
|
Python's in the last digits; `dist=` computes in double precision.
|
|
6481
|
+
- SurrealDB 2.x's and the embedded engine's exact scan (`dist=`) picks among records at an equal distance at the
|
|
6482
|
+
`limit`-th place in no fixed order, so there the ORM ranks it by distance, then id: identical calls return the same
|
|
6483
|
+
records in the same order, the tied ones by id, and a page, a `Subquery` and the bulk writes take the same records.
|
|
6484
|
+
SurrealDB 3.x's own scan gives one answer.
|
|
6478
6485
|
- `COSINE` has no distance for a zero vector: `similar_to()` refuses a zero query vector when the distance is
|
|
6479
6486
|
`COSINE` — `dist="cosine"`, or the model's `COSINE` index on the field —, and a record holding a zero vector gets a
|
|
6480
6487
|
`nan` distance.
|
|
@@ -6647,10 +6654,11 @@ except SurrealDbError as error:
|
|
|
6647
6654
|
more than half the documents scores `0.0` on SurrealDB 3.x and below zero on 2.x and the embedded engine
|
|
6648
6655
|
([2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x)), so the full-text list, and the fused ranking with it, can
|
|
6649
6656
|
differ between lines.
|
|
6650
|
-
- **An exact scan (`dist=`)
|
|
6651
|
-
|
|
6652
|
-
|
|
6653
|
-
|
|
6657
|
+
- **An exact scan (`dist=`) returns the same vector list on every call**, on every line. SurrealDB 2.x's and the
|
|
6658
|
+
embedded engine's own scan picks among records at an equal distance at the `vector_limit`-th place in no fixed order,
|
|
6659
|
+
so there the ORM ranks it by distance, then id, as for `similar_to()` (section 37): the tied records are kept by id,
|
|
6660
|
+
and a page read with `offset()` and `limit()` never skips nor repeats one. The HNSW index (no `dist=`) returns the
|
|
6661
|
+
same list on every call too.
|
|
6654
6662
|
- Each search needs its index. Without a full-text index on `text_field`, SurrealDB 3.3, 2.x and the embedded engine
|
|
6655
6663
|
refuse the search, and `hybrid_search()` raises `SurrealDbError` naming the field, as above; SurrealDB 3.1 and 3.2
|
|
6656
6664
|
match nothing, so the vector list alone is fused.
|
|
@@ -6693,8 +6701,7 @@ except ValueError as error:
|
|
|
6693
6701
|
2.x and the embedded engine; the full ORM calls `search::rrf()` with arguments SurrealDB 3.3 refuses, and runs on
|
|
6694
6702
|
3.x only.
|
|
6695
6703
|
- **Equal fused scores have a fixed order** (the vector list's first), so the same two lists always give the same
|
|
6696
|
-
page
|
|
6697
|
-
two identical calls, as above.
|
|
6704
|
+
page, and an exact scan (`dist=`) gives the same vector list on every line, as above.
|
|
6698
6705
|
- **Checked before any request**: both fields, the vector, `vector_limit` and `text_limit` (1 to 10 000), `rrf_k`
|
|
6699
6706
|
(0 to 10 000), `ef` and `dist`; the full ORM checks the field names only.
|
|
6700
6707
|
- **Reciprocal Rank Fusion only**: `search::linear()` (weights and score normalisation) is not offered yet.
|
|
@@ -6821,7 +6828,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
6821
6828
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
6822
6829
|
on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
|
|
6823
6830
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
6824
|
-
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.36.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.36.2 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.37.0 were measured on 2.7.0, 3.3.4, 3.2.6 and the embedded engine, with 3.1.5 and 3.2.6 where they differ from 3.3.4.
|
|
6831
|
+
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.36.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.36.2 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.37.0 were measured on 2.7.0, 3.3.4, 3.2.6 and the embedded engine, with 3.1.5 and 3.2.6 where they differ from 3.3.4. The row added in v0.37.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.37.4 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
|
|
6825
6832
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
6826
6833
|
|
|
6827
6834
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -6866,6 +6873,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
6866
6873
|
| Signing in as a system user while a record session is open | permissions change, `$auth` still points at the record — only `invalidate()` clears it | 3.2.x: same as 2.x. **3.3.0**: the identity is cleared and `info()` returns `None`; `invalidate()` stays the portable log-out | v0.16.0 |
|
|
6867
6874
|
| Duplicate signin identifier in the record table | signin fails (`No record was returned`) | signin succeeds, picking one record | v0.16.0 |
|
|
6868
6875
|
| Model auth (`signup`/`signin`/`authenticate`, `access_ddl`/`define_access`) | same on both lines (verified on 2.6.5) | same on both lines (verified on 3.2.4) | v0.17.0 |
|
|
6876
|
+
| Model auth with a `primary_key` (`access_ddl()`, `define_access()`) | same on both lines: SIGNUP runs `CREATE <table> SET id = $<key>, …`, so the record id is the key (verified on 2.7.0) | same on both lines (verified on 3.3.4 and 3.1.5); v0.17.0 to v0.37.1 rendered `type::thing`, which 3.x refuses, so `define_access()` failed | v0.37.2 |
|
|
6869
6877
|
| Model auth session isolation (each call on its own ephemeral connection) | same on both lines (an SDK/connection property, not a server one) | same on both lines (verified on 3.2.4) | v0.17.0 |
|
|
6870
6878
|
| Hydrated instance's password field after `signup`/`signin` | holds the stored **hash**, never the plaintext | same on both lines | v0.17.0 |
|
|
6871
6879
|
| Model config `with_refresh=True` → `define_access()` | raises `SurrealDbError` (clause does not parse; message names the 3.x requirement) | applies, and `AuthResult.tokens.refresh` is populated | v0.17.0 |
|
|
@@ -6985,7 +6993,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
6985
6993
|
| `hybrid_search()`: the fusion | the ORM fuses the two lists with `search::rrf()`'s formula, which SurrealDB 2.x does not have: the same records, scores and order for the same two lists | SurrealDB's `search::rrf()` fuses them; the ORM orders equal scores, which SurrealDB returns in no fixed order | v0.37.0 |
|
|
6986
6994
|
| `hybrid_search()` with other conditions | applied to both lists; the vector list selects the records first (a `LET`), as `similar_to()` does | applied to both lists, during each search | v0.37.0 |
|
|
6987
6995
|
| `hybrid_search()` on a field without a vector or full-text index | no vector index: the vector list is empty, so the full-text ranking alone is fused; no full-text index: `SurrealDbError` naming the field | the same; 3.1 and 3.2 put the first `vector_limit` records by id in the vector list, with no distance, and match no record for the text | v0.37.0 |
|
|
6988
|
-
| An exact scan (`similar_to(dist=…)`, `hybrid_search(dist=…)`) with records at an equal distance at the last place | the
|
|
6996
|
+
| An exact scan (`similar_to(dist=…)`, `hybrid_search(dist=…)`) with records at an equal distance at the last place | the ORM ranks the scan by distance, then id: the same records on every call, the tied ones by id (2.x's own scan picks among them in no fixed order) | the same records on every call, as with the HNSW index | v0.37.4 |
|
|
6989
6997
|
| Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0 | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips) | 3.3.0 identical to 3.2.4, except the system-user signin row | v0.19.1 |
|
|
6990
6998
|
|
|
6991
6999
|
> **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
|
|
@@ -7026,7 +7034,7 @@ Capabilities not listed behave as on a 2.x server.
|
|
|
7026
7034
|
| `define_indexes(tx=)` in a block that writes to the model's table | an ORM write before it: refused all the same, although this engine indexes its records; a write after it is committed and indexed | refused (left out of the index); on 2.x a write after it, to a table holding records, fails the commit | v0.35.3 |
|
|
7027
7035
|
| Vector search (v0.36.0) | as on a 2.x server: `MTREE` accepted, at most `ef` records returned (the ORM raises `ef` to `limit`), other conditions selected first in a `LET` (search annotations refused), writes made by the ids of the nearest, fewer records with a selective condition; an index without `TYPE` is `F64` (servers: `F32`), so the ORM always writes `TYPE` | 3.x refuses `MTREE`, applies the conditions during the index search and keeps search annotations | v0.36.0 |
|
|
7028
7036
|
| `remove_index(tx=)` then `define_indexes(tx=)` in one block | the index is defined again after its removal and committed, on a table holding records too | the same on 3.x; on 2.x, on a table holding records, the commit fails with a retryable conflict | v0.36.2 |
|
|
7029
|
-
| Hybrid search (v0.37.0) | as on a 2.x server: the ORM fuses the two lists with `search::rrf()`'s formula, which the engine does not have, and the vector list selects the other conditions first (a `LET`); an exact scan (`dist=`)
|
|
7037
|
+
| Hybrid search (v0.37.0) | as on a 2.x server: the ORM fuses the two lists with `search::rrf()`'s formula, which the engine does not have, and the vector list selects the other conditions first (a `LET`); an exact scan (`dist=`) keeps the records at an equal distance at the `vector_limit`-th place by id (since v0.37.4), as `similar_to(dist=…)` does | 3.x fuses with `search::rrf()`, each list applying the conditions; its exact scan returns the same list | v0.37.0 |
|
|
7030
7038
|
| Everything else | CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields, upsert/patch, server values, computed fields, stored functions, signals: the same as on a 2.x server | unchanged | v0.25.0 |
|
|
7031
7039
|
|
|
7032
7040
|
---
|
|
@@ -1246,7 +1246,9 @@ a concurrent server).
|
|
|
1246
1246
|
|
|
1247
1247
|
The model must declare either an `id` field or a `primary_key`, as every ORM model must. Prefer
|
|
1248
1248
|
`id` here so the server mints the record id during SIGNUP; configure `primary_key` when identity
|
|
1249
|
-
_is_ a column, and the SIGNUP clause
|
|
1249
|
+
_is_ a column, and the SIGNUP clause sets the record id from it to match
|
|
1250
|
+
(`CREATE User SET id = $email, email = $email, …`): the same statement on SurrealDB 2.x, 3.x and the embedded engine,
|
|
1251
|
+
and the record id is the key on all of them.
|
|
1250
1252
|
|
|
1251
1253
|
#### Configuration
|
|
1252
1254
|
|
|
@@ -4454,10 +4456,11 @@ reads, stores, logs or writes them.
|
|
|
4454
4456
|
for a field without `TYPE`, as in the full ORM.
|
|
4455
4457
|
- **Accesses are database-level**: they are in `schema.accesses`, and `TableState` has no `access` attribute; find
|
|
4456
4458
|
a table's with `[a for a in schema.accesses.values() if a.table == "user"]`. `table`, `signup_fields` and
|
|
4457
|
-
`signin_where` are read from `SIGNUP (CREATE <table> SET …)` (
|
|
4458
|
-
`CREATE type::
|
|
4459
|
-
`SIGNIN (SELECT … FROM <table> WHERE …)`. The full ORM reads the
|
|
4460
|
-
empty, with field names unescaped; durations are kept as rendered,
|
|
4459
|
+
`signin_where` are read from `SIGNUP (CREATE <table> SET …)` (the form `define_access()` uses, whose
|
|
4460
|
+
`id = $<key>` for a `primary_key` is one of the `signup_fields`; also `CREATE type::thing('<table>', …) SET …` and
|
|
4461
|
+
`CREATE type::record('<table>', …) SET …`) and `SIGNIN (SELECT … FROM <table> WHERE …)`. The full ORM reads the
|
|
4462
|
+
first form only, and another shape leaves them empty, with field names unescaped; durations are kept as rendered,
|
|
4463
|
+
`'NONE'` included.
|
|
4461
4464
|
- **`encrypted` is not provided**: the lite has no `Encrypted` type, so a hashing `VALUE`
|
|
4462
4465
|
(`crypto::argon2::generate($value)`) stays in `FieldState.value` and the field is generated as a writable field.
|
|
4463
4466
|
- **APIs and the GraphQL config are not typed**: their definitions are in `SchemaState.other["apis"]` and
|
|
@@ -6424,6 +6427,10 @@ print(await annotated.count(), await annotated.exists())
|
|
|
6424
6427
|
that keeps a tenth of the table. Pass `dist=` for an exact scan.
|
|
6425
6428
|
- Distances are computed in the index's `vector_type` (`F32` by default: single precision), so they can differ from
|
|
6426
6429
|
Python's in the last digits; `dist=` computes in double precision.
|
|
6430
|
+
- SurrealDB 2.x's and the embedded engine's exact scan (`dist=`) picks among records at an equal distance at the
|
|
6431
|
+
`limit`-th place in no fixed order, so there the ORM ranks it by distance, then id: identical calls return the same
|
|
6432
|
+
records in the same order, the tied ones by id, and a page, a `Subquery` and the bulk writes take the same records.
|
|
6433
|
+
SurrealDB 3.x's own scan gives one answer.
|
|
6427
6434
|
- `COSINE` has no distance for a zero vector: `similar_to()` refuses a zero query vector when the distance is
|
|
6428
6435
|
`COSINE` — `dist="cosine"`, or the model's `COSINE` index on the field —, and a record holding a zero vector gets a
|
|
6429
6436
|
`nan` distance.
|
|
@@ -6596,10 +6603,11 @@ except SurrealDbError as error:
|
|
|
6596
6603
|
more than half the documents scores `0.0` on SurrealDB 3.x and below zero on 2.x and the embedded engine
|
|
6597
6604
|
([2.x/3.x table](#orm-behaviour-surrealdb-2x-vs-3x)), so the full-text list, and the fused ranking with it, can
|
|
6598
6605
|
differ between lines.
|
|
6599
|
-
- **An exact scan (`dist=`)
|
|
6600
|
-
|
|
6601
|
-
|
|
6602
|
-
|
|
6606
|
+
- **An exact scan (`dist=`) returns the same vector list on every call**, on every line. SurrealDB 2.x's and the
|
|
6607
|
+
embedded engine's own scan picks among records at an equal distance at the `vector_limit`-th place in no fixed order,
|
|
6608
|
+
so there the ORM ranks it by distance, then id, as for `similar_to()` (section 37): the tied records are kept by id,
|
|
6609
|
+
and a page read with `offset()` and `limit()` never skips nor repeats one. The HNSW index (no `dist=`) returns the
|
|
6610
|
+
same list on every call too.
|
|
6603
6611
|
- Each search needs its index. Without a full-text index on `text_field`, SurrealDB 3.3, 2.x and the embedded engine
|
|
6604
6612
|
refuse the search, and `hybrid_search()` raises `SurrealDbError` naming the field, as above; SurrealDB 3.1 and 3.2
|
|
6605
6613
|
match nothing, so the vector list alone is fused.
|
|
@@ -6642,8 +6650,7 @@ except ValueError as error:
|
|
|
6642
6650
|
2.x and the embedded engine; the full ORM calls `search::rrf()` with arguments SurrealDB 3.3 refuses, and runs on
|
|
6643
6651
|
3.x only.
|
|
6644
6652
|
- **Equal fused scores have a fixed order** (the vector list's first), so the same two lists always give the same
|
|
6645
|
-
page
|
|
6646
|
-
two identical calls, as above.
|
|
6653
|
+
page, and an exact scan (`dist=`) gives the same vector list on every line, as above.
|
|
6647
6654
|
- **Checked before any request**: both fields, the vector, `vector_limit` and `text_limit` (1 to 10 000), `rrf_k`
|
|
6648
6655
|
(0 to 10 000), `ef` and `dist`; the full ORM checks the field names only.
|
|
6649
6656
|
- **Reciprocal Rank Fusion only**: `search::linear()` (weights and score normalisation) is not offered yet.
|
|
@@ -6770,7 +6777,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
6770
6777
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
6771
6778
|
on 2.7.0. The 3.x column was measured on 3.2.4 and holds on 3.3.0, except where a row says
|
|
6772
6779
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
6773
|
-
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.
|
|
6780
|
+
Rows added in v0.20.0 were measured directly on 2.7.0 and 3.3.0; rows added in v0.21.0 on 2.7.0 and 3.3.2, re-verified on 3.3.3, with 3.1.5 where it differs; rows added in v0.22.0 on 2.7.0 and 3.3.3, with 3.1.5 where it differs; rows added in v0.23.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.24.0 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.26.0 on 2.7.0 and 3.3.4, in memory and on versioned storage, identical on 3.1.5; rows added in v0.27.0 on 2.7.0 and 3.3.4, with 3.1.5 where it differs; rows added in v0.28.0 on 2.7.0 and 3.3.4, identical on 3.1.5; the rows added in v0.28.1 on 2.7.0 and 3.3.4, identical on 3.1.5; rows added in v0.29.0 on 2.7.0 and 3.3.4 in one process, identical on 3.1.5. The row added in v0.29.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.30.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.30.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. The row added in v0.30.7 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5: its parser refuses a statement that nests six objects, and `update()` nests at most four. Rows added in v0.31.0 were measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.31.1 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. Rows added in v0.32.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 but accepts raw writes to a view. Rows added in v0.33.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4. Rows added in v0.34.0 were measured on 2.7.0, 3.3.4 and the embedded engine; 3.1.5 behaves as 3.3.4 except that it refuses a Python `set` written to a `set` field, and an object item of an optional untyped `list`. Rows added in v0.35.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.35.2 was measured on 2.7.0 and 3.3.4, identical on 3.1.5. The row added in v0.35.3 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.36.0 were measured on 2.7.0, 3.3.4 and the embedded engine, with 3.1.5 where it differs. The row added in v0.36.2 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5. Rows added in v0.37.0 were measured on 2.7.0, 3.3.4, 3.2.6 and the embedded engine, with 3.1.5 and 3.2.6 where they differ from 3.3.4. The row added in v0.37.2 was measured on 2.7.0, 3.3.4 and the embedded engine, identical on 3.1.5. The row added in v0.37.4 was measured on 2.7.0 and 3.3.4, over WebSocket and HTTP, and on the embedded engine, identical on 3.1.5.
|
|
6774
6781
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
6775
6782
|
|
|
6776
6783
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -6815,6 +6822,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
6815
6822
|
| Signing in as a system user while a record session is open | permissions change, `$auth` still points at the record — only `invalidate()` clears it | 3.2.x: same as 2.x. **3.3.0**: the identity is cleared and `info()` returns `None`; `invalidate()` stays the portable log-out | v0.16.0 |
|
|
6816
6823
|
| Duplicate signin identifier in the record table | signin fails (`No record was returned`) | signin succeeds, picking one record | v0.16.0 |
|
|
6817
6824
|
| Model auth (`signup`/`signin`/`authenticate`, `access_ddl`/`define_access`) | same on both lines (verified on 2.6.5) | same on both lines (verified on 3.2.4) | v0.17.0 |
|
|
6825
|
+
| Model auth with a `primary_key` (`access_ddl()`, `define_access()`) | same on both lines: SIGNUP runs `CREATE <table> SET id = $<key>, …`, so the record id is the key (verified on 2.7.0) | same on both lines (verified on 3.3.4 and 3.1.5); v0.17.0 to v0.37.1 rendered `type::thing`, which 3.x refuses, so `define_access()` failed | v0.37.2 |
|
|
6818
6826
|
| Model auth session isolation (each call on its own ephemeral connection) | same on both lines (an SDK/connection property, not a server one) | same on both lines (verified on 3.2.4) | v0.17.0 |
|
|
6819
6827
|
| Hydrated instance's password field after `signup`/`signin` | holds the stored **hash**, never the plaintext | same on both lines | v0.17.0 |
|
|
6820
6828
|
| Model config `with_refresh=True` → `define_access()` | raises `SurrealDbError` (clause does not parse; message names the 3.x requirement) | applies, and `AuthResult.tokens.refresh` is populated | v0.17.0 |
|
|
@@ -6934,7 +6942,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
6934
6942
|
| `hybrid_search()`: the fusion | the ORM fuses the two lists with `search::rrf()`'s formula, which SurrealDB 2.x does not have: the same records, scores and order for the same two lists | SurrealDB's `search::rrf()` fuses them; the ORM orders equal scores, which SurrealDB returns in no fixed order | v0.37.0 |
|
|
6935
6943
|
| `hybrid_search()` with other conditions | applied to both lists; the vector list selects the records first (a `LET`), as `similar_to()` does | applied to both lists, during each search | v0.37.0 |
|
|
6936
6944
|
| `hybrid_search()` on a field without a vector or full-text index | no vector index: the vector list is empty, so the full-text ranking alone is fused; no full-text index: `SurrealDbError` naming the field | the same; 3.1 and 3.2 put the first `vector_limit` records by id in the vector list, with no distance, and match no record for the text | v0.37.0 |
|
|
6937
|
-
| An exact scan (`similar_to(dist=…)`, `hybrid_search(dist=…)`) with records at an equal distance at the last place | the
|
|
6945
|
+
| An exact scan (`similar_to(dist=…)`, `hybrid_search(dist=…)`) with records at an equal distance at the last place | the ORM ranks the scan by distance, then id: the same records on every call, the tied ones by id (2.x's own scan picks among them in no fixed order) | the same records on every call, as with the HNSW index | v0.37.4 |
|
|
6938
6946
|
| Full suite and every divergence in this table, re-run on SurrealDB 2.7.0 and 3.3.0 | 2.7.0 identical to 2.6.5 (same passes, same 3.x-only skips) | 3.3.0 identical to 3.2.4, except the system-user signin row | v0.19.1 |
|
|
6939
6947
|
|
|
6940
6948
|
> **Note on record IDs**: A record loaded from the database has its `id` field set to a native `surrealdb.RecordID` object, not a plain string. Use `model.get_raw_id()` to obtain the bare identifier string (e.g. `"alice"`), or compare directly with `model.id == RecordID("User", "alice")`. In-memory instances you construct yourself retain whatever value you assign.
|
|
@@ -6975,7 +6983,7 @@ Capabilities not listed behave as on a 2.x server.
|
|
|
6975
6983
|
| `define_indexes(tx=)` in a block that writes to the model's table | an ORM write before it: refused all the same, although this engine indexes its records; a write after it is committed and indexed | refused (left out of the index); on 2.x a write after it, to a table holding records, fails the commit | v0.35.3 |
|
|
6976
6984
|
| Vector search (v0.36.0) | as on a 2.x server: `MTREE` accepted, at most `ef` records returned (the ORM raises `ef` to `limit`), other conditions selected first in a `LET` (search annotations refused), writes made by the ids of the nearest, fewer records with a selective condition; an index without `TYPE` is `F64` (servers: `F32`), so the ORM always writes `TYPE` | 3.x refuses `MTREE`, applies the conditions during the index search and keeps search annotations | v0.36.0 |
|
|
6977
6985
|
| `remove_index(tx=)` then `define_indexes(tx=)` in one block | the index is defined again after its removal and committed, on a table holding records too | the same on 3.x; on 2.x, on a table holding records, the commit fails with a retryable conflict | v0.36.2 |
|
|
6978
|
-
| 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=`)
|
|
6986
|
+
| Hybrid search (v0.37.0) | as on a 2.x server: the ORM fuses the two lists with `search::rrf()`'s formula, which the engine does not have, and the vector list selects the other conditions first (a `LET`); an exact scan (`dist=`) keeps the records at an equal distance at the `vector_limit`-th place by id (since v0.37.4), as `similar_to(dist=…)` does | 3.x fuses with `search::rrf()`, each list applying the conditions; its exact scan returns the same list | v0.37.0 |
|
|
6979
6987
|
| Everything else | CRUD, QuerySet, aggregations, relations, typed edges, rich and geo fields, upsert/patch, server values, computed fields, stored functions, signals: the same as on a 2.x server | unchanged | v0.25.0 |
|
|
6980
6988
|
|
|
6981
6989
|
---
|
|
@@ -2491,8 +2491,10 @@ def parse_define_access(text: str) -> AccessState:
|
|
|
2491
2491
|
``BEARER``) is read positionally, then the clauses ``SIGNUP``, ``SIGNIN``, ``WITH REFRESH``, ``WITH JWT``,
|
|
2492
2492
|
``ALGORITHM``, ``URL``, ``WITH ISSUER``, ``AUTHENTICATE``, ``DURATION`` and ``COMMENT``. ``signup`` and ``signin``
|
|
2493
2493
|
keep their groups, parentheses included. ``table`` and ``signup_fields`` come from a SIGNUP ``CREATE <target> SET
|
|
2494
|
-
<field> = <expr>, …`` whose target is a table name
|
|
2495
|
-
``
|
|
2494
|
+
<field> = <expr>, …`` whose target is a table name — ``define_access()``'s form, whose ``id = $<key>`` item for a
|
|
2495
|
+
``primary_key`` is one of the ``signup_fields`` — or a guarded ``type::thing('<table>', …)`` /
|
|
2496
|
+
``type::record('<table>', …)`` call (the ORM's ``primary_key`` form before #338, or one written by hand), every
|
|
2497
|
+
``SET`` item read; ``signin_where`` from a SIGNIN ``SELECT … FROM <table> WHERE <expr>``; any
|
|
2496
2498
|
other shape gives ``""`` and ``{}``, with no error (the full ORM's attributes, made exact). Durations are kept as
|
|
2497
2499
|
rendered (``"4w2d"``, ``"NONE"``), ``None`` for one the ``DURATION`` clause does not name. The servers render the
|
|
2498
2500
|
keys ``[REDACTED]``. Raises ``DefineParseError``.
|
|
@@ -170,7 +170,8 @@ class AuthenticatedUserMixin:
|
|
|
170
170
|
a ``primary_key`` — otherwise the instance these methods return cannot be constructed at
|
|
171
171
|
all. Prefer the ``id`` field here: SIGNUP lets the server mint the record id, and this is
|
|
172
172
|
what receives it. Configure ``primary_key`` instead when the identity *is* a column (say
|
|
173
|
-
the e-mail address), and the SIGNUP clause will
|
|
173
|
+
the e-mail address), and the SIGNUP clause will set the record id from it (``id = $email``)
|
|
174
|
+
accordingly — the same statement on SurrealDB 3.x, 2.x and the embedded engine.
|
|
174
175
|
"""
|
|
175
176
|
|
|
176
177
|
# ------------------------------------------------------------------
|
|
@@ -303,11 +304,12 @@ class AuthenticatedUserMixin:
|
|
|
303
304
|
def _signup_primary_key(cls) -> str | None:
|
|
304
305
|
"""The primary key SIGNUP builds the record id from, or ``None`` for a server id.
|
|
305
306
|
|
|
306
|
-
The key has to be *bindable*: SIGNUP renders ``
|
|
307
|
-
is not among the fields signup sends would evaluate to ``
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
bound. Caught here, at render time,
|
|
307
|
+
The key has to be *bindable*: SIGNUP renders ``CREATE <table> SET id = $pk, …``, so a key
|
|
308
|
+
that is not among the fields signup sends would evaluate to ``id = NONE`` and have the
|
|
309
|
+
server mint a random record id — one no ``objects().get(<key>)`` addresses.
|
|
310
|
+
``primary_key="id"`` is the trap — ``id`` is deliberately excluded from the signup
|
|
311
|
+
payload (the server mints it), so it can never be bound. Caught here, at render time,
|
|
312
|
+
rather than on every signup.
|
|
311
313
|
"""
|
|
312
314
|
primary_key = cls.get_index_primary_key() # type: ignore[attr-defined]
|
|
313
315
|
if primary_key is None:
|
|
@@ -385,6 +387,12 @@ class AuthenticatedUserMixin:
|
|
|
385
387
|
``define_table()`` writes ``TYPE NORMAL``, so calling both changes the type each time.
|
|
386
388
|
Declaring ``table_type`` gives both the same type.
|
|
387
389
|
|
|
390
|
+
A model with a ``primary_key`` has SIGNUP create the record whose id is the key:
|
|
391
|
+
``CREATE <table> SET id = $<key>, …``, the assignment first (#338). The statements are
|
|
392
|
+
the same for SurrealDB 3.x, 2.x and the embedded engine — a function building the id
|
|
393
|
+
would not be: 3.x refuses ``type::thing`` at ``DEFINE``, and 2.x reads
|
|
394
|
+
``type::record(table, key)`` as a type check that fails every signup.
|
|
395
|
+
|
|
388
396
|
Args:
|
|
389
397
|
overwrite: ``True`` (default) emits ``OVERWRITE`` — the model is the source of
|
|
390
398
|
truth, so re-running converges the database onto the code. ``False`` emits
|
|
@@ -451,9 +459,13 @@ class AuthenticatedUserMixin:
|
|
|
451
459
|
|
|
452
460
|
# The record id follows the model's primary key, because the rest of the ORM does: a
|
|
453
461
|
# random id here would leave User.objects().get(email=…) addressing a record the
|
|
454
|
-
# signup never wrote.
|
|
462
|
+
# signup never wrote. It is assigned from the bound key (`id = $<key>`, first item of
|
|
463
|
+
# the SET), not built with a function: SurrealDB 3.x refuses `type::thing` at DEFINE,
|
|
464
|
+
# and 2.x reads `type::record(table, key)` as a type check that fails every signup
|
|
465
|
+
# (#338), while the assignment gives the record id `<table>:<key>` on both lines and on
|
|
466
|
+
# the embedded engine.
|
|
455
467
|
primary_key = cls._signup_primary_key()
|
|
456
|
-
|
|
468
|
+
items = [] if primary_key is None else [f"id = ${primary_key}"]
|
|
457
469
|
|
|
458
470
|
# Column on the left of each assignment, bound variable on the right: the variable
|
|
459
471
|
# keeps the Python name the caller passes as a keyword argument, while the column is
|
|
@@ -462,16 +474,16 @@ class AuthenticatedUserMixin:
|
|
|
462
474
|
# `password_hash` — signin would then keep validating against a hash no ORM write ever
|
|
463
475
|
# updates.
|
|
464
476
|
to_column = cls.to_db_field # type: ignore[attr-defined]
|
|
465
|
-
|
|
477
|
+
items += [
|
|
466
478
|
f"{to_column(name)} = crypto::{algorithm}::generate(${name})"
|
|
467
479
|
if name == password
|
|
468
480
|
else f"{to_column(name)} = ${name}"
|
|
469
481
|
for name in cls._signup_fields()
|
|
470
|
-
|
|
482
|
+
]
|
|
471
483
|
|
|
472
484
|
parts = [
|
|
473
485
|
f"DEFINE ACCESS {clause} {access} ON DATABASE TYPE RECORD",
|
|
474
|
-
f"SIGNUP ( CREATE {
|
|
486
|
+
f"SIGNUP ( CREATE {table} SET {', '.join(items)} )",
|
|
475
487
|
f"SIGNIN ( SELECT * FROM {table} WHERE {to_column(identifier)} = ${identifier} "
|
|
476
488
|
f"AND crypto::{algorithm}::compare({to_column(password)}, ${password}) )",
|
|
477
489
|
]
|
|
@@ -654,6 +666,14 @@ class AuthenticatedUserMixin:
|
|
|
654
666
|
f"They have no default, so the instance could not be built from the record "
|
|
655
667
|
f"the server would create."
|
|
656
668
|
)
|
|
669
|
+
# The record id SIGNUP creates is the primary key's value (`SET id = $<key>`, #338): a
|
|
670
|
+
# `None` there has the server mint a random id, one no objects().get(<key>) addresses —
|
|
671
|
+
# refused before the exchange as well.
|
|
672
|
+
primary_key = cls.get_index_primary_key() # type: ignore[attr-defined]
|
|
673
|
+
if primary_key in payload and payload[primary_key] is None:
|
|
674
|
+
raise ValueError(
|
|
675
|
+
f"{cls.__name__}.{action}() requires {primary_key}=: it is the primary key, which SIGNUP makes the record id."
|
|
676
|
+
)
|
|
657
677
|
return payload
|
|
658
678
|
|
|
659
679
|
@classmethod
|
|
@@ -964,7 +984,8 @@ class AuthenticatedUserMixin:
|
|
|
964
984
|
would strip of its password hash. :meth:`signin`, :meth:`authenticate`,
|
|
965
985
|
:meth:`refresh`, ``update()`` and ``upsert()`` refuse such a model the same way
|
|
966
986
|
(#310), whoever wrote the record.
|
|
967
|
-
ValueError: for an unknown field
|
|
987
|
+
ValueError: for an unknown field, a missing required one, or a ``primary_key`` left
|
|
988
|
+
``None`` (it is the record id SIGNUP creates) — before any request.
|
|
968
989
|
SurrealDbAuthenticationError: if the server refuses the signup, or returns no
|
|
969
990
|
record for the new session (the message says how to grant the permission).
|
|
970
991
|
SurrealDbError: on the embedded engine without ``bind=True``.
|
|
@@ -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.
|
|
@@ -279,8 +279,9 @@ class AccessState:
|
|
|
279
279
|
``signup_fields``, ``signin_where``, ``duration_token``, ``duration_session``, ``access_type``,
|
|
280
280
|
``duration_grant``. Lite additions, keyword-only: ``signup``, ``signin``, ``with_refresh``, ``comment``, ``raw``.
|
|
281
281
|
|
|
282
|
-
``table`` and ``signup_fields`` come from a ``SIGNUP (CREATE <table> SET <field> = <expr>, …)
|
|
283
|
-
|
|
282
|
+
``table`` and ``signup_fields`` come from a ``SIGNUP (CREATE <table> SET <field> = <expr>, …)`` — every item,
|
|
283
|
+
the ``id = $<key>`` of a model with a ``primary_key`` included —, ``signin_where`` from a ``SIGNIN (SELECT … FROM
|
|
284
|
+
<table> WHERE <expr>)`` (``""``/empty otherwise). Durations are kept as rendered
|
|
284
285
|
(``"15m"``, ``"NONE"``). The keys of a ``raw`` statement are already ``[REDACTED]`` by the server; ``raw``,
|
|
285
286
|
``signup``, ``signin`` and ``signin_where`` are kept out of ``repr`` all the same, and ``signup_fields`` shows its
|
|
286
287
|
keys only.
|
|
@@ -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).
|
|
@@ -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.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/connection_config.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/connection_manager.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
|
{surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/testing/__init__.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/testing/database.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.37.1 → surreal_orm_lite-0.37.4}/src/surreal_orm_lite/testing/fixtures.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|