surreal-orm-lite 0.28.0__tar.gz → 0.28.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/CHANGELOG.md +90 -0
  2. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/PKG-INFO +106 -22
  3. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/README.md +105 -21
  4. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/pyproject.toml +1 -1
  5. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/__init__.py +1 -1
  6. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/constants.py +7 -0
  7. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/functions.py +16 -7
  8. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/query_set.py +247 -48
  9. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/subquery.py +17 -5
  10. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/surql_literal.py +9 -6
  11. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/utils.py +180 -35
  12. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/.gitignore +0 -0
  13. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/LICENSE +0 -0
  14. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/Makefile +0 -0
  15. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/_sdk.py +0 -0
  16. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/aggregations.py +0 -0
  17. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/auth.py +0 -0
  18. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/cache.py +0 -0
  19. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/changefeed.py +0 -0
  20. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/concurrency.py +0 -0
  21. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/connection_manager.py +0 -0
  22. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/decoding.py +0 -0
  23. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/edge.py +0 -0
  24. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/embedded.py +0 -0
  25. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/encoding.py +0 -0
  26. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/enum.py +0 -0
  27. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/exceptions.py +0 -0
  28. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/geo.py +0 -0
  29. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/live.py +0 -0
  30. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/model_auth.py +0 -0
  31. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/model_base.py +0 -0
  32. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/py.typed +0 -0
  33. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/q.py +0 -0
  34. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/signals.py +0 -0
  35. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/__init__.py +0 -0
  36. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/database.py +0 -0
  37. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/testing/fixtures.py +0 -0
  38. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/time_travel.py +0 -0
  39. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/transaction.py +0 -0
  40. {surreal_orm_lite-0.28.0 → surreal_orm_lite-0.28.1}/src/surreal_orm_lite/types.py +0 -0
