surreal-orm-lite 0.29.0__tar.gz → 0.29.3__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.29.0 → surreal_orm_lite-0.29.3}/CHANGELOG.md +102 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/PKG-INFO +82 -14
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/README.md +81 -13
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/pyproject.toml +1 -1
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/constants.py +15 -6
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/query_set.py +227 -86
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/subquery.py +2 -6
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/utils.py +96 -8
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/.gitignore +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/LICENSE +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/Makefile +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,108 @@ 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.29.3] - 2026-10-18
|
|
9
|
+
|
|
10
|
+
`get_or_create()` and `update_or_create()` bind the queryset's `variables()` in their lookup, as
|
|
11
|
+
`filter()` does. No new public API.
|
|
12
|
+
|
|
13
|
+
### Fixed
|
|
14
|
+
|
|
15
|
+
- **`get_or_create()` and `update_or_create()` bind `variables()` in their lookup** (#252). The
|
|
16
|
+
lookup ran without the queryset's `variables()`, so a `Var` criterion read `NONE` there:
|
|
17
|
+
`variables(n=10).get_or_create(size__gte=Var("n"), …)` compared `size` with `NONE` and could
|
|
18
|
+
match a record the caller did not mean, which `update_or_create()` then updated, and
|
|
19
|
+
`variables(t="mine").get_or_create(title=Var("t"))` did not find the existing record. The lookup
|
|
20
|
+
now binds the queryset's `variables()`, merged with those of its subquery criteria as `filter()`
|
|
21
|
+
merges them (a subquery that binds one of these names to another value raises `ValueError`), on
|
|
22
|
+
SurrealDB 2.x, 3.x and the embedded engine.
|
|
23
|
+
- **An `exact` `Var` criterion naming a variable of `variables()` is written as that variable's
|
|
24
|
+
value on create** (#252), so the next identical call finds the record:
|
|
25
|
+
`variables(t="mine").get_or_create(title=Var("t"))` behaves as `get_or_create(title="mine")`. On
|
|
26
|
+
the record id and on an edge's `in` and `out`, it is compared as the record id its value names,
|
|
27
|
+
as the same criterion given that value is (`variables(a="person:alice")` with
|
|
28
|
+
`get_or_create(in_=Var("a"), out=bob)` finds or relates `person:alice`); a value that names no
|
|
29
|
+
record id there raises `ValueError` before any request. A model instance given to `variables()`
|
|
30
|
+
is bound and written as its record id, as the instance given as the criterion is; an unsaved one
|
|
31
|
+
raises `ValueError` before any request. An `exact` `Var` that names a session parameter
|
|
32
|
+
(`Var("auth")`) or no variable of `variables()` still raises `SurrealDbError` on create.
|
|
33
|
+
|
|
34
|
+
```python
|
|
35
|
+
from surreal_orm_lite import Var
|
|
36
|
+
|
|
37
|
+
qs = Room.objects().variables(t="mine", n=10)
|
|
38
|
+
room, created = await qs.get_or_create(title=Var("t")) # as get_or_create(title="mine")
|
|
39
|
+
room, created = await qs.update_or_create(size__gte=Var("n"), title=Var("t"), defaults={"floor": 2})
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Changed
|
|
43
|
+
|
|
44
|
+
- **Refusals of a `"$name"` criterion in `get_or_create()` and `update_or_create()`** (#252): a
|
|
45
|
+
string criterion that is exactly `$` followed by the name of a variable of a subquery criterion's
|
|
46
|
+
`variables()` now raises `SurrealDbError` too, like one naming a variable of the queryset's
|
|
47
|
+
`variables()`. For a variable, the message names `Var('x')` as the criterion to write, under any
|
|
48
|
+
lookup but `like`/`ilike`, which take no `Var` (pass the pattern itself, or use `regex`). For a
|
|
49
|
+
session parameter, it says to pass the actual value under `exact`, and that `Var('auth')` works
|
|
50
|
+
under any other lookup but `like`/`ilike`, which take no `Var` (pass the pattern itself, or use
|
|
51
|
+
`regex`): `members__contains=Var("auth")` is looked up, never written. On the `id` column it names
|
|
52
|
+
the record id `table:⟨$name⟩` the string would be.
|
|
53
|
+
|
|
54
|
+
### Deprecated
|
|
55
|
+
|
|
56
|
+
- The `"$$"` escape of a string filter value, deprecated since v0.28.1 (#250) and listed there
|
|
57
|
+
under Changed: a string filter value starting with `$$` loses one `$` (`"$$admin"` finds
|
|
58
|
+
`"$admin"`) and emits a `DeprecationWarning`. A string filter value is always data, so write the
|
|
59
|
+
value with one `$` less. An item of an `in` list never had the escape and is unchanged.
|
|
60
|
+
|
|
61
|
+
## [0.29.2] - 2026-10-18
|
|
62
|
+
|
|
63
|
+
The text lookups `startswith`, `endswith`, `like`, `ilike`, `match` and `regex` work: each compiles
|
|
64
|
+
to a SurrealQL string function. No new public API.
|
|
65
|
+
|
|
66
|
+
### Fixed
|
|
67
|
+
|
|
68
|
+
- **Text lookups compile to SurrealQL string functions** (#251). They compiled to infix operators
|
|
69
|
+
SurrealQL does not have (`STARTSWITH`, `LIKE`, `REGEX`…), so every such filter was a parse error
|
|
70
|
+
on SurrealDB 2.x, 3.x and the embedded engine, in reads and in live queries. Each now compiles to
|
|
71
|
+
a string function guarded by the field's type, with its value bound:
|
|
72
|
+
`filter(name__startswith="A")` is `((name).is_string() AND string::starts_with(name, $_f0))`.
|
|
73
|
+
- `startswith` and `endswith`: `string::starts_with` and `string::ends_with`.
|
|
74
|
+
- `match` and `regex`: `string::matches`, the regular expression (SurrealDB's syntax, the Rust
|
|
75
|
+
`regex` crate) as given. `match` is a regex lookup, not the full-text `@@` operator: full-text
|
|
76
|
+
search is planned for v0.34.0.
|
|
77
|
+
- `like` and `ilike`: `string::matches` on the pattern translated to an anchored regular
|
|
78
|
+
expression. `%` matches any run of characters (newlines included), `_` exactly one, every other
|
|
79
|
+
character is literal; `ilike` ignores case. The whole value must match: `like="Al"` finds
|
|
80
|
+
`"Al"`, not `"Alice"`.
|
|
81
|
+
- A record whose field is missing (`NONE`), `NULL` or not a string never matches, and the query
|
|
82
|
+
does not fail on it; the negation (`~Q(name__startswith="A")`) matches it. A dotted path
|
|
83
|
+
through an array of record links or objects (`authors.name`) holds an array: it never matches
|
|
84
|
+
either.
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
await User.objects().filter(name__startswith="A").exec()
|
|
88
|
+
await User.objects().filter(email__ilike="%@EXAMPLE.com").exec() # case-insensitive
|
|
89
|
+
await User.objects().filter(name__regex=r"^\d{3}").exec()
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Changed
|
|
93
|
+
|
|
94
|
+
- **The value of a text lookup must be a `str`** (#251), otherwise `ValueError`. A string starting
|
|
95
|
+
with `$` is data, as for every lookup. `startswith`, `endswith`, `match` and `regex` also take a
|
|
96
|
+
`Var`; `like` and `ilike` raise `ValueError` for one, since their pattern is translated before it
|
|
97
|
+
is sent. These calls were parse errors before, so no call that worked changes.
|
|
98
|
+
|
|
99
|
+
### Notes
|
|
100
|
+
|
|
101
|
+
- Same behaviour on SurrealDB 2.x, 3.x and the embedded engine: the guard is written in the method
|
|
102
|
+
form `(field).is_string()`, which parses on both lines (`type::is::string` parses on 2.x only,
|
|
103
|
+
`type::is_string` on 3.x only). The path is in parentheses because SurrealDB 3.x applies
|
|
104
|
+
`authors.name.is_string()` to each element of the array such a path gives, and the array of
|
|
105
|
+
booleans let the array reach the string function, which failed the query. The README's behaviour
|
|
106
|
+
table has a row for the text lookups.
|
|
107
|
+
- `surreal_orm_lite.constants.LOOKUP_OPERATORS` (internal) no longer lists the text lookups; they
|
|
108
|
+
are in `TEXT_LOOKUP_FUNCTIONS`.
|
|
109
|
+
|
|
8
110
|
## [0.29.0] - 2026-10-18
|
|
9
111
|
|
|
10
112
|
Multiple databases: one process works with several databases at once. Named connections stand
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: surreal-orm-lite
|
|
3
|
-
Version: 0.29.
|
|
3
|
+
Version: 0.29.3
|
|
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
|
|
@@ -272,9 +272,7 @@ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads
|
|
|
272
272
|
- `in`, `not_in` (a list, or a `Range` bound as one value: see [section 24](#24-rich-field-types))
|
|
273
273
|
- `contains`, `not_contains` (`contains` on a range column tests membership)
|
|
274
274
|
- `containsall`, `containsany`
|
|
275
|
-
- `startswith`, `endswith`
|
|
276
|
-
- `like`, `ilike`
|
|
277
|
-
- `match`, `regex`
|
|
275
|
+
- `startswith`, `endswith`, `like`, `ilike`, `match`, `regex` (text: see [Text lookups](#text-lookups))
|
|
278
276
|
- `isnull`
|
|
279
277
|
- `inside`, `outside`, `intersects` (geometry values: see [section 25](#25-geospatial-fields))
|
|
280
278
|
- a subquery — `Subquery(qs)` or the queryset itself — as the value of `in`, `not_in`, `containsall`, `containsany` (all its values) or `exact`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains` (its first value): see [section 28](#28-subqueries-subquery)
|
|
@@ -282,6 +280,48 @@ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads
|
|
|
282
280
|
Filter values on rich fields must be typed: `filter(trial__gte=timedelta(days=7))`, not
|
|
283
281
|
`"7d"`. Strings are not converted (see [section 24](#24-rich-field-types)).
|
|
284
282
|
|
|
283
|
+
#### Text lookups
|
|
284
|
+
|
|
285
|
+
SurrealQL has no `LIKE` or `STARTSWITH` operator, so each text lookup compiles to a string
|
|
286
|
+
function, with its value bound:
|
|
287
|
+
|
|
288
|
+
| Lookup | Value | Compiles to |
|
|
289
|
+
| ------------ | -------------------------- | -------------------------------------------------------------------------------- |
|
|
290
|
+
| `startswith` | a prefix | `string::starts_with(field, $v)` |
|
|
291
|
+
| `endswith` | a suffix | `string::ends_with(field, $v)` |
|
|
292
|
+
| `like` | an SQL `LIKE` pattern | `string::matches(field, $v)`, the pattern translated to an anchored `(?s)` regex |
|
|
293
|
+
| `ilike` | the same, case-insensitive | the same, with `(?i)` added |
|
|
294
|
+
| `regex` | a regular expression | `string::matches(field, $v)` |
|
|
295
|
+
| `match` | a regular expression | `string::matches(field, $v)`: the same as `regex` |
|
|
296
|
+
|
|
297
|
+
```python
|
|
298
|
+
await User.objects().filter(name__startswith="A").exec()
|
|
299
|
+
await User.objects().filter(email__ilike="%@EXAMPLE.com").exec() # case-insensitive
|
|
300
|
+
await User.objects().filter(code__like="AB_-%").exec() # "AB", any one character, "-", anything
|
|
301
|
+
await User.objects().filter(name__regex=r"^\d{3}").exec() # SurrealDB's regex syntax (Rust regex)
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
- **Non-string fields.** Each condition is guarded by the field's type:
|
|
305
|
+
`filter(name__startswith="A")` is `((name).is_string() AND string::starts_with(name, $_f0))`.
|
|
306
|
+
A record whose field is missing (`NONE`), `NULL` or not a string never matches, and the
|
|
307
|
+
query does not fail on it. The negation (`~Q(name__startswith="A")`) matches it. A dotted
|
|
308
|
+
path through an array of record links or objects (`authors.name`) holds an array, so it
|
|
309
|
+
never matches either, on both lines: the parentheses make SurrealDB 3.x test that array,
|
|
310
|
+
not each of its elements.
|
|
311
|
+
- **`like` / `ilike` patterns.** `%` matches any run of characters (newlines included) and `_`
|
|
312
|
+
exactly one character. Every other character is literal, regex metacharacters included
|
|
313
|
+
(`.`, `*`, `(`, `\`, …). There is no escape character, so a pattern cannot match a literal
|
|
314
|
+
`%` or `_` alone: use `regex` for that. The whole value must match, so `like="Al"` finds
|
|
315
|
+
`"Al"` but not `"Alice"`.
|
|
316
|
+
- **`match` and `regex`.** Both take a regular expression in SurrealDB's syntax (the Rust
|
|
317
|
+
`regex` crate) and match anywhere in the value unless it is anchored (`^…$`). Prefix it
|
|
318
|
+
with `(?i)` to ignore case. Here `match` is a regex lookup, not the full SurrealDB-ORM's
|
|
319
|
+
full-text `@@` operator: full-text search is planned for v0.34.0, as a separate API.
|
|
320
|
+
- **Values.** The value must be a `str`, otherwise `ValueError`. A string starting with `$`
|
|
321
|
+
is data, as for every lookup ([String filter values and `Var()`](#string-filter-values-and-var)).
|
|
322
|
+
`startswith`, `endswith`, `match` and `regex` also take a `Var`. `like` and `ilike` do not:
|
|
323
|
+
their pattern is translated before it is sent, so `Var` raises `ValueError`.
|
|
324
|
+
|
|
285
325
|
#### Filtering on the record id
|
|
286
326
|
|
|
287
327
|
The `id` column holds a native `RecordID`, not a string, so the ORM coerces an `id` lookup
|
|
@@ -354,15 +394,39 @@ raises `ValueError`; when it names a variable of `variables()` or one of these p
|
|
|
354
394
|
message names the `Var(...)` to write.
|
|
355
395
|
|
|
356
396
|
`get_or_create()` and `update_or_create()` look up their criteria and write the `exact` ones on
|
|
357
|
-
create
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
397
|
+
create. Their lookup binds `variables()`, as `filter()` does, so a `Var` criterion reads the
|
|
398
|
+
variable there too, and an `exact` one is written as the variable's value on create: the next
|
|
399
|
+
identical call finds the record.
|
|
400
|
+
|
|
401
|
+
```python
|
|
402
|
+
qs = Room.objects().variables(t="mine", n=10)
|
|
403
|
+
room, created = await qs.get_or_create(title=Var("t")) # as get_or_create(title="mine")
|
|
404
|
+
room, created = await qs.update_or_create(size__gte=Var("n"), title=Var("t"), defaults={"floor": 2})
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
On the record id and on an edge's `in` and `out`, such a criterion is compared as the record id
|
|
408
|
+
its value names, as the same criterion given that value is: with `variables(a="person:alice")`,
|
|
409
|
+
`get_or_create(in_=Var("a"), out=bob)` finds or relates `person:alice`. A value that names no record
|
|
410
|
+
id there raises `ValueError` before any request. A model instance given to `variables()` is bound
|
|
411
|
+
and written as its record id, as the instance given as the criterion is (`variables(a=alice)`); an
|
|
412
|
+
unsaved one raises `ValueError` before any request. The `variables()` of a subquery criterion share
|
|
413
|
+
the lookup, as in `filter()`: one that binds a name of the queryset's `variables()` to another
|
|
414
|
+
value raises `ValueError`. `Var("auth")` finds the signed-in user's record
|
|
363
415
|
(`get_or_create(owner=Var("auth"))` returns it) but cannot be written: with no record to return, it
|
|
364
|
-
raises `SurrealDbError
|
|
365
|
-
|
|
416
|
+
raises `SurrealDbError`, and so does an `exact` `Var` that names no variable of `variables()`.
|
|
417
|
+
|
|
418
|
+
A string criterion is refused where it would be a trap: `update_or_create(owner="$auth", defaults=…)`
|
|
419
|
+
would find and write the record whose `owner` is the string `"$auth"`, the same record for every
|
|
420
|
+
record user, and `members__contains="$auth"` would look for the string. A criterion that is exactly
|
|
421
|
+
`$` followed by the name of one of these parameters or of a variable the lookup binds (of
|
|
422
|
+
`variables()`, the queryset's or a subquery criterion's) raises `SurrealDbError` before any request,
|
|
423
|
+
whatever its lookup. For a variable, the message names `Var("x")` as the criterion to write, under
|
|
424
|
+
any lookup but `like`/`ilike`, which take no `Var` (pass the pattern itself, or use `regex`). For a
|
|
425
|
+
parameter, it says to pass the actual value as an `exact` criterion (the record id, or the value
|
|
426
|
+
itself), and that `Var("auth")` works under any other lookup but `like`/`ilike`, which take no `Var`
|
|
427
|
+
(pass the pattern itself, or use `regex`): `members__contains=Var("auth")` is looked up, never
|
|
428
|
+
written. Any other string, such as `"$admin"`, is looked up and written as it is. On an edge's `in`
|
|
429
|
+
and `out`, such a criterion raises the `ValueError` above.
|
|
366
430
|
|
|
367
431
|
`variables()` refuses these four names with a `ValueError`: SurrealDB sets them for each session
|
|
368
432
|
and refuses a query variable of that name. To pass your own value, give it another name, or pass
|
|
@@ -697,7 +761,10 @@ async with SurrealDBConnectionManager.transaction() as tx:
|
|
|
697
761
|
|
|
698
762
|
If the lookup criteria match more than one record, both methods raise `SurrealDbError`
|
|
699
763
|
(the criteria are not unique). Non-`exact` lookups (e.g. `name__contains`) drive the lookup
|
|
700
|
-
but are not written to the record.
|
|
764
|
+
but are not written to the record. The lookup binds the queryset's `variables()`, as `filter()`
|
|
765
|
+
does: `User.objects().variables(e="bob@example.com").get_or_create(email=Var("e"))` finds the user
|
|
766
|
+
whose email is the variable's value, and writes that value on create (see
|
|
767
|
+
[String filter values and `Var()`](#string-filter-values-and-var)). Without a transaction the behaviour is identical on
|
|
701
768
|
SurrealDB 2.6.x and 3.x; under `objects(tx=)` they participate in the transaction on 3.x,
|
|
702
769
|
while a buffered 2.6.x transaction raises on the lookup (see the behaviour table).
|
|
703
770
|
|
|
@@ -4123,7 +4190,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
4123
4190
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
4124
4191
|
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
|
|
4125
4192
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
4126
|
-
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.
|
|
4193
|
+
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.
|
|
4127
4194
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
4128
4195
|
|
|
4129
4196
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -4233,6 +4300,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
4233
4300
|
| `filter(f="$x")`: a string filter value starting with `$` | same on both lines: compared with the string `"$x"`, bound like any value, in a live query too; `Var("x")` reads the variable `$x`, `Var("auth")` SurrealDB's `$auth` | the same; on an edge's `in`/`out` (record ids) such a string raises `ValueError`, on both lines; `$access`, `$session`, `$token` read like `$auth` | v0.28.1 |
|
|
4234
4301
|
| `limit(n)` or `offset(n)` above `4294967295` (`2**32 - 1`) | the server refuses the read: `Found <n> but the LIMIT clause must evaluate to a positive integer` (`START` likewise) | read; above `2**63 - 1` the ORM raises `ValueError` when `limit()` or `offset()` is called, on both lines | pre-existing (documented in v0.28.1) |
|
|
4235
4302
|
| Several connections in one process (`add_connection()`, `using()`) | each connection follows its own server: a 2.x connection's transactions are buffered, whatever the others are | each 3.x WebSocket connection gets interactive transactions, beside 2.x connections in the same process | v0.29.0 |
|
|
4303
|
+
| Text lookups (`startswith`, `endswith`, `like`, `ilike`, `match`, `regex`) | same on both lines: string functions guarded by `(field).is_string()` (`type::is::string` is 2.x-only); a `NONE`, `NULL`, non-string or array path value never matches | the same (`type::is_string` is 3.x-only; `a.b.is_string()` tests each element of an array path); until v0.29.1: operators SurrealQL lacks (`LIKE`…), a parse error on both lines | v0.29.2 |
|
|
4236
4304
|
| 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 |
|
|
4237
4305
|
|
|
4238
4306
|
> **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.
|
|
@@ -221,9 +221,7 @@ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads
|
|
|
221
221
|
- `in`, `not_in` (a list, or a `Range` bound as one value: see [section 24](#24-rich-field-types))
|
|
222
222
|
- `contains`, `not_contains` (`contains` on a range column tests membership)
|
|
223
223
|
- `containsall`, `containsany`
|
|
224
|
-
- `startswith`, `endswith`
|
|
225
|
-
- `like`, `ilike`
|
|
226
|
-
- `match`, `regex`
|
|
224
|
+
- `startswith`, `endswith`, `like`, `ilike`, `match`, `regex` (text: see [Text lookups](#text-lookups))
|
|
227
225
|
- `isnull`
|
|
228
226
|
- `inside`, `outside`, `intersects` (geometry values: see [section 25](#25-geospatial-fields))
|
|
229
227
|
- a subquery — `Subquery(qs)` or the queryset itself — as the value of `in`, `not_in`, `containsall`, `containsany` (all its values) or `exact`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains` (its first value): see [section 28](#28-subqueries-subquery)
|
|
@@ -231,6 +229,48 @@ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads
|
|
|
231
229
|
Filter values on rich fields must be typed: `filter(trial__gte=timedelta(days=7))`, not
|
|
232
230
|
`"7d"`. Strings are not converted (see [section 24](#24-rich-field-types)).
|
|
233
231
|
|
|
232
|
+
#### Text lookups
|
|
233
|
+
|
|
234
|
+
SurrealQL has no `LIKE` or `STARTSWITH` operator, so each text lookup compiles to a string
|
|
235
|
+
function, with its value bound:
|
|
236
|
+
|
|
237
|
+
| Lookup | Value | Compiles to |
|
|
238
|
+
| ------------ | -------------------------- | -------------------------------------------------------------------------------- |
|
|
239
|
+
| `startswith` | a prefix | `string::starts_with(field, $v)` |
|
|
240
|
+
| `endswith` | a suffix | `string::ends_with(field, $v)` |
|
|
241
|
+
| `like` | an SQL `LIKE` pattern | `string::matches(field, $v)`, the pattern translated to an anchored `(?s)` regex |
|
|
242
|
+
| `ilike` | the same, case-insensitive | the same, with `(?i)` added |
|
|
243
|
+
| `regex` | a regular expression | `string::matches(field, $v)` |
|
|
244
|
+
| `match` | a regular expression | `string::matches(field, $v)`: the same as `regex` |
|
|
245
|
+
|
|
246
|
+
```python
|
|
247
|
+
await User.objects().filter(name__startswith="A").exec()
|
|
248
|
+
await User.objects().filter(email__ilike="%@EXAMPLE.com").exec() # case-insensitive
|
|
249
|
+
await User.objects().filter(code__like="AB_-%").exec() # "AB", any one character, "-", anything
|
|
250
|
+
await User.objects().filter(name__regex=r"^\d{3}").exec() # SurrealDB's regex syntax (Rust regex)
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
- **Non-string fields.** Each condition is guarded by the field's type:
|
|
254
|
+
`filter(name__startswith="A")` is `((name).is_string() AND string::starts_with(name, $_f0))`.
|
|
255
|
+
A record whose field is missing (`NONE`), `NULL` or not a string never matches, and the
|
|
256
|
+
query does not fail on it. The negation (`~Q(name__startswith="A")`) matches it. A dotted
|
|
257
|
+
path through an array of record links or objects (`authors.name`) holds an array, so it
|
|
258
|
+
never matches either, on both lines: the parentheses make SurrealDB 3.x test that array,
|
|
259
|
+
not each of its elements.
|
|
260
|
+
- **`like` / `ilike` patterns.** `%` matches any run of characters (newlines included) and `_`
|
|
261
|
+
exactly one character. Every other character is literal, regex metacharacters included
|
|
262
|
+
(`.`, `*`, `(`, `\`, …). There is no escape character, so a pattern cannot match a literal
|
|
263
|
+
`%` or `_` alone: use `regex` for that. The whole value must match, so `like="Al"` finds
|
|
264
|
+
`"Al"` but not `"Alice"`.
|
|
265
|
+
- **`match` and `regex`.** Both take a regular expression in SurrealDB's syntax (the Rust
|
|
266
|
+
`regex` crate) and match anywhere in the value unless it is anchored (`^…$`). Prefix it
|
|
267
|
+
with `(?i)` to ignore case. Here `match` is a regex lookup, not the full SurrealDB-ORM's
|
|
268
|
+
full-text `@@` operator: full-text search is planned for v0.34.0, as a separate API.
|
|
269
|
+
- **Values.** The value must be a `str`, otherwise `ValueError`. A string starting with `$`
|
|
270
|
+
is data, as for every lookup ([String filter values and `Var()`](#string-filter-values-and-var)).
|
|
271
|
+
`startswith`, `endswith`, `match` and `regex` also take a `Var`. `like` and `ilike` do not:
|
|
272
|
+
their pattern is translated before it is sent, so `Var` raises `ValueError`.
|
|
273
|
+
|
|
234
274
|
#### Filtering on the record id
|
|
235
275
|
|
|
236
276
|
The `id` column holds a native `RecordID`, not a string, so the ORM coerces an `id` lookup
|
|
@@ -303,15 +343,39 @@ raises `ValueError`; when it names a variable of `variables()` or one of these p
|
|
|
303
343
|
message names the `Var(...)` to write.
|
|
304
344
|
|
|
305
345
|
`get_or_create()` and `update_or_create()` look up their criteria and write the `exact` ones on
|
|
306
|
-
create
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
346
|
+
create. Their lookup binds `variables()`, as `filter()` does, so a `Var` criterion reads the
|
|
347
|
+
variable there too, and an `exact` one is written as the variable's value on create: the next
|
|
348
|
+
identical call finds the record.
|
|
349
|
+
|
|
350
|
+
```python
|
|
351
|
+
qs = Room.objects().variables(t="mine", n=10)
|
|
352
|
+
room, created = await qs.get_or_create(title=Var("t")) # as get_or_create(title="mine")
|
|
353
|
+
room, created = await qs.update_or_create(size__gte=Var("n"), title=Var("t"), defaults={"floor": 2})
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
On the record id and on an edge's `in` and `out`, such a criterion is compared as the record id
|
|
357
|
+
its value names, as the same criterion given that value is: with `variables(a="person:alice")`,
|
|
358
|
+
`get_or_create(in_=Var("a"), out=bob)` finds or relates `person:alice`. A value that names no record
|
|
359
|
+
id there raises `ValueError` before any request. A model instance given to `variables()` is bound
|
|
360
|
+
and written as its record id, as the instance given as the criterion is (`variables(a=alice)`); an
|
|
361
|
+
unsaved one raises `ValueError` before any request. The `variables()` of a subquery criterion share
|
|
362
|
+
the lookup, as in `filter()`: one that binds a name of the queryset's `variables()` to another
|
|
363
|
+
value raises `ValueError`. `Var("auth")` finds the signed-in user's record
|
|
312
364
|
(`get_or_create(owner=Var("auth"))` returns it) but cannot be written: with no record to return, it
|
|
313
|
-
raises `SurrealDbError
|
|
314
|
-
|
|
365
|
+
raises `SurrealDbError`, and so does an `exact` `Var` that names no variable of `variables()`.
|
|
366
|
+
|
|
367
|
+
A string criterion is refused where it would be a trap: `update_or_create(owner="$auth", defaults=…)`
|
|
368
|
+
would find and write the record whose `owner` is the string `"$auth"`, the same record for every
|
|
369
|
+
record user, and `members__contains="$auth"` would look for the string. A criterion that is exactly
|
|
370
|
+
`$` followed by the name of one of these parameters or of a variable the lookup binds (of
|
|
371
|
+
`variables()`, the queryset's or a subquery criterion's) raises `SurrealDbError` before any request,
|
|
372
|
+
whatever its lookup. For a variable, the message names `Var("x")` as the criterion to write, under
|
|
373
|
+
any lookup but `like`/`ilike`, which take no `Var` (pass the pattern itself, or use `regex`). For a
|
|
374
|
+
parameter, it says to pass the actual value as an `exact` criterion (the record id, or the value
|
|
375
|
+
itself), and that `Var("auth")` works under any other lookup but `like`/`ilike`, which take no `Var`
|
|
376
|
+
(pass the pattern itself, or use `regex`): `members__contains=Var("auth")` is looked up, never
|
|
377
|
+
written. Any other string, such as `"$admin"`, is looked up and written as it is. On an edge's `in`
|
|
378
|
+
and `out`, such a criterion raises the `ValueError` above.
|
|
315
379
|
|
|
316
380
|
`variables()` refuses these four names with a `ValueError`: SurrealDB sets them for each session
|
|
317
381
|
and refuses a query variable of that name. To pass your own value, give it another name, or pass
|
|
@@ -646,7 +710,10 @@ async with SurrealDBConnectionManager.transaction() as tx:
|
|
|
646
710
|
|
|
647
711
|
If the lookup criteria match more than one record, both methods raise `SurrealDbError`
|
|
648
712
|
(the criteria are not unique). Non-`exact` lookups (e.g. `name__contains`) drive the lookup
|
|
649
|
-
but are not written to the record.
|
|
713
|
+
but are not written to the record. The lookup binds the queryset's `variables()`, as `filter()`
|
|
714
|
+
does: `User.objects().variables(e="bob@example.com").get_or_create(email=Var("e"))` finds the user
|
|
715
|
+
whose email is the variable's value, and writes that value on create (see
|
|
716
|
+
[String filter values and `Var()`](#string-filter-values-and-var)). Without a transaction the behaviour is identical on
|
|
650
717
|
SurrealDB 2.6.x and 3.x; under `objects(tx=)` they participate in the transaction on 3.x,
|
|
651
718
|
while a buffered 2.6.x transaction raises on the lookup (see the behaviour table).
|
|
652
719
|
|
|
@@ -4072,7 +4139,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
4072
4139
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
4073
4140
|
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
|
|
4074
4141
|
otherwise. The full suite and every divergence below were re-verified on both new versions.
|
|
4075
|
-
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.
|
|
4142
|
+
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.
|
|
4076
4143
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
4077
4144
|
|
|
4078
4145
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -4182,6 +4249,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
4182
4249
|
| `filter(f="$x")`: a string filter value starting with `$` | same on both lines: compared with the string `"$x"`, bound like any value, in a live query too; `Var("x")` reads the variable `$x`, `Var("auth")` SurrealDB's `$auth` | the same; on an edge's `in`/`out` (record ids) such a string raises `ValueError`, on both lines; `$access`, `$session`, `$token` read like `$auth` | v0.28.1 |
|
|
4183
4250
|
| `limit(n)` or `offset(n)` above `4294967295` (`2**32 - 1`) | the server refuses the read: `Found <n> but the LIMIT clause must evaluate to a positive integer` (`START` likewise) | read; above `2**63 - 1` the ORM raises `ValueError` when `limit()` or `offset()` is called, on both lines | pre-existing (documented in v0.28.1) |
|
|
4184
4251
|
| Several connections in one process (`add_connection()`, `using()`) | each connection follows its own server: a 2.x connection's transactions are buffered, whatever the others are | each 3.x WebSocket connection gets interactive transactions, beside 2.x connections in the same process | v0.29.0 |
|
|
4252
|
+
| Text lookups (`startswith`, `endswith`, `like`, `ilike`, `match`, `regex`) | same on both lines: string functions guarded by `(field).is_string()` (`type::is::string` is 2.x-only); a `NONE`, `NULL`, non-string or array path value never matches | the same (`type::is_string` is 3.x-only; `a.b.is_string()` tests each element of an array path); until v0.29.1: operators SurrealQL lacks (`LIKE`…), a parse error on both lines | v0.29.2 |
|
|
4185
4253
|
| 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 |
|
|
4186
4254
|
|
|
4187
4255
|
> **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.
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
#: The lookups that compile to a SurrealQL infix operator (``field <op> $_f<n>``). With
|
|
2
|
+
#: ``GEOMETRY_LOOKUP_OPERATORS`` and ``TEXT_LOOKUP_FUNCTIONS`` it is the list of valid lookups.
|
|
1
3
|
LOOKUP_OPERATORS = {
|
|
2
4
|
"exact": "=",
|
|
3
5
|
"gt": ">",
|
|
@@ -6,19 +8,26 @@ LOOKUP_OPERATORS = {
|
|
|
6
8
|
"lte": "<=",
|
|
7
9
|
"in": "IN",
|
|
8
10
|
"not_in": "NOT IN",
|
|
9
|
-
"like": "LIKE",
|
|
10
|
-
"ilike": "ILIKE",
|
|
11
11
|
"contains": "CONTAINS",
|
|
12
12
|
"not_contains": "CONTAINSNOT",
|
|
13
13
|
"containsall": "CONTAINSALL",
|
|
14
14
|
"containsany": "CONTAINSANY",
|
|
15
|
-
"startswith": "STARTSWITH",
|
|
16
|
-
"endswith": "ENDSWITH",
|
|
17
|
-
"match": "MATCH",
|
|
18
|
-
"regex": "REGEX",
|
|
19
15
|
"isnull": "IS",
|
|
20
16
|
}
|
|
21
17
|
|
|
18
|
+
#: The text lookups (#251): SurrealQL has no infix operator for them (``LIKE``, ``STARTSWITH``, ``REGEX``… are parse
|
|
19
|
+
#: errors on 2.x and 3.x), so each compiles to the string function named here, guarded by the field's type:
|
|
20
|
+
#: ``((name).is_string() AND string::starts_with(name, $_f0))`` (``utils._text_condition``). ``like``/``ilike`` bind
|
|
21
|
+
#: their pattern translated to a regular expression, ``match``/``regex`` theirs as it is.
|
|
22
|
+
TEXT_LOOKUP_FUNCTIONS = {
|
|
23
|
+
"startswith": "string::starts_with",
|
|
24
|
+
"endswith": "string::ends_with",
|
|
25
|
+
"like": "string::matches",
|
|
26
|
+
"ilike": "string::matches",
|
|
27
|
+
"match": "string::matches",
|
|
28
|
+
"regex": "string::matches",
|
|
29
|
+
}
|
|
30
|
+
|
|
22
31
|
#: The spatial lookups (v0.24.0): SurrealQL's geometry operators, each taking one geometry. They live
|
|
23
32
|
#: apart from ``LOOKUP_OPERATORS`` because their value is a geometry, never a list or a string, and
|
|
24
33
|
#: ``build_filter_condition`` reads this mapping first.
|
|
@@ -2,7 +2,7 @@ import contextlib
|
|
|
2
2
|
import logging
|
|
3
3
|
import math
|
|
4
4
|
import numbers
|
|
5
|
-
from collections.abc import Awaitable, Callable,
|
|
5
|
+
from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence
|
|
6
6
|
from datetime import datetime, timedelta
|
|
7
7
|
from typing import TYPE_CHECKING, Any, Self, SupportsIndex, cast
|
|
8
8
|
from uuid import UUID
|
|
@@ -34,10 +34,12 @@ from .subquery import SubqueryCompiler
|
|
|
34
34
|
from .surql_literal import inline_variables
|
|
35
35
|
from .types import Duration
|
|
36
36
|
from .utils import (
|
|
37
|
+
RECORD_ID_COLUMN,
|
|
37
38
|
VALID_FIELD_PATTERN,
|
|
38
39
|
VARIABLE_NAME_VALUE,
|
|
39
40
|
as_record_value,
|
|
40
41
|
build_filter_condition,
|
|
42
|
+
coerce_endpoint,
|
|
41
43
|
coerce_record_id,
|
|
42
44
|
is_select_item,
|
|
43
45
|
non_negative_int,
|
|
@@ -68,6 +70,18 @@ _CACHE_QUERY = (
|
|
|
68
70
|
_CACHE_DISABLED = "QueryCache is disabled — .cache() has no effect"
|
|
69
71
|
|
|
70
72
|
|
|
73
|
+
def _unwritable_variable(field: str, name: str) -> str:
|
|
74
|
+
"""The refusal of an ``exact`` ``Var(name)`` criterion the create of ``get_or_create()``/``update_or_create()``
|
|
75
|
+
cannot write (issue #252): a session parameter, or a name no ``variables()`` of the lookup gives."""
|
|
76
|
+
if name in SESSION_PARAMETERS:
|
|
77
|
+
why = f"it reads SurrealDB's ${name} parameter, whose value only the database knows"
|
|
78
|
+
advice = "Pass the value itself as the criterion or in defaults=."
|
|
79
|
+
else:
|
|
80
|
+
why = f"variables() gives no {name}, so only the database knows its value"
|
|
81
|
+
advice = f"Give {name} to variables(), or pass the value itself as the criterion or in defaults=."
|
|
82
|
+
return f"Cannot create a record from Var('{name}') given for '{field}': {why}. {advice}"
|
|
83
|
+
|
|
84
|
+
|
|
71
85
|
class QuerySet:
|
|
72
86
|
"""
|
|
73
87
|
A class used to build, execute, and manage queries on a SurrealDB table associated with a specific model.
|
|
@@ -809,13 +823,7 @@ class QuerySet:
|
|
|
809
823
|
|
|
810
824
|
return parts, variables, counter
|
|
811
825
|
|
|
812
|
-
def _build_where(
|
|
813
|
-
self,
|
|
814
|
-
*,
|
|
815
|
-
as_of: bool = False,
|
|
816
|
-
subqueries: SubqueryCompiler | None = None,
|
|
817
|
-
variable_names: Collection[str] = (),
|
|
818
|
-
) -> tuple[str, dict[str, Any]]:
|
|
826
|
+
def _build_where(self, *, as_of: bool = False, subqueries: SubqueryCompiler | None = None) -> tuple[str, dict[str, Any]]:
|
|
819
827
|
"""
|
|
820
828
|
Build a parameterized WHERE clause from filters, Q objects and ``nearby()`` conditions.
|
|
821
829
|
|
|
@@ -824,27 +832,18 @@ class QuerySet:
|
|
|
824
832
|
by *subqueries*, the statement's compiler; without one it raises ``ValueError`` (S8).
|
|
825
833
|
|
|
826
834
|
Once every condition is compiled, a scalar ``str`` filter value that is ``$`` and the name of one of the
|
|
827
|
-
statement's ``variables()`` — this queryset's
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
nothing is checked: only a statement has variables.
|
|
831
|
-
|
|
832
|
-
Args:
|
|
833
|
-
variable_names: names the checks count as variables besides the statement's (the warning, and the hint
|
|
834
|
-
of an edge endpoint's ``ValueError``): the ``variables()`` of the queryset whose
|
|
835
|
-
``get_or_create()``/``update_or_create()`` look up with this one. Kept on *subqueries*
|
|
836
|
-
(``outer_variable_names``).
|
|
835
|
+
statement's ``variables()`` — this queryset's or its subqueries' — or of SurrealDB's session parameters
|
|
836
|
+
(``$auth``…) gives a ``UserWarning`` naming ``Var(...)`` (:func:`utils.warn_on_variable_names`, v0.28.1),
|
|
837
|
+
unless ``subqueries.warn`` is false. Without *subqueries* nothing is checked: only a statement has variables.
|
|
837
838
|
|
|
838
839
|
Returns:
|
|
839
840
|
A tuple of (where_clause_string, variables_dict).
|
|
840
841
|
The where_clause_string includes the ``WHERE`` keyword, or is empty if no filters.
|
|
841
842
|
"""
|
|
842
|
-
if subqueries is not None and variable_names:
|
|
843
|
-
subqueries.outer_variable_names = frozenset(variable_names)
|
|
844
843
|
parts, variables, _ = self._where_parts(0, as_of=as_of, subqueries=subqueries)
|
|
845
844
|
if subqueries is not None:
|
|
846
845
|
if subqueries.warn:
|
|
847
|
-
warn_on_variable_names(subqueries.variable_like,
|
|
846
|
+
warn_on_variable_names(subqueries.variable_like, subqueries.variables)
|
|
848
847
|
subqueries.variable_like.clear()
|
|
849
848
|
if not parts:
|
|
850
849
|
return "", {}
|
|
@@ -2017,8 +2016,7 @@ class QuerySet:
|
|
|
2017
2016
|
|
|
2018
2017
|
# ==================== Upsert / get_or_create ====================
|
|
2019
2018
|
|
|
2020
|
-
|
|
2021
|
-
def _criteria_payload(criteria: dict[str, Any]) -> dict[str, Any]:
|
|
2019
|
+
def _criteria_payload(self, criteria: Mapping[str, Any]) -> dict[str, Any]:
|
|
2022
2020
|
"""Field=value pairs usable as a WRITE payload, taken from EQUALITY criteria only.
|
|
2023
2021
|
|
|
2024
2022
|
``criteria`` keys are filter lookups (``field`` or ``field__lookup``). A literal raw
|
|
@@ -2032,23 +2030,37 @@ class QuerySet:
|
|
|
2032
2030
|
gets created is the row the next lookup finds: a ``str`` is data, ``"$admin"`` included;
|
|
2033
2031
|
the deprecated ``"$$admin"`` escape is un-escaped to ``"$admin"`` (otherwise it filtered on
|
|
2034
2032
|
``"$admin"`` but stored ``"$$admin"``, never converging and creating a duplicate on every
|
|
2035
|
-
call), without a second warning (the lookup warns)
|
|
2036
|
-
|
|
2037
|
-
|
|
2038
|
-
|
|
2039
|
-
|
|
2040
|
-
|
|
2033
|
+
call), without a second warning (the lookup warns). A model instance is written as its
|
|
2034
|
+
record id, the value its lookup binds (v0.22.0): ``get_or_create(customer=alice)`` stores
|
|
2035
|
+
``customer = RecordID(...)``. A string ``"$auth"`` naming a session parameter or a variable
|
|
2036
|
+
the lookup binds never gets here: the caller refused it before the lookup
|
|
2037
|
+
(:meth:`_reject_string_references`).
|
|
2038
|
+
|
|
2039
|
+
A ``Var("t")`` criterion naming a variable the lookup binds (:meth:`_lookup_variables`: this
|
|
2040
|
+
queryset's ``variables()`` and those of its subquery criteria) is written as that variable's value,
|
|
2041
|
+
through :func:`~surreal_orm_lite.utils.as_record_value` — data, never un-escaped (issue #252): the lookup
|
|
2042
|
+
compared the column with that value, so the next identical call finds the record.
|
|
2043
|
+
``get_or_create(title=Var("t"))`` with ``variables(t="mine")`` writes ``title = "mine"``. Any other
|
|
2044
|
+
``Var`` — a session parameter (``Var("auth")``), a name no ``variables()`` gives — is refused: its value
|
|
2045
|
+
is only known to the database, so it cannot be written back (issue #156 follow-up).
|
|
2046
|
+
|
|
2047
|
+
Raises:
|
|
2048
|
+
SurrealDbError: an ``exact`` ``Var`` criterion naming no variable the lookup binds.
|
|
2049
|
+
ValueError: an unsaved model instance; and what compiling the criteria raises (:meth:`_lookup_variables`).
|
|
2041
2050
|
"""
|
|
2042
2051
|
payload: dict[str, Any] = {}
|
|
2052
|
+
variables: dict[str, Any] | None = None
|
|
2043
2053
|
for key, value in criteria.items():
|
|
2044
2054
|
field_name, lookup = parse_lookup(key)
|
|
2045
2055
|
if lookup != "exact":
|
|
2046
2056
|
continue
|
|
2047
2057
|
if isinstance(value, Var):
|
|
2048
|
-
|
|
2049
|
-
|
|
2050
|
-
|
|
2051
|
-
|
|
2058
|
+
if variables is None:
|
|
2059
|
+
variables = self._lookup_variables(criteria)
|
|
2060
|
+
if value.name not in variables:
|
|
2061
|
+
raise SurrealDbError(_unwritable_variable(field_name, value.name))
|
|
2062
|
+
payload[field_name] = as_record_value(variables[value.name])
|
|
2063
|
+
continue
|
|
2052
2064
|
payload[field_name] = as_record_value(unescape_filter_value(value, warn=False))
|
|
2053
2065
|
return payload
|
|
2054
2066
|
|
|
@@ -2080,72 +2092,170 @@ class QuerySet:
|
|
|
2080
2092
|
owner is the string ``"$auth"``, the same record for every record user, and ``members__contains="$auth"``
|
|
2081
2093
|
would look for the string. A criterion whose read would warn
|
|
2082
2094
|
(:func:`~surreal_orm_lite.utils.warn_on_variable_names`) — a scalar ``str`` that is ``$`` and the name of a
|
|
2083
|
-
variable this queryset's ``variables()``
|
|
2084
|
-
|
|
2085
|
-
|
|
2086
|
-
|
|
2087
|
-
|
|
2095
|
+
variable the lookup binds (:meth:`_lookup_variables`: this queryset's ``variables()`` and, since issue #252,
|
|
2096
|
+
those of its subquery criteria, which its read counted already), or of one of SurrealDB's session
|
|
2097
|
+
parameters — is refused instead, before any request. For a variable, the message names ``Var(...)`` as the
|
|
2098
|
+
criterion to pass: the lookup reads the variable, and the create writes its value. For a session parameter
|
|
2099
|
+
it says to pass the actual value under ``exact`` (``Var("auth")`` is looked up but cannot be written), and
|
|
2100
|
+
that ``Var("auth")`` works under any other lookup, which is only looked up. ``like``/``ilike`` take no
|
|
2101
|
+
``Var`` (their pattern is translated to a regular expression before it is sent): under them, for a variable
|
|
2102
|
+
and a session parameter alike, the message says neither, but to pass the actual pattern as the criterion,
|
|
2103
|
+
or to use ``regex`` with a ``Var`` holding a regular expression. On the ``id`` column the string is the
|
|
2104
|
+
record id ``table:⟨$name⟩``, which the message names. Any other ``"$name"`` is data, looked up and written as
|
|
2105
|
+
it is, and so is an item of a list lookup. A criterion the lookup refuses with a ``ValueError`` (an edge
|
|
2106
|
+
endpoint, which holds a record id; a text lookup on ``id``) raises that error here, as the lookup would: on
|
|
2107
|
+
an edge endpoint its message names the same ``Var(...)``.
|
|
2088
2108
|
|
|
2089
2109
|
Raises:
|
|
2090
2110
|
SurrealDbError: the first such criterion.
|
|
2091
|
-
|
|
2092
|
-
|
|
2093
|
-
|
|
2094
|
-
|
|
2095
|
-
|
|
2096
|
-
|
|
2097
|
-
|
|
2098
|
-
|
|
2111
|
+
ValueError: what compiling the criteria raises (:meth:`_lookup_variables`).
|
|
2112
|
+
"""
|
|
2113
|
+
candidates = [
|
|
2114
|
+
(key, value, match.group(1))
|
|
2115
|
+
for key, value in criteria.items()
|
|
2116
|
+
if isinstance(value, str) and (match := VARIABLE_NAME_VALUE.fullmatch(value)) is not None
|
|
2117
|
+
]
|
|
2118
|
+
if not candidates:
|
|
2119
|
+
return
|
|
2120
|
+
variables = self._lookup_variables(criteria)
|
|
2121
|
+
for key, value, name in candidates:
|
|
2122
|
+
if name in variables:
|
|
2123
|
+
source, variable = f"the variable {name} given to variables()", True
|
|
2099
2124
|
elif name in SESSION_PARAMETERS:
|
|
2100
|
-
source,
|
|
2125
|
+
source, variable = f"SurrealDB's ${name} parameter", False
|
|
2101
2126
|
else:
|
|
2102
2127
|
continue
|
|
2103
|
-
|
|
2104
|
-
|
|
2105
|
-
how = "looked up and written" if
|
|
2128
|
+
field_name, lookup = parse_lookup(key)
|
|
2129
|
+
written = lookup == "exact"
|
|
2130
|
+
how = "looked up and written" if written else "looked up"
|
|
2131
|
+
if self._column(field_name) == RECORD_ID_COLUMN:
|
|
2132
|
+
what = f"the record id {coerce_record_id(value, self._model_table)}"
|
|
2133
|
+
else:
|
|
2134
|
+
what = f"the string '${name}'"
|
|
2135
|
+
if lookup in ("like", "ilike"):
|
|
2136
|
+
advice = (
|
|
2137
|
+
f"'{lookup}' cannot take Var('{name}'): its pattern is translated to a regular expression before "
|
|
2138
|
+
"it is sent. Pass the actual pattern as the criterion, or use 'regex' with a Var holding a regular "
|
|
2139
|
+
"expression."
|
|
2140
|
+
)
|
|
2141
|
+
elif variable:
|
|
2142
|
+
advice = f"To read the variable, pass Var('{name}') as the criterion" + (
|
|
2143
|
+
": the create writes the variable's value." if written else "."
|
|
2144
|
+
)
|
|
2145
|
+
elif written:
|
|
2146
|
+
advice = (
|
|
2147
|
+
f"Pass the actual value as the criterion (the record id, or the value itself); Var('{name}') reads "
|
|
2148
|
+
"the parameter in the lookup but cannot be written."
|
|
2149
|
+
)
|
|
2150
|
+
else:
|
|
2151
|
+
advice = (
|
|
2152
|
+
f"To read the parameter, pass Var('{name}') as the criterion: {key}=Var('{name}') is looked up, "
|
|
2153
|
+
"never written."
|
|
2154
|
+
)
|
|
2106
2155
|
raise SurrealDbError(
|
|
2107
|
-
f"Cannot look up or create a record from the string '${name}' given for '{key}': it names "
|
|
2108
|
-
f"
|
|
2109
|
-
f"the criterion (the record id, or the value itself); Var('{name}') reads the {kind} in a filter but "
|
|
2110
|
-
"cannot be written."
|
|
2156
|
+
f"Cannot look up or create a record from the string '${name}' given for '{key}': it names {source}, "
|
|
2157
|
+
f"but a string criterion is data, {how} as {what}. {advice}"
|
|
2111
2158
|
)
|
|
2112
2159
|
|
|
2113
|
-
def
|
|
2114
|
-
"""
|
|
2160
|
+
def _lookup_probe(self, criteria: Mapping[str, Any]) -> "QuerySet":
|
|
2161
|
+
"""The queryset the lookup of ``get_or_create()``/``update_or_create()`` reads with: *criteria* as its
|
|
2162
|
+
filters, a copy of this queryset's ``variables()`` (issue #252) and its transaction (``objects(tx=)``); no
|
|
2163
|
+
``cache()``, no ``as_of()``."""
|
|
2164
|
+
probe = QuerySet(self.model)
|
|
2165
|
+
probe.filter(**criteria)
|
|
2166
|
+
probe._variables = dict(self._variables)
|
|
2167
|
+
probe._tx = self._tx
|
|
2168
|
+
return probe
|
|
2169
|
+
|
|
2170
|
+
def _lookup_variables(self, criteria: Mapping[str, Any]) -> dict[str, Any]:
|
|
2171
|
+
"""The variables the lookup of *criteria* binds (issue #252), by name.
|
|
2172
|
+
|
|
2173
|
+
This queryset's ``variables()``, then those of each subquery criterion (nested ones included), merged as
|
|
2174
|
+
in ``filter()``: the statement :meth:`_lookup_matches` sends binds them all. Compiled, never sent, without
|
|
2175
|
+
a warning.
|
|
2115
2176
|
|
|
2116
|
-
|
|
2117
|
-
|
|
2118
|
-
|
|
2177
|
+
Raises:
|
|
2178
|
+
ValueError, SurrealDbError: what the lookup raises compiling *criteria*, before any request — S7 for a
|
|
2179
|
+
subquery binding one of these names to another value, an edge endpoint that is no record id…
|
|
2119
2180
|
"""
|
|
2120
|
-
|
|
2121
|
-
|
|
2122
|
-
|
|
2123
|
-
|
|
2124
|
-
|
|
2125
|
-
|
|
2181
|
+
probe = self._lookup_probe(criteria)
|
|
2182
|
+
compiler = probe._subquery_compiler(warn=False)
|
|
2183
|
+
probe._where_parts(subqueries=compiler)
|
|
2184
|
+
return compiler.variables
|
|
2185
|
+
|
|
2186
|
+
def _lookup_criteria(self, criteria: Mapping[str, Any]) -> dict[str, Any]:
|
|
2187
|
+
"""*criteria* as the lookup compares them (issue #252).
|
|
2188
|
+
|
|
2189
|
+
An ``exact`` ``Var("k")`` criterion on the record id column or on an edge endpoint (``in``/``out``), naming
|
|
2190
|
+
a variable the lookup binds, is compared with the record id that variable's value names — read as the same
|
|
2191
|
+
criterion given that value is (:func:`~surreal_orm_lite.utils.coerce_record_id`,
|
|
2192
|
+
:func:`~surreal_orm_lite.utils.coerce_endpoint`): ``id=Var("k")`` with ``variables(k="r1")`` compares
|
|
2193
|
+
``id`` with ``<table>:r1``, the record the create writes. Compared with the variable as it is, a string never
|
|
2194
|
+
equals a record id: the lookup would never find the record it created. Every other criterion is unchanged,
|
|
2195
|
+
a ``Var`` reading its variable as ``filter()`` does.
|
|
2196
|
+
|
|
2197
|
+
Raises:
|
|
2198
|
+
ValueError: the variable's value names no record id there (``in_=Var("a")`` with ``variables(a="x")``,
|
|
2199
|
+
a ``bool`` for ``id``), before any request; and what :meth:`_lookup_variables` raises.
|
|
2200
|
+
"""
|
|
2201
|
+
endpoint_columns = self.model._endpoint_columns()
|
|
2202
|
+
looked_up = dict(criteria)
|
|
2203
|
+
variables: dict[str, Any] | None = None
|
|
2204
|
+
for key, value in criteria.items():
|
|
2205
|
+
field_name, lookup = parse_lookup(key)
|
|
2206
|
+
if lookup != "exact" or not isinstance(value, Var):
|
|
2207
|
+
continue
|
|
2208
|
+
column = self._column(field_name)
|
|
2209
|
+
if column != RECORD_ID_COLUMN and column not in endpoint_columns:
|
|
2210
|
+
continue
|
|
2211
|
+
if variables is None:
|
|
2212
|
+
variables = self._lookup_variables(criteria)
|
|
2213
|
+
if value.name not in variables:
|
|
2214
|
+
continue
|
|
2215
|
+
try:
|
|
2216
|
+
record = as_record_value(variables[value.name])
|
|
2217
|
+
if column == RECORD_ID_COLUMN:
|
|
2218
|
+
looked_up[key] = coerce_record_id(record, self._model_table)
|
|
2219
|
+
else:
|
|
2220
|
+
looked_up[key] = coerce_endpoint(record)
|
|
2221
|
+
except ValueError as exc:
|
|
2222
|
+
raise ValueError(
|
|
2223
|
+
f"Var('{value.name}') given for '{key}' is compared as the record id its value names: {exc}"
|
|
2224
|
+
) from exc
|
|
2225
|
+
return looked_up
|
|
2126
2226
|
|
|
2127
2227
|
async def _lookup_matches(self, criteria: dict[str, Any]) -> list[Any]:
|
|
2128
2228
|
"""Return rows matching ``criteria``, routed through the transaction when attached.
|
|
2129
2229
|
|
|
2130
2230
|
Reuses the parameterized WHERE builder (anti-injection) via a throwaway QuerySet's
|
|
2131
|
-
``filter(**criteria)
|
|
2132
|
-
it — seeing the tx's uncommitted writes on an interactive transaction, and raising on a
|
|
2231
|
+
``filter(**criteria)`` (:meth:`_lookup_probe`), joined to ``self._tx`` (``objects(tx=)``) so the read
|
|
2232
|
+
participates in it — seeing the tx's uncommitted writes on an interactive transaction, and raising on a
|
|
2133
2233
|
buffered one (consistent with every other read). ``LIMIT 2`` is enough to distinguish
|
|
2134
2234
|
0 / 1 / >1. A subquery criterion (v0.27.0) is read in the same statement, a block
|
|
2135
|
-
``{ LET $_sq0 = (…); (SELECT … LIMIT 2) };``, run as every read is (:meth:`_run_compiled`).
|
|
2136
|
-
|
|
2137
|
-
|
|
2138
|
-
(
|
|
2235
|
+
``{ LET $_sq0 = (…); (SELECT … LIMIT 2) };``, run as every read is (:meth:`_run_compiled`), never cached.
|
|
2236
|
+
|
|
2237
|
+
The lookup binds this queryset's ``variables()`` (issue #252; until then it bound none, and a ``Var``
|
|
2238
|
+
criterion read ``NONE``), merged with its subquery criteria's as ``filter()`` merges them (S7 when a
|
|
2239
|
+
subquery binds a name to another value), so ``variables(n=10).get_or_create(size__gte=Var("n"))`` compares
|
|
2240
|
+
``size`` with 10. An ``exact`` ``Var`` criterion on the record id or an edge endpoint is compared with the
|
|
2241
|
+
record id its value names (:meth:`_lookup_criteria`). A criterion ``"$name"`` that would warn never gets
|
|
2242
|
+
here (:meth:`_reject_string_references`).
|
|
2243
|
+
|
|
2244
|
+
Each variable is bound as the value the create writes (:func:`~surreal_orm_lite.utils.as_record_value`): a
|
|
2245
|
+
model instance as its record id, whether a criterion reads it or not — bound as it is, the SDK has no
|
|
2246
|
+
encoder for it. S7 compares the values given to ``variables()``, before that conversion.
|
|
2247
|
+
|
|
2248
|
+
Raises:
|
|
2249
|
+
ValueError: an unsaved model instance in the variables (it has no record id), before any request.
|
|
2139
2250
|
"""
|
|
2140
|
-
probe =
|
|
2141
|
-
probe.filter(**criteria)
|
|
2142
|
-
probe._tx = self._tx
|
|
2251
|
+
probe = self._lookup_probe(self._lookup_criteria(criteria))
|
|
2143
2252
|
table = self._model_table
|
|
2144
2253
|
|
|
2145
2254
|
def compile_statement(compiler: SubqueryCompiler) -> tuple[str, dict[str, Any]]:
|
|
2146
|
-
where_clause, where_vars = probe._build_where(subqueries=compiler
|
|
2255
|
+
where_clause, where_vars = probe._build_where(subqueries=compiler)
|
|
2147
2256
|
query = f"SELECT * FROM {table}{where_clause} LIMIT 2;"
|
|
2148
|
-
|
|
2257
|
+
bound = {name: as_record_value(value) for name, value in compiler.variables.items()}
|
|
2258
|
+
return compiler.wrap(query), {**bound, **where_vars}
|
|
2149
2259
|
|
|
2150
2260
|
rows = await probe._run_compiled(compile_statement)
|
|
2151
2261
|
return rows if isinstance(rows, list) else []
|
|
@@ -2215,14 +2325,29 @@ class QuerySet:
|
|
|
2215
2325
|
never written; one the create would have to write — under an ``exact`` lookup, or in
|
|
2216
2326
|
``defaults`` — raises ``SurrealDbError`` before any request.
|
|
2217
2327
|
|
|
2328
|
+
The lookup binds this queryset's ``variables()``, as ``filter()`` does (issue #252; until then a ``Var``
|
|
2329
|
+
criterion read ``NONE`` there, and a comparison could match, then update, a record the caller did not
|
|
2330
|
+
mean): ``objects().variables(n=10).update_or_create(size__gte=Var("n"), title="mine", defaults=…)``
|
|
2331
|
+
compares ``size`` with 10. A subquery criterion's ``variables()`` share the statement: one binding a name of
|
|
2332
|
+
this queryset's to another value raises S7 (``ValueError``) before any request. An ``exact`` ``Var``
|
|
2333
|
+
criterion naming a variable the lookup binds is written as that variable's value on create
|
|
2334
|
+
(``title=Var("t")`` with ``variables(t="mine")`` writes ``title = "mine"``), so the next identical call
|
|
2335
|
+
finds the record; on the record id and an edge's ``in``/``out`` it is compared as the record id its value
|
|
2336
|
+
names, as the same criterion given that value is. A model instance in ``variables()`` is bound and written as
|
|
2337
|
+
its record id (an unsaved one raises ``ValueError`` before any request). A ``Var`` naming a session
|
|
2338
|
+
parameter (``Var("auth")``) or a name no ``variables()`` gives is looked up but cannot be written:
|
|
2339
|
+
``SurrealDbError`` before any write.
|
|
2340
|
+
|
|
2218
2341
|
A ``str`` criterion is data, looked up and written as it is (``owner="$admin"``). A scalar criterion, whatever
|
|
2219
|
-
its lookup, that is ``$`` and the name of a variable
|
|
2342
|
+
its lookup, that is ``$`` and the name of a variable the lookup binds or of one of SurrealDB's session
|
|
2220
2343
|
parameters — ``update_or_create(owner="$auth", …)`` — raises ``SurrealDbError`` before any request
|
|
2221
2344
|
(v0.28.1): it would find and write the record whose owner is the string ``"$auth"``, the same for every
|
|
2222
|
-
record user.
|
|
2223
|
-
|
|
2224
|
-
|
|
2225
|
-
``
|
|
2345
|
+
record user. For a variable, the message names ``Var(...)`` as the criterion to pass, under any lookup but
|
|
2346
|
+
``like``/``ilike``, which take no ``Var`` (pass the pattern itself, or use ``regex``); for a session
|
|
2347
|
+
parameter, it says to pass the actual value (the record id, or the value itself) under ``exact`` and that
|
|
2348
|
+
``Var("auth")`` works under any other lookup but ``like``/``ilike``, which take no ``Var`` (pass the pattern
|
|
2349
|
+
itself, or use ``regex``): ``members__contains=Var("auth")``. On an edge endpoint such a string raises the
|
|
2350
|
+
lookup's ``ValueError``.
|
|
2226
2351
|
"""
|
|
2227
2352
|
self._reject_time_travel("update_or_create()")
|
|
2228
2353
|
self._reject_subquery_writes(criteria, defaults, "update_or_create")
|
|
@@ -2272,13 +2397,29 @@ class QuerySet:
|
|
|
2272
2397
|
create would have to write — under an ``exact`` lookup, or in ``defaults`` — raises
|
|
2273
2398
|
``SurrealDbError`` before any request.
|
|
2274
2399
|
|
|
2400
|
+
The lookup binds this queryset's ``variables()``, as ``filter()`` does (issue #252; until then a ``Var``
|
|
2401
|
+
criterion read ``NONE`` there): ``objects().variables(n=10).get_or_create(size__gte=Var("n"), …)`` compares
|
|
2402
|
+
``size`` with 10. A subquery criterion's ``variables()`` share the statement: one binding a name of this
|
|
2403
|
+
queryset's to another value raises S7 (``ValueError``) before any request. An ``exact`` ``Var`` criterion
|
|
2404
|
+
naming a variable the lookup binds is written as that variable's value on create:
|
|
2405
|
+
``objects().variables(t="mine").get_or_create(title=Var("t"))`` behaves as ``get_or_create(title="mine")``,
|
|
2406
|
+
and the next identical call returns ``created=False``. On the record id and an edge's ``in``/``out`` it is
|
|
2407
|
+
compared as the record id its value names, as the same criterion given that value is:
|
|
2408
|
+
``variables(a="person:alice").get_or_create(in_=Var("a"), out=bob)`` finds or relates ``person:alice``. A
|
|
2409
|
+
model instance in ``variables()`` is bound and written as its record id (``variables(a=alice)``); an unsaved
|
|
2410
|
+
one raises ``ValueError`` before any request.
|
|
2411
|
+
|
|
2275
2412
|
A ``str`` criterion is data, looked up and written as it is (``owner="$admin"``). A scalar criterion, whatever
|
|
2276
|
-
its lookup, that is ``$`` and the name of a variable
|
|
2413
|
+
its lookup, that is ``$`` and the name of a variable the lookup binds or of one of SurrealDB's session
|
|
2277
2414
|
parameters — ``get_or_create(owner="$auth")``, ``get_or_create(members__contains="$auth", …)`` — raises
|
|
2278
|
-
``SurrealDbError`` before any request (v0.28.1)
|
|
2279
|
-
|
|
2280
|
-
|
|
2281
|
-
|
|
2415
|
+
``SurrealDbError`` before any request (v0.28.1). For a variable, the message names ``Var(...)`` as the
|
|
2416
|
+
criterion to pass, under any lookup but ``like``/``ilike``, which take no ``Var`` (pass the pattern itself,
|
|
2417
|
+
or use ``regex``); for a session parameter, it says to pass the actual value (the record id, or the value
|
|
2418
|
+
itself) under ``exact`` and that ``Var("auth")`` works under any other lookup but ``like``/``ilike``, which
|
|
2419
|
+
take no ``Var`` (pass the pattern itself, or use ``regex``).
|
|
2420
|
+
``get_or_create(owner=Var("auth"))`` returns the signed-in record user's record; when there is none it raises
|
|
2421
|
+
``SurrealDbError``: a session parameter's value is only known to the database and cannot be written, nor can
|
|
2422
|
+
a name no ``variables()`` gives. On an edge endpoint such a string raises the lookup's ``ValueError``.
|
|
2282
2423
|
"""
|
|
2283
2424
|
self._reject_time_travel("get_or_create()")
|
|
2284
2425
|
self._reject_subquery_writes(criteria, defaults, "get_or_create")
|
|
@@ -226,9 +226,6 @@ class SubqueryCompiler:
|
|
|
226
226
|
(``"$x"`` gives ``x``), every subquery's included, in order: ``QuerySet._build_where`` warns for those
|
|
227
227
|
:meth:`names_a_variable` or SurrealDB's session parameters hold once the statement's conditions are
|
|
228
228
|
compiled (v0.28.1).
|
|
229
|
-
outer_variable_names: the ``variables()`` names of the queryset whose ``get_or_create()`` or
|
|
230
|
-
``update_or_create()`` looks up with this statement, which binds none of them: the checks of the filter
|
|
231
|
-
values count them as variables (v0.28.1).
|
|
232
229
|
_stack: the ids of the querysets being rendered, the outer one first (a queryset cannot be its own subquery).
|
|
233
230
|
"""
|
|
234
231
|
|
|
@@ -243,12 +240,11 @@ class SubqueryCompiler:
|
|
|
243
240
|
edge_tables: set[str] = field(default_factory=set)
|
|
244
241
|
warn: bool = True
|
|
245
242
|
variable_like: list[str] = field(default_factory=list)
|
|
246
|
-
outer_variable_names: frozenset[str] = frozenset()
|
|
247
243
|
_stack: list[int] = field(default_factory=list)
|
|
248
244
|
|
|
249
245
|
def names_a_variable(self, name: str) -> bool:
|
|
250
|
-
"""Whether *name* is one of the statement's ``variables()`` so far
|
|
251
|
-
return name in self.variables
|
|
246
|
+
"""Whether *name* is one of the statement's ``variables()`` so far."""
|
|
247
|
+
return name in self.variables
|
|
252
248
|
|
|
253
249
|
def merge_variables(self, variables: Mapping[str, Any]) -> None:
|
|
254
250
|
"""Add a subquery's ``variables()`` to the statement's, in order.
|
|
@@ -10,7 +10,7 @@ import pydantic
|
|
|
10
10
|
|
|
11
11
|
from . import geo as _geo
|
|
12
12
|
from ._sdk import RecordID, SdkRange, ServerError
|
|
13
|
-
from .constants import GEOMETRY_LOOKUP_OPERATORS, LOOKUP_OPERATORS, SESSION_PARAMETERS
|
|
13
|
+
from .constants import GEOMETRY_LOOKUP_OPERATORS, LOOKUP_OPERATORS, SESSION_PARAMETERS, TEXT_LOOKUP_FUNCTIONS
|
|
14
14
|
from .exceptions import SurrealDbError
|
|
15
15
|
from .functions import SurrealFunc, Var
|
|
16
16
|
from .subquery import SubqueryCompiler, inside_a_list, lookup_refused, subquery_condition, subquery_of
|
|
@@ -584,6 +584,81 @@ def _spatial_condition(
|
|
|
584
584
|
return f"{field} {op} ${var_name}", {var_name: _geo._as_geometry(value, lookup)}, counter + 1
|
|
585
585
|
|
|
586
586
|
|
|
587
|
+
#: The characters SurrealDB's ``string::matches`` (the Rust ``regex`` crate) reads as syntax outside a class. A
|
|
588
|
+
#: ``like`` pattern escapes these and no other: a Rust regex refuses some escapes Python's ``re.escape`` writes.
|
|
589
|
+
_REGEX_METACHARACTERS = frozenset("\\.+*?()|[]{}^$")
|
|
590
|
+
|
|
591
|
+
|
|
592
|
+
def _like_regex(pattern: str, *, ignore_case: bool) -> str:
|
|
593
|
+
"""The regular expression of an SQL ``LIKE`` *pattern* (#251), for ``string::matches``.
|
|
594
|
+
|
|
595
|
+
``%`` matches any run of characters, newlines included (``.*`` under ``(?s)``), ``_`` exactly one (``.``), and
|
|
596
|
+
every other character is literal. Anchored at both ends: ``^`` and ``$`` are the text's start and end in a Rust
|
|
597
|
+
regex, never a line's. *ignore_case* (``ilike``) adds ``(?i)``.
|
|
598
|
+
"""
|
|
599
|
+
parts = []
|
|
600
|
+
for char in pattern:
|
|
601
|
+
if char == "%":
|
|
602
|
+
parts.append(".*")
|
|
603
|
+
elif char == "_":
|
|
604
|
+
parts.append(".")
|
|
605
|
+
elif char in _REGEX_METACHARACTERS:
|
|
606
|
+
parts.append("\\" + char)
|
|
607
|
+
else:
|
|
608
|
+
parts.append(char)
|
|
609
|
+
flags = "(?is)" if ignore_case else "(?s)"
|
|
610
|
+
return f"{flags}^{''.join(parts)}$"
|
|
611
|
+
|
|
612
|
+
|
|
613
|
+
def _text_condition(
|
|
614
|
+
field: str, lookup: str, function: str, value: Any, counter: int, subqueries: SubqueryCompiler | None
|
|
615
|
+
) -> tuple[str, dict[str, Any], int]:
|
|
616
|
+
"""The condition of a text lookup (``startswith``, ``endswith``, ``like``, ``ilike``, ``match``, ``regex``; #251).
|
|
617
|
+
|
|
618
|
+
``((<field>).is_string() AND <function>(<field>, $_f<n>))``: the string function alone fails the whole query on
|
|
619
|
+
a record whose field is ``NONE``, ``NULL`` or not a string, and the guard makes such a record never match (and
|
|
620
|
+
match the negation). The method form parses on both lines and on the embedded engine (``type::is::string`` is
|
|
621
|
+
2.x-only, ``type::is_string`` 3.x-only). The parentheses make it test the path's value as a whole: SurrealDB 3.x
|
|
622
|
+
applies ``authors.name.is_string()`` to each element of the array a dotted path through an array of record links
|
|
623
|
+
or objects gives (``[true, true]``, truthy), which then reached the function and failed the query; such a path is
|
|
624
|
+
an array, never matches, and matches the negation on both lines.
|
|
625
|
+
|
|
626
|
+
The value is a ``str`` — data, whatever it starts with, the ``"$$"`` escape unescaped and a variable-like value
|
|
627
|
+
noted as in :func:`build_filter_condition` — or a ``Var`` reference, except for ``like``/``ilike``, whose
|
|
628
|
+
pattern is translated to a regular expression before it is bound (:func:`_like_regex`).
|
|
629
|
+
|
|
630
|
+
Raises:
|
|
631
|
+
ValueError: a ``Var`` given to ``like``/``ilike``, or a value that is neither a ``str`` nor a ``Var``.
|
|
632
|
+
"""
|
|
633
|
+
if isinstance(value, Var):
|
|
634
|
+
if lookup in ("like", "ilike"):
|
|
635
|
+
raise ValueError(
|
|
636
|
+
f"'{lookup}' cannot take a Var: its pattern is translated to a regular expression before it is sent, "
|
|
637
|
+
"and a Var's value is only known to the database. Pass the pattern as a string, or use 'regex' "
|
|
638
|
+
"with a Var holding a regular expression."
|
|
639
|
+
)
|
|
640
|
+
return _guarded(field, function, value.reference), {}, counter
|
|
641
|
+
if not isinstance(value, str):
|
|
642
|
+
raise ValueError(f"'{lookup}' lookup requires a string, got {type(value).__name__}")
|
|
643
|
+
variable_like = VARIABLE_NAME_VALUE.fullmatch(value)
|
|
644
|
+
if subqueries is not None and variable_like is not None:
|
|
645
|
+
subqueries.variable_like.append(variable_like.group(1))
|
|
646
|
+
value = unescape_filter_value(value, warn=subqueries is None or subqueries.warn)
|
|
647
|
+
if lookup in ("like", "ilike"):
|
|
648
|
+
value = _like_regex(value, ignore_case=lookup == "ilike")
|
|
649
|
+
var_name = f"_f{counter}"
|
|
650
|
+
return _guarded(field, function, f"${var_name}"), {var_name: value}, counter + 1
|
|
651
|
+
|
|
652
|
+
|
|
653
|
+
def _guarded(field: str, function: str, argument: str) -> str:
|
|
654
|
+
"""``((<field>).is_string() AND <function>(<field>, <argument>))``, the condition of a text lookup (#251).
|
|
655
|
+
|
|
656
|
+
The path is parenthesised before ``.is_string()``, so a dotted path through an array is tested as the array it
|
|
657
|
+
gives, not element by element (:func:`_text_condition`).
|
|
658
|
+
"""
|
|
659
|
+
return f"(({field}).is_string() AND {function}({field}, {argument}))"
|
|
660
|
+
|
|
661
|
+
|
|
587
662
|
def _list_item(item: Any, field: str, lookup: str) -> Any:
|
|
588
663
|
"""An item of a sequence lookup's list, returned unchanged; a subquery there raises S15 (v0.27.0)."""
|
|
589
664
|
if subquery_of(item) is not None:
|
|
@@ -704,6 +779,13 @@ def build_filter_condition(
|
|
|
704
779
|
geometry object as the ORM value, or a ``Var`` reference. ``outside`` keeps SurrealQL's
|
|
705
780
|
semantics: it also holds for a record whose field is missing or holds no geometry.
|
|
706
781
|
|
|
782
|
+
The text lookups ``startswith``, ``endswith``, ``like``, ``ilike``, ``match`` and ``regex`` (#251,
|
|
783
|
+
``TEXT_LOOKUP_FUNCTIONS``) compile to SurrealQL's string functions, guarded by the field's type
|
|
784
|
+
(:func:`_text_condition`): ``((name).is_string() AND string::starts_with(name, $_f0))``. A record whose field
|
|
785
|
+
is missing, ``NULL`` or not a string (a dotted path through an array included) never matches. ``like``/``ilike``
|
|
786
|
+
bind their pattern translated to an anchored regular expression (:func:`_like_regex`); ``match``/``regex`` bind
|
|
787
|
+
theirs as it is.
|
|
788
|
+
|
|
707
789
|
A subquery (v0.27.0) — a ``Subquery``, or a ``QuerySet`` read as one — given as the whole value is compiled
|
|
708
790
|
by *subqueries*, the statement's compiler (``subquery.subquery_condition``): ``in``, ``not_in``,
|
|
709
791
|
``containsall`` and ``containsany`` compare with all its values, ``exact``, ``gt``, ``gte``, ``lt``, ``lte``,
|
|
@@ -738,9 +820,10 @@ def build_filter_condition(
|
|
|
738
820
|
``Range`` on the ``id`` column or on an endpoint column (v0.23.0) — or a spatial
|
|
739
821
|
lookup gets a value that is not a geometry, or is applied to the ``id`` column or
|
|
740
822
|
to an endpoint column (v0.24.0). ``InvalidGeometryError`` (a ``ValueError``) for a
|
|
741
|
-
malformed GeoJSON object.
|
|
742
|
-
|
|
743
|
-
(
|
|
823
|
+
malformed GeoJSON object. A text lookup given a value that is neither a ``str`` nor a ``Var``, or
|
|
824
|
+
``like``/``ilike`` given a ``Var`` (#251). With a subquery (v0.27.0): a lookup that takes none —
|
|
825
|
+
``isnull``, the text and the spatial lookups — (S2); a subquery as an item of a list (S15); no
|
|
826
|
+
*subqueries* compiler (S8); and the inner queryset's refusals (S3–S7, S13).
|
|
744
827
|
"""
|
|
745
828
|
validate_field_name(field, "filter field")
|
|
746
829
|
sub = subquery_of(value)
|
|
@@ -749,12 +832,10 @@ def build_filter_condition(
|
|
|
749
832
|
if sub is not None:
|
|
750
833
|
raise ValueError(lookup_refused(lookup))
|
|
751
834
|
return _spatial_condition(field, lookup, spatial_op, value, counter, endpoint_columns)
|
|
752
|
-
|
|
753
|
-
if
|
|
835
|
+
text_function = TEXT_LOOKUP_FUNCTIONS.get(lookup)
|
|
836
|
+
if text_function is None and lookup not in LOOKUP_OPERATORS:
|
|
754
837
|
raise ValueError(f"Unsupported lookup type: '{lookup}'")
|
|
755
838
|
|
|
756
|
-
var_name = f"_f{counter}"
|
|
757
|
-
|
|
758
839
|
is_record_id_column = record_table is not None and field == RECORD_ID_COLUMN
|
|
759
840
|
if is_record_id_column and lookup in _RECORD_ID_INVALID_LOOKUPS:
|
|
760
841
|
raise ValueError(
|
|
@@ -766,6 +847,13 @@ def build_filter_condition(
|
|
|
766
847
|
if is_endpoint_column and lookup in _RECORD_ID_INVALID_LOOKUPS:
|
|
767
848
|
raise ValueError(f"'{lookup}' cannot be applied to the edge endpoint column '{field}': it holds a record id, not text.")
|
|
768
849
|
|
|
850
|
+
if text_function is not None:
|
|
851
|
+
if sub is not None:
|
|
852
|
+
raise ValueError(lookup_refused(lookup))
|
|
853
|
+
return _text_condition(field, lookup, text_function, value, counter, subqueries)
|
|
854
|
+
|
|
855
|
+
op = LOOKUP_OPERATORS[lookup]
|
|
856
|
+
var_name = f"_f{counter}"
|
|
769
857
|
if sub is not None:
|
|
770
858
|
return subquery_condition(field, lookup, op, sub, counter, subqueries)
|
|
771
859
|
|
|
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.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/connection_config.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/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
|
{surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/testing/__init__.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/testing/database.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.3}/src/surreal_orm_lite/testing/fixtures.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|