surreal-orm-lite 0.29.0__tar.gz → 0.29.2__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.2}/CHANGELOG.md +49 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/PKG-INFO +46 -5
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/README.md +45 -4
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/pyproject.toml +1 -1
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/__init__.py +1 -1
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/constants.py +15 -6
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/utils.py +96 -8
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/.gitignore +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/LICENSE +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/Makefile +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/_sdk.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/aggregations.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/auth.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/cache.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/changefeed.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/concurrency.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/connection_config.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/connection_manager.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/decoding.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/edge.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/embedded.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/encoding.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/enum.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/exceptions.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/functions.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/geo.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/live.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/model_auth.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/model_base.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/py.typed +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/q.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/query_set.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/routing.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/signals.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/subquery.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/surql_literal.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/testing/__init__.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/testing/database.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/testing/fixtures.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/time_travel.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/transaction.py +0 -0
- {surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/types.py +0 -0
|
@@ -5,6 +5,55 @@ 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.2] - 2026-10-18
|
|
9
|
+
|
|
10
|
+
The text lookups `startswith`, `endswith`, `like`, `ilike`, `match` and `regex` work: each compiles
|
|
11
|
+
to a SurrealQL string function. No new public API.
|
|
12
|
+
|
|
13
|
+
### Fixed
|
|
14
|
+
|
|
15
|
+
- **Text lookups compile to SurrealQL string functions** (#251). They compiled to infix operators
|
|
16
|
+
SurrealQL does not have (`STARTSWITH`, `LIKE`, `REGEX`…), so every such filter was a parse error
|
|
17
|
+
on SurrealDB 2.x, 3.x and the embedded engine, in reads and in live queries. Each now compiles to
|
|
18
|
+
a string function guarded by the field's type, with its value bound:
|
|
19
|
+
`filter(name__startswith="A")` is `((name).is_string() AND string::starts_with(name, $_f0))`.
|
|
20
|
+
- `startswith` and `endswith`: `string::starts_with` and `string::ends_with`.
|
|
21
|
+
- `match` and `regex`: `string::matches`, the regular expression (SurrealDB's syntax, the Rust
|
|
22
|
+
`regex` crate) as given. `match` is a regex lookup, not the full-text `@@` operator: full-text
|
|
23
|
+
search is planned for v0.34.0.
|
|
24
|
+
- `like` and `ilike`: `string::matches` on the pattern translated to an anchored regular
|
|
25
|
+
expression. `%` matches any run of characters (newlines included), `_` exactly one, every other
|
|
26
|
+
character is literal; `ilike` ignores case. The whole value must match: `like="Al"` finds
|
|
27
|
+
`"Al"`, not `"Alice"`.
|
|
28
|
+
- A record whose field is missing (`NONE`), `NULL` or not a string never matches, and the query
|
|
29
|
+
does not fail on it; the negation (`~Q(name__startswith="A")`) matches it. A dotted path
|
|
30
|
+
through an array of record links or objects (`authors.name`) holds an array: it never matches
|
|
31
|
+
either.
|
|
32
|
+
|
|
33
|
+
```python
|
|
34
|
+
await User.objects().filter(name__startswith="A").exec()
|
|
35
|
+
await User.objects().filter(email__ilike="%@EXAMPLE.com").exec() # case-insensitive
|
|
36
|
+
await User.objects().filter(name__regex=r"^\d{3}").exec()
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Changed
|
|
40
|
+
|
|
41
|
+
- **The value of a text lookup must be a `str`** (#251), otherwise `ValueError`. A string starting
|
|
42
|
+
with `$` is data, as for every lookup. `startswith`, `endswith`, `match` and `regex` also take a
|
|
43
|
+
`Var`; `like` and `ilike` raise `ValueError` for one, since their pattern is translated before it
|
|
44
|
+
is sent. These calls were parse errors before, so no call that worked changes.
|
|
45
|
+
|
|
46
|
+
### Notes
|
|
47
|
+
|
|
48
|
+
- Same behaviour on SurrealDB 2.x, 3.x and the embedded engine: the guard is written in the method
|
|
49
|
+
form `(field).is_string()`, which parses on both lines (`type::is::string` parses on 2.x only,
|
|
50
|
+
`type::is_string` on 3.x only). The path is in parentheses because SurrealDB 3.x applies
|
|
51
|
+
`authors.name.is_string()` to each element of the array such a path gives, and the array of
|
|
52
|
+
booleans let the array reach the string function, which failed the query. The README's behaviour
|
|
53
|
+
table has a row for the text lookups.
|
|
54
|
+
- `surreal_orm_lite.constants.LOOKUP_OPERATORS` (internal) no longer lists the text lookups; they
|
|
55
|
+
are in `TEXT_LOOKUP_FUNCTIONS`.
|
|
56
|
+
|
|
8
57
|
## [0.29.0] - 2026-10-18
|
|
9
58
|
|
|
10
59
|
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.2
|
|
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
|
|
@@ -4123,7 +4163,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
4123
4163
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
4124
4164
|
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
4165
|
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.
|
|
4166
|
+
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
4167
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
4128
4168
|
|
|
4129
4169
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -4233,6 +4273,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
4233
4273
|
| `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
4274
|
| `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
4275
|
| 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 |
|
|
4276
|
+
| 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
4277
|
| 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
4278
|
|
|
4238
4279
|
> **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
|
|
@@ -4072,7 +4112,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
|
|
|
4072
4112
|
listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
|
|
4073
4113
|
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
4114
|
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.
|
|
4115
|
+
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
4116
|
The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
|
|
4077
4117
|
|
|
4078
4118
|
| ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
|
|
@@ -4182,6 +4222,7 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
|
|
|
4182
4222
|
| `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
4223
|
| `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
4224
|
| 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 |
|
|
4225
|
+
| 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
4226
|
| 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
4227
|
|
|
4187
4228
|
> **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.
|
|
@@ -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.2}/src/surreal_orm_lite/connection_config.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/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
|
{surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/testing/__init__.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/testing/database.py
RENAMED
|
File without changes
|
{surreal_orm_lite-0.29.0 → surreal_orm_lite-0.29.2}/src/surreal_orm_lite/testing/fixtures.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|