@@ -5,6 +5,96 @@ 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.28.1] - 2026-10-17
9
+
10
+ Query building checks what it is given: `select()` accepts field names and paths, `limit()` and
11
+ `offset()` take a non-negative integer, and a string filter value is always data, with `Var()` as
12
+ the only variable reference. No new public API.
13
+
14
+ ### Changed
15
+
16
+ - **A string filter value is data, whatever its first character** (#250), on every filter path:
17
+ `filter()`, `Q`, `get()`, `first()`, `count()`, `exists()`, `get_or_create()`,
18
+ `update_or_create()`, `bulk_update()` by filter, `cache()`, subqueries and live queries.
19
+ `filter(name="$admin")` compares `name` with the string `"$admin"`, bound like any other value.
20
+ `Var("name")` is the only reference to a query variable, whose value `variables()` gives.
21
+ Migration: where a filter uses the `"$name"` form (deprecated since v0.14.3), write
22
+ `Var("name")`. When a string filter value is exactly `$` followed by the name of a variable of
23
+ `variables()` or of a session parameter (`$access`, `$auth`, `$session`, `$token`), a
24
+ `UserWarning` names the `Var(...)` to write, once per read, pointing at the caller's line; the
25
+ value stays data. Any other string, such as `"$x"` with no variable `x`, is data and nothing
26
+ warns.
27
+
28
+ ```python
29
+ from surreal_orm_lite import Var
30
+
31
+ await User.objects().filter(name="$admin").exec() # the string "$admin"
32
+ await User.objects().filter(age__gte=Var("min_age")).variables(min_age=21).exec() # $min_age
33
+ await Doc.objects().filter(owner=Var("auth")).exec() # SurrealDB's $auth
34
+ ```
35
+
36
+ - **The `"$$"` escape keeps its meaning and is deprecated** (#250): a string filter value starting
37
+ with `$$` loses one `$` (`"$$admin"` finds `"$admin"`) and emits a `DeprecationWarning`; write
38
+ the value with one `$` less. An item of an `in` list never had the escape and is unchanged.
39
+ - **`variables()` refuses `access`, `auth`, `session` and `token`** with a `ValueError` (#250):
40
+ SurrealDB sets these parameters for each session and refuses a query variable of that name. To
41
+ pass your own value, give it another name or put the value itself in the filter:
42
+ `filter(token=Var("device_token")).variables(device_token=t)` or `filter(token=t)`.
43
+ `Var("token")` without `variables()` reads SurrealDB's `$token`, and likewise for the three
44
+ others, in reads and in live queries.
45
+ - **`get_or_create()` and `update_or_create()`** raise `SurrealDbError` before any request when a
46
+ scalar string criterion is exactly `$` followed by the name of a variable of `variables()` or of
47
+ a session parameter, whatever its lookup (#250): pass the actual value as the criterion (the
48
+ record id, or the value itself). Any other `"$name"` string is looked up and written as it is.
49
+ `Var("auth")` finds the signed-in user's record but cannot be written: with no record to return,
50
+ it raises `SurrealDbError`.
51
+ - **`select()` checks its items** like `order_by()` and `values()` (#247): each item is `"*"`, a
52
+ field name (an aliased field by its Python name), a dotted path into a nested object or through a
53
+ record link, or such a path followed by `.*` (`"author.*"`). Anything else raises `ValueError`
54
+ naming the item when `select()` is called, before any request, and the selection in place is
55
+ kept; an item that is not a `str` raises `TypeError`. Write a computed projection with `query()`
56
+ and bound parameters.
57
+ - **`limit()` and `offset()` take a non-negative integer** (#249) of any type with `__index__`
58
+ (an `IntEnum` member, NumPy's `int64`; the parameter is annotated `SupportsIndex`), up to
59
+ `2**63 - 1`. A `bool`, `str`, `float` or `None` raises `TypeError`, a negative value or one above
60
+ `2**63 - 1` `ValueError`, naming the method and the value, when the method is called (for a
61
+ subquery's `limit()` and `offset()` too), before any request; the value in place is kept.
62
+ SurrealDB 2.x and the embedded engine refuse a value above `2**32 - 1` when the read runs;
63
+ SurrealDB 3.x reads it.
64
+ - **Live queries**: `Var("scope")` takes its value from `variables(scope=...)` like any other name
65
+ and raises `SurrealDbError` without it (#250). `$access`, `$auth`, `$session`, `$token`, `$this`
66
+ and `$parent` stay references the server reads on every notification.
67
+
68
+ ### Fixed
69
+
70
+ - On an edge's `in` and `out`, which hold record ids, a string that is `$` followed by the name of
71
+ a variable of `variables()` or of a session parameter raises a `ValueError` whose message names
72
+ the `Var(...)` to write (#250).
73
+ - Each warning of a filter value is emitted once per read: the second compilation of a `cache()`
74
+ miss and the re-send of a subquery over a missing table stay quiet, for the `"$$"`
75
+ `DeprecationWarning` too (#250).
76
+
77
+ ### Removed
78
+
79
+ - `utils.remove_quotes_for_variables()` and `utils.VALID_VARIABLE_REF_PATTERN`, internal helpers
80
+ that were never in `__all__`.
81
+
82
+ ### Notes
83
+
84
+ - **SurrealDB 2.x vs 3.x**: string filter values and `Var()` behave the same on both lines and on
85
+ the embedded engine. `select("meta.*")` on a nested object that is not a record link gives the
86
+ object on 3.x and its values as a list on 2.x and the embedded engine (through a link, the linked
87
+ record on both). A `limit()` or `offset()` above `2**32 - 1` is refused by SurrealDB 2.x and the
88
+ embedded engine when the read runs, and read by 3.x.
89
+ - **Docs**: the README section "String filter values and `Var()`" replaces "Filter values that
90
+ start with `$`"; new parts "What `select()` accepts" and "`limit()` and `offset()`"; the
91
+ live-query, subquery and query-cache invalidation notes match; three rows in the 2.x/3.x behaviour
92
+ table (string filter values, a nested object's `.*`, `LIMIT`/`START` above `2**32 - 1`). The
93
+ `getting_started` notebook reads `SURREALDB_HOST` and `SURREALDB_PORT`; the v0.14.3 notebook says
94
+ the `"$$"` escape is deprecated since v0.28.1.
95
+ - **Server pins unchanged**: tested against SurrealDB 3.3.4 and 2.7.0, and on the embedded engine,
96
+ plus 3.1.5 for backward compatibility (identical).
97
+
8
98
  ## [0.28.0] - 2026-10-17
9
99
 
10
100
  Query cache: a QuerySet serves its reads from a client-side cache with `cache(ttl)`, and every ORM
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: surreal-orm-lite
3
- Version: 0.28.0
3
+ Version: 0.28.1
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
@@ -180,6 +180,43 @@ results = await User.objects().query(
180
180
  )
181
181
  ```
182
182
 
183
+ #### What `select()` accepts
184
+
185
+ ```python
186
+ await Book.objects().select("title", "price").exec() # field names
187
+ await Book.objects().select("title", "author.name").exec() # [{"title": "Dune", "author": {"name": "Ada"}}, …]
188
+ await Book.objects().select("title", "author.*").exec() # every field of the linked author
189
+ await Book.objects().select("*", "author.*").exec() # every field, the author's record included
190
+ ```
191
+
192
+ Each item is `*`, a field name (an aliased field by its Python name: its column is selected), a
193
+ dotted path into a nested object or through a record link, or such a path followed by `.*`. Names
194
+ are letters, digits and underscores, each part starting with a letter or an underscore, as in
195
+ `order_by()` and `values()`. Anything else — an expression, a function call, `AS`, `{…}` or
196
+ `[…]` — raises `ValueError` naming the item when `select()` is called, before any request; write a
197
+ computed projection with `query()` and bound parameters. Rows that do not validate as the model (a
198
+ link read as a record, a required field left out) come back as dicts keyed by Python names. On a
199
+ nested object that is not a link, `"meta.*"` gives the object on SurrealDB 3.x and its values as a
200
+ list on 2.x and the embedded engine.
201
+
202
+ #### `limit()` and `offset()`
203
+
204
+ ```python
205
+ users = await User.objects().order_by("name").limit(10).offset(20).exec()
206
+ User.objects().limit(int(size)) # a size read as text: convert it first
207
+ User.objects().limit("10") # TypeError: limit() takes a non-negative integer, got '10'
208
+ User.objects().offset(-1) # ValueError: offset() takes a non-negative integer, got -1
209
+ ```
210
+
211
+ Each takes a non-negative integer (`0` reads no record; an `IntEnum` member or an integer type
212
+ such as NumPy's `int64` gives its value). A value that is not an integer — a `bool`, a `str` such
213
+ as `"10"`, a `float`, `None` — raises `TypeError`, and a negative one or one above `2**63 - 1`
214
+ (SurrealQL's largest integer) `ValueError`, naming the method and the value, when `limit()` or
215
+ `offset()` is called, before any request; the value in place is kept. The same holds wherever the
216
+ queryset is read: `exec()`, `first()`, `get()`, `values(…).annotate(…)`, `cache()`, `as_of()` and
217
+ a subquery. The server may still refuse a large value when the read runs: SurrealDB 2.x and the
218
+ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads it.
219
+
183
220
  ---
184
221
 
185
222
  ## Features
@@ -273,23 +310,64 @@ await User.objects().filter(id__startswith="al").exec()
273
310
  A model that aliases its identity through `primary_key` keeps that alias as an ordinary
274
311
  column, so `filter(code="abc")` is a normal string comparison and is unaffected.
275
312
 
276
- #### Filter values that start with `$`
277
-
278
- A filter value beginning with `$` is read as a reference to a **query variable**, not as data.
279
- Use `Var(...)` to say so explicitly, and `$$` to escape a value that genuinely starts with a
280
- dollar sign:
313
+ #### String filter values and `Var()`
281
314
 
282
315
  ```python
283
316
  from surreal_orm_lite import Var
284
317
 
285
- await User.objects().filter(age__gte=Var("min_age")).exec() # … WHERE age >= $min_age
286
- await User.objects().filter(name="$$admin").exec() # matches the literal "$admin"
287
- await User.objects().filter(name="$admin").exec() # deprecated: reads as $admin
318
+ await User.objects().filter(name="$admin").exec() # the string "$admin"
319
+ await User.objects().filter(age__gte=Var("min_age")).variables(min_age=21).exec() # … WHERE age >= $min_age
320
+ ```
321
+
322
+ A string filter value is data, whatever it starts with: `filter(name="$admin")` compares `name`
323
+ with the string `"$admin"`, bound like any other value, wherever a filter applies: `filter()`, `Q`,
324
+ `get()`, `get_or_create()`, `update_or_create()`, `bulk_update()` by filter, subqueries and live
325
+ queries. `Var(...)` is the only way to reference a query variable, whose value `variables()`
326
+ gives.
327
+
328
+ Until v0.28.1 a value starting with `$` was read as a variable reference (deprecated since
329
+ v0.14.3), and `"$$admin"` was how to write the string `"$admin"`. That escape keeps its meaning,
330
+ deprecated: a filter value starting with `$$` loses one `$` (`"$$admin"` finds `"$admin"`: write
331
+ `"$admin"`), with a `DeprecationWarning`; an item of an `in` list never had the escape.
332
+
333
+ A call written for the old reading, such as `filter(age__lte="$max_age").variables(max_age=25)`,
334
+ now compares `age` with the string `"$max_age"`: a number sorts below a string, so `lt` and `lte`
335
+ match every number, and `gt`, `gte` and `exact` none. When a string filter value is exactly `$`
336
+ followed by the name of a variable that `variables()` gives, the ORM keeps it as data and emits a
337
+ `UserWarning` that says to write `Var("max_age")`, once per read, pointing at your line.
338
+
339
+ `Var()` also reads the parameters SurrealDB sets for each session, without `variables()`: `$auth`
340
+ (the signed-in record user), `$access`, `$session` and `$token`, in reads and in live queries.
341
+
342
+ ```python
343
+ mine = await Doc.objects().filter(owner=Var("auth")).exec() # … WHERE owner = $auth
288
344
  ```
289
345
 
290
- The bare `"$admin"` form still works for backward compatibility but emits a `DeprecationWarning`:
291
- it silently matches nothing when the value is really meant as data, which is a trap for
292
- user-supplied strings. Prefer `Var(...)` in new code.
346
+ The string `"$auth"` is data: `filter(owner="$auth")` compares `owner` with the string `"$auth"`,
347
+ so a read keeps only the records whose `owner` is that string, and a live query notifies only for
348
+ those. A string filter value that is exactly `"$auth"`, `"$access"`, `"$session"` or `"$token"`
349
+ emits a `UserWarning` naming the `Var(...)` that reads the parameter, once per read, pointing at
350
+ your line. Any other string, such as `"$x"` with no variable `x`, is data the caller meant: no
351
+ warning. On an edge's `in` and `out`, which hold record ids, such a string is not a record id and
352
+ raises `ValueError`; when it names a variable of `variables()` or one of these parameters, the
353
+ message names the `Var(...)` to write.
354
+
355
+ `get_or_create()` and `update_or_create()` look up their criteria and write the `exact` ones on
356
+ create, so there such a string is refused: `update_or_create(owner="$auth", defaults=…)` would find
357
+ and write the record whose `owner` is the string `"$auth"`, the same record for every record user,
358
+ and `members__contains="$auth"` would look for the string. A criterion that is exactly `$` followed
359
+ by the name of a variable of `variables()` or of one of these parameters raises `SurrealDbError`
360
+ before any request, whatever its lookup, saying to pass the actual value as the criterion: the
361
+ record id, or the value itself. `Var("auth")` finds the signed-in user's record
362
+ (`get_or_create(owner=Var("auth"))` returns it) but cannot be written: with no record to return, it
363
+ raises `SurrealDbError`. Any other string, such as `"$admin"`, is looked up and written as it is. On
364
+ an edge's `in` and `out`, such a criterion raises the `ValueError` above.
365
+
366
+ `variables()` refuses these four names with a `ValueError`: SurrealDB sets them for each session
367
+ and refuses a query variable of that name. To pass your own value, give it another name, or pass
368
+ the value itself in the filter: `filter(token=Var("device_token")).variables(device_token=t)` or
369
+ `filter(token=t)`, in a read or a live query. `Var("token")` without `variables()` reads SurrealDB's
370
+ `$token`.
293
371
 
294
372
  #### Model instances as filter values
295
373
 
@@ -1342,8 +1420,12 @@ else, a string containing a NUL character, an integer beyond 64 bits, a `Decimal
1342
1420
  round or a zero, negative or oversized duration raises `TypeError` when you call `live()`, before
1343
1421
  anything is sent. A `Var` must be supplied through `variables()` — an unbound reference would read
1344
1422
  as `NONE` on every notification, so `age > $min_age` would match every record; it raises
1345
- `SurrealDbError` instead (server parameters such as `$auth` and `$session` are allowed). Every
1346
- other query keeps binding parameters.
1423
+ `SurrealDbError` instead. SurrealDB's own parameters need no `variables()`: `Var("auth")` (and
1424
+ `$access`, `$session`, `$token`) stays a reference the server reads on every notification, so
1425
+ `filter(owner=Var("auth"))` streams the signed-in record user's own records, on both lines; the
1426
+ string `"$auth"` is data, written as `'$auth'` (see
1427
+ [String filter values and `Var()`](#string-filter-values-and-var)). Every other query keeps binding
1428
+ parameters.
1347
1429
 
1348
1430
  #### Diff mode
1349
1431
 
@@ -3346,7 +3428,8 @@ A statement with subqueries is one block, whose `LET`s bind each subquery once,
3346
3428
  - **Reserved names**: `$_sq0`, `$_sq1`, … (`_sq<N>`) are the block's `LET`s and hide a
3347
3429
  `variables()` value of the same name; a subquery can order by `_sqv` only when it selects `_sqv`
3348
3430
  itself (`ValueError` otherwise).
3349
- - `limit()` and `offset()` of a subquery take an `int >= 0` (`ValueError` otherwise).
3431
+ - `limit()` and `offset()` of a subquery take a non-negative integer, as everywhere (`TypeError` or
3432
+ `ValueError` when they are called).
3350
3433
 
3351
3434
  #### Where subqueries apply
3352
3435
 
@@ -3408,8 +3491,7 @@ at the call):
3408
3491
  - an inner `objects(tx=)` whose transaction is not the outer queryset's: `SurrealDbError`;
3409
3492
  - an inner `variables()` binding a name of the statement to another value: `ValueError` (the two
3410
3493
  values must have the same type and be equal: `1` and `True`, or `1` and `1.0`, differ);
3411
- - an inner `limit()` or `offset()` that is not an `int >= 0`, or an inner `order_by()` on `_sqv`
3412
- (above): `ValueError`;
3494
+ - an inner `order_by()` on `_sqv` (above): `ValueError`;
3413
3495
  - a subquery inside a list (`author__in=[Subquery(qs)]`): `ValueError`, give it as the whole value;
3414
3496
  - `Q(...).to_sql()` called on its own with a subquery lookup: `ValueError` (only a QuerySet binds
3415
3497
  a subquery);
@@ -3530,8 +3612,8 @@ Every ORM write removes the cached reads it can change, **before** its `post_*`
3530
3612
  included.
3531
3613
  - A read that **follows links** is removed by **any** ORM write: `fetch()`, a dotted path such as
3532
3614
  `filter(**{"author.name": …})` or `order_by("author.name")` (in a subquery too), and a
3533
- `select()` item that is not a plain field, such as `"author.*"` or an expression (a projection
3534
- may read another table).
3615
+ `select()` item that is not a plain field, such as `"author.*"` (the projection reads the linked
3616
+ record).
3535
3617
  - A read of an **edge model** (`BaseSurrealEdge`) is removed by any delete: deleting a record
3536
3618
  deletes the edges that point at it or from it.
3537
3619
  - Inside `transaction()` the tables written are invalidated **at commit** (a failed commit too,
@@ -3553,8 +3635,7 @@ table's entries after such a change:
3553
3635
  - what the server derives on its own: `DEFINE EVENT`, `REFERENCE … ON DELETE` (3.x), views
3554
3636
  (`DEFINE TABLE … AS SELECT`), `PERMISSIONS` that read another table;
3555
3637
  - values computed when the read runs: a `DEFINE PARAM` read with `Var()`, `<future>`/`COMPUTED`
3556
- fields (over another table, the graph such as `count(<-likes)`, or the time), time functions
3557
- inside a `select()` expression;
3638
+ fields (over another table, the graph such as `count(<-likes)`, or the time);
3558
3639
  - a table of relations read through a model that is not a `BaseSurrealEdge`.
3559
3640
 
3560
3641
  ```python
@@ -3772,7 +3853,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
3772
3853
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
3773
3854
  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
3774
3855
  otherwise. The full suite and every divergence below were re-verified on both new versions.
3775
- 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.
3856
+ 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.
3776
3857
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
3777
3858
 
3778
3859
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -3878,6 +3959,9 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
3878
3959
  | A subquery reading a table that does not exist | read as empty, like any missing table | read as empty in three requests (statement, table probe, re-send); other errors, even ones quoting "does not exist", are relayed; transaction writes fail; `live()` raises on start | v0.27.0 |
3879
3960
  | Subqueries under `as_of()` | each subquery reads at the same moment: the ORM adds `VERSION` to it (the server would read the current state) | the same (the server applies the outer `VERSION` to an inline sub-SELECT only); without versioned storage `SurrealDbError`, but 3.1.5 raises the server's own `ThrownError` | v0.27.0 |
3880
3961
  | Query cache (`cache()`, `QueryCache`) | same on both lines: client-side, per connection and identity; writes in a transaction invalidate at commit; reads in one are never cached (on 2.x they raise: buffered) | the same; reads inside an interactive transaction are never cached (they see its uncommitted writes) | v0.28.0 |
3962
+ | `select("meta.*")` on a nested object that is not a record link | its values, as a list; through a link (`select("author.*")`), the linked record | the object; through a link, the linked record | pre-existing (documented in v0.28.1) |
3963
+ | `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 |
3964
+ | `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) |
3881
3965
  | 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 |
3882
3966
 
3883
3967
  > **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.
@@ -129,6 +129,43 @@ results = await User.objects().query(
129
129
  )
130
130
  ```
131
131
 
132
+ #### What `select()` accepts
133
+
134
+ ```python
135
+ await Book.objects().select("title", "price").exec() # field names
136
+ await Book.objects().select("title", "author.name").exec() # [{"title": "Dune", "author": {"name": "Ada"}}, …]
137
+ await Book.objects().select("title", "author.*").exec() # every field of the linked author
138
+ await Book.objects().select("*", "author.*").exec() # every field, the author's record included
139
+ ```
140
+
141
+ Each item is `*`, a field name (an aliased field by its Python name: its column is selected), a
142
+ dotted path into a nested object or through a record link, or such a path followed by `.*`. Names
143
+ are letters, digits and underscores, each part starting with a letter or an underscore, as in
144
+ `order_by()` and `values()`. Anything else — an expression, a function call, `AS`, `{…}` or
145
+ `[…]` — raises `ValueError` naming the item when `select()` is called, before any request; write a
146
+ computed projection with `query()` and bound parameters. Rows that do not validate as the model (a
147
+ link read as a record, a required field left out) come back as dicts keyed by Python names. On a
148
+ nested object that is not a link, `"meta.*"` gives the object on SurrealDB 3.x and its values as a
149
+ list on 2.x and the embedded engine.
150
+
151
+ #### `limit()` and `offset()`
152
+
153
+ ```python
154
+ users = await User.objects().order_by("name").limit(10).offset(20).exec()
155
+ User.objects().limit(int(size)) # a size read as text: convert it first
156
+ User.objects().limit("10") # TypeError: limit() takes a non-negative integer, got '10'
157
+ User.objects().offset(-1) # ValueError: offset() takes a non-negative integer, got -1
158
+ ```
159
+
160
+ Each takes a non-negative integer (`0` reads no record; an `IntEnum` member or an integer type
161
+ such as NumPy's `int64` gives its value). A value that is not an integer — a `bool`, a `str` such
162
+ as `"10"`, a `float`, `None` — raises `TypeError`, and a negative one or one above `2**63 - 1`
163
+ (SurrealQL's largest integer) `ValueError`, naming the method and the value, when `limit()` or
164
+ `offset()` is called, before any request; the value in place is kept. The same holds wherever the
165
+ queryset is read: `exec()`, `first()`, `get()`, `values(…).annotate(…)`, `cache()`, `as_of()` and
166
+ a subquery. The server may still refuse a large value when the read runs: SurrealDB 2.x and the
167
+ embedded engine refuse one above `4294967295` (`2**32 - 1`), SurrealDB 3.x reads it.
168
+
132
169
  ---
133
170
 
134
171
  ## Features
@@ -222,23 +259,64 @@ await User.objects().filter(id__startswith="al").exec()
222
259
  A model that aliases its identity through `primary_key` keeps that alias as an ordinary
223
260
  column, so `filter(code="abc")` is a normal string comparison and is unaffected.
224
261
 
225
- #### Filter values that start with `$`
226
-
227
- A filter value beginning with `$` is read as a reference to a **query variable**, not as data.
228
- Use `Var(...)` to say so explicitly, and `$$` to escape a value that genuinely starts with a
229
- dollar sign:
262
+ #### String filter values and `Var()`
230
263
 
231
264
  ```python
232
265
  from surreal_orm_lite import Var
233
266
 
234
- await User.objects().filter(age__gte=Var("min_age")).exec() # … WHERE age >= $min_age
235
- await User.objects().filter(name="$$admin").exec() # matches the literal "$admin"
236
- await User.objects().filter(name="$admin").exec() # deprecated: reads as $admin
267
+ await User.objects().filter(name="$admin").exec() # the string "$admin"
268
+ await User.objects().filter(age__gte=Var("min_age")).variables(min_age=21).exec() # … WHERE age >= $min_age
269
+ ```
270
+
271
+ A string filter value is data, whatever it starts with: `filter(name="$admin")` compares `name`
272
+ with the string `"$admin"`, bound like any other value, wherever a filter applies: `filter()`, `Q`,
273
+ `get()`, `get_or_create()`, `update_or_create()`, `bulk_update()` by filter, subqueries and live
274
+ queries. `Var(...)` is the only way to reference a query variable, whose value `variables()`
275
+ gives.
276
+
277
+ Until v0.28.1 a value starting with `$` was read as a variable reference (deprecated since
278
+ v0.14.3), and `"$$admin"` was how to write the string `"$admin"`. That escape keeps its meaning,
279
+ deprecated: a filter value starting with `$$` loses one `$` (`"$$admin"` finds `"$admin"`: write
280
+ `"$admin"`), with a `DeprecationWarning`; an item of an `in` list never had the escape.
281
+
282
+ A call written for the old reading, such as `filter(age__lte="$max_age").variables(max_age=25)`,
283
+ now compares `age` with the string `"$max_age"`: a number sorts below a string, so `lt` and `lte`
284
+ match every number, and `gt`, `gte` and `exact` none. When a string filter value is exactly `$`
285
+ followed by the name of a variable that `variables()` gives, the ORM keeps it as data and emits a
286
+ `UserWarning` that says to write `Var("max_age")`, once per read, pointing at your line.
287
+
288
+ `Var()` also reads the parameters SurrealDB sets for each session, without `variables()`: `$auth`
289
+ (the signed-in record user), `$access`, `$session` and `$token`, in reads and in live queries.
290
+
291
+ ```python
292
+ mine = await Doc.objects().filter(owner=Var("auth")).exec() # … WHERE owner = $auth
237
293
  ```
238
294
 
239
- The bare `"$admin"` form still works for backward compatibility but emits a `DeprecationWarning`:
240
- it silently matches nothing when the value is really meant as data, which is a trap for
241
- user-supplied strings. Prefer `Var(...)` in new code.
295
+ The string `"$auth"` is data: `filter(owner="$auth")` compares `owner` with the string `"$auth"`,
296
+ so a read keeps only the records whose `owner` is that string, and a live query notifies only for
297
+ those. A string filter value that is exactly `"$auth"`, `"$access"`, `"$session"` or `"$token"`
298
+ emits a `UserWarning` naming the `Var(...)` that reads the parameter, once per read, pointing at
299
+ your line. Any other string, such as `"$x"` with no variable `x`, is data the caller meant: no
300
+ warning. On an edge's `in` and `out`, which hold record ids, such a string is not a record id and
301
+ raises `ValueError`; when it names a variable of `variables()` or one of these parameters, the
302
+ message names the `Var(...)` to write.
303
+
304
+ `get_or_create()` and `update_or_create()` look up their criteria and write the `exact` ones on
305
+ create, so there such a string is refused: `update_or_create(owner="$auth", defaults=…)` would find
306
+ and write the record whose `owner` is the string `"$auth"`, the same record for every record user,
307
+ and `members__contains="$auth"` would look for the string. A criterion that is exactly `$` followed
308
+ by the name of a variable of `variables()` or of one of these parameters raises `SurrealDbError`
309
+ before any request, whatever its lookup, saying to pass the actual value as the criterion: the
310
+ record id, or the value itself. `Var("auth")` finds the signed-in user's record
311
+ (`get_or_create(owner=Var("auth"))` returns it) but cannot be written: with no record to return, it
312
+ raises `SurrealDbError`. Any other string, such as `"$admin"`, is looked up and written as it is. On
313
+ an edge's `in` and `out`, such a criterion raises the `ValueError` above.
314
+
315
+ `variables()` refuses these four names with a `ValueError`: SurrealDB sets them for each session
316
+ and refuses a query variable of that name. To pass your own value, give it another name, or pass
317
+ the value itself in the filter: `filter(token=Var("device_token")).variables(device_token=t)` or
318
+ `filter(token=t)`, in a read or a live query. `Var("token")` without `variables()` reads SurrealDB's
319
+ `$token`.
242
320
 
243
321
  #### Model instances as filter values
244
322
 
@@ -1291,8 +1369,12 @@ else, a string containing a NUL character, an integer beyond 64 bits, a `Decimal
1291
1369
  round or a zero, negative or oversized duration raises `TypeError` when you call `live()`, before
1292
1370
  anything is sent. A `Var` must be supplied through `variables()` — an unbound reference would read
1293
1371
  as `NONE` on every notification, so `age > $min_age` would match every record; it raises
1294
- `SurrealDbError` instead (server parameters such as `$auth` and `$session` are allowed). Every
1295
- other query keeps binding parameters.
1372
+ `SurrealDbError` instead. SurrealDB's own parameters need no `variables()`: `Var("auth")` (and
1373
+ `$access`, `$session`, `$token`) stays a reference the server reads on every notification, so
1374
+ `filter(owner=Var("auth"))` streams the signed-in record user's own records, on both lines; the
1375
+ string `"$auth"` is data, written as `'$auth'` (see
1376
+ [String filter values and `Var()`](#string-filter-values-and-var)). Every other query keeps binding
1377
+ parameters.
1296
1378
 
1297
1379
  #### Diff mode
1298
1380
 
@@ -3295,7 +3377,8 @@ A statement with subqueries is one block, whose `LET`s bind each subquery once,
3295
3377
  - **Reserved names**: `$_sq0`, `$_sq1`, … (`_sq<N>`) are the block's `LET`s and hide a
3296
3378
  `variables()` value of the same name; a subquery can order by `_sqv` only when it selects `_sqv`
3297
3379
  itself (`ValueError` otherwise).
3298
- - `limit()` and `offset()` of a subquery take an `int >= 0` (`ValueError` otherwise).
3380
+ - `limit()` and `offset()` of a subquery take a non-negative integer, as everywhere (`TypeError` or
3381
+ `ValueError` when they are called).
3299
3382
 
3300
3383
  #### Where subqueries apply
3301
3384
 
@@ -3357,8 +3440,7 @@ at the call):
3357
3440
  - an inner `objects(tx=)` whose transaction is not the outer queryset's: `SurrealDbError`;
3358
3441
  - an inner `variables()` binding a name of the statement to another value: `ValueError` (the two
3359
3442
  values must have the same type and be equal: `1` and `True`, or `1` and `1.0`, differ);
3360
- - an inner `limit()` or `offset()` that is not an `int >= 0`, or an inner `order_by()` on `_sqv`
3361
- (above): `ValueError`;
3443
+ - an inner `order_by()` on `_sqv` (above): `ValueError`;
3362
3444
  - a subquery inside a list (`author__in=[Subquery(qs)]`): `ValueError`, give it as the whole value;
3363
3445
  - `Q(...).to_sql()` called on its own with a subquery lookup: `ValueError` (only a QuerySet binds
3364
3446
  a subquery);
@@ -3479,8 +3561,8 @@ Every ORM write removes the cached reads it can change, **before** its `post_*`
3479
3561
  included.
3480
3562
  - A read that **follows links** is removed by **any** ORM write: `fetch()`, a dotted path such as
3481
3563
  `filter(**{"author.name": …})` or `order_by("author.name")` (in a subquery too), and a
3482
- `select()` item that is not a plain field, such as `"author.*"` or an expression (a projection
3483
- may read another table).
3564
+ `select()` item that is not a plain field, such as `"author.*"` (the projection reads the linked
3565
+ record).
3484
3566
  - A read of an **edge model** (`BaseSurrealEdge`) is removed by any delete: deleting a record
3485
3567
  deletes the edges that point at it or from it.
3486
3568
  - Inside `transaction()` the tables written are invalidated **at commit** (a failed commit too,
@@ -3502,8 +3584,7 @@ table's entries after such a change:
3502
3584
  - what the server derives on its own: `DEFINE EVENT`, `REFERENCE … ON DELETE` (3.x), views
3503
3585
  (`DEFINE TABLE … AS SELECT`), `PERMISSIONS` that read another table;
3504
3586
  - values computed when the read runs: a `DEFINE PARAM` read with `Var()`, `<future>`/`COMPUTED`
3505
- fields (over another table, the graph such as `count(<-likes)`, or the time), time functions
3506
- inside a `select()` expression;
3587
+ fields (over another table, the graph such as `count(<-likes)`, or the time);
3507
3588
  - a table of relations read through a model that is not a `BaseSurrealEdge`.
3508
3589
 
3509
3590
  ```python
@@ -3721,7 +3802,7 @@ features introduced in SurrealDB 3.x. On 2.x the ORM degrades gracefully. Capabi
3721
3802
  listed behave the same on both lines. The 2.x column was measured on 2.6.5 and holds unchanged
3722
3803
  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
3723
3804
  otherwise. The full suite and every divergence below were re-verified on both new versions.
3724
- 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.
3805
+ 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.
3725
3806
  The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded engine](#orm-behaviour-the-embedded-engine).
3726
3807
 
3727
3808
  | ORM capability | SurrealDB 2.6.x / 2.7.x | SurrealDB 3.2.x / 3.3.x | Since |
@@ -3827,6 +3908,9 @@ The SDK's in-process engine has a table of its own: [ORM behaviour: the embedded
3827
3908
  | A subquery reading a table that does not exist | read as empty, like any missing table | read as empty in three requests (statement, table probe, re-send); other errors, even ones quoting "does not exist", are relayed; transaction writes fail; `live()` raises on start | v0.27.0 |
3828
3909
  | Subqueries under `as_of()` | each subquery reads at the same moment: the ORM adds `VERSION` to it (the server would read the current state) | the same (the server applies the outer `VERSION` to an inline sub-SELECT only); without versioned storage `SurrealDbError`, but 3.1.5 raises the server's own `ThrownError` | v0.27.0 |
3829
3910
  | Query cache (`cache()`, `QueryCache`) | same on both lines: client-side, per connection and identity; writes in a transaction invalidate at commit; reads in one are never cached (on 2.x they raise: buffered) | the same; reads inside an interactive transaction are never cached (they see its uncommitted writes) | v0.28.0 |
3911
+ | `select("meta.*")` on a nested object that is not a record link | its values, as a list; through a link (`select("author.*")`), the linked record | the object; through a link, the linked record | pre-existing (documented in v0.28.1) |
3912
+ | `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 |
3913
+ | `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) |
3830
3914
  | 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 |
3831
3915
 
3832
3916
  > **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,6 +1,6 @@
1
1
  [project]
2
2
  name = "surreal-orm-lite"
3
- version = "0.28.0"
3
+ version = "0.28.1"
4
4
  description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"
@@ -1,4 +1,4 @@
1
- __version__ = "0.28.0"
1
+ __version__ = "0.28.1"
2
2
 
3
3
  from ._sdk import BoundExcluded, BoundIncluded
4
4
  from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
@@ -27,3 +27,10 @@ GEOMETRY_LOOKUP_OPERATORS = {
27
27
  "outside": "OUTSIDE",
28
28
  "intersects": "INTERSECTS",
29
29
  }
30
+
31
+ #: SurrealDB's session parameters (v0.28.1): ``$access``, ``$auth``, ``$session`` and ``$token``. The server sets them
32
+ #: for every session and refuses ``LET`` on them (its protected parameters; measured on 2.7.0 and 3.3.4), so a filter
33
+ #: reads them with ``Var("auth")`` and no ``variables()``. A ``str`` filter value ``"$auth"`` is data, with a
34
+ #: ``UserWarning`` (``utils.warn_on_variable_names``). The statement parameters (``$this``, ``$parent``, ``$value``,
35
+ #: ``$before``, ``$after``, ``$input``, ``$event``) and the 1.x ``$scope`` are not session values: not listed.
36
+ SESSION_PARAMETERS = frozenset({"access", "auth", "session", "token"})
@@ -233,19 +233,28 @@ def computed(expression: "str | SurrealFunc") -> Any:
233
233
 
234
234
 
235
235
  class Var:
236
- """An explicit reference to a **bound query variable** in a filter (v0.14.3).
236
+ """A reference to a **bound query variable** in a filter (v0.14.3): the only one.
237
237
 
238
- ``filter()`` has always read a string starting with ``$`` as a variable reference, which
239
- makes a literal value like ``"$admin"`` impossible to express and turns any user-supplied
240
- string into an accidental reference. ``Var`` states the intent instead of inferring it::
238
+ A string filter value is data, whatever it starts with: ``filter(name="$admin")`` compares
239
+ ``name`` with the string ``"$admin"``. ``Var`` is how a filter reads a query variable
240
+ instead::
241
241
 
242
242
  from surreal_orm_lite import Var
243
243
 
244
244
  qs = User.objects().filter(age__gte=Var("min_age")) # … WHERE age >= $min_age
245
+ await qs.variables(min_age=21).exec()
245
246
 
246
- The variable itself is supplied at execution time, exactly as before. Plain strings
247
- beginning with ``$`` still work but are deprecated; write ``"$$admin"`` to filter on a
248
- literal that starts with a dollar sign.
247
+ The variable itself is supplied with ``variables()``. A leading ``$`` in the name is
248
+ accepted: ``Var("$min_age")`` is ``Var("min_age")``.
249
+
250
+ ``Var`` also reads the parameters SurrealDB sets for the session — ``$auth`` (the signed-in
251
+ record user), ``$access``, ``$session``, ``$token`` — with no ``variables()``, in a read and in
252
+ a live query::
253
+
254
+ mine = await Doc.objects().filter(owner=Var("auth")).exec() # … WHERE owner = $auth
255
+
256
+ The string ``"$auth"`` is data: ``filter(owner="$auth")`` compares ``owner`` with the string
257
+ ``"$auth"``, with a ``UserWarning`` naming ``Var("auth")``.
249
258
  """
250
259
 
251
260
  __slots__ = ("name",)