fennecdb 0.2.0__py3-none-any.whl

fennecdb/builder.py

@@ -0,0 +1,1867 @@
+"""The query builder: FennecQL text and its parameters from a chain of calls.
+
+    rows = (db.collection("docs")
+              .select("title")
+              .where("year", ">=", 2024)
+              .near("embed", vector, ef=64)
+              .limit(5)
+              .rows())
+
+It makes the text web/fennec.js's builder makes of the same chain, to the
+byte, and so do the Go and .NET builders: integrations/builder-golden.json
+holds the chains and what each must make, and every builder's tests run
+it. Every value goes in as a parameter; a name -- a collection, a field, a
+path into a json field -- cannot, so names are checked against FennecQL's
+own rule, and that check is the injection boundary.
+
+A query is immutable: each call hands back a new one, so a base query can
+be kept and branched from. `to_fennecql()` is the text and its parameters,
+for logging or another transport; `rows()`, `first()`, `count()` and
+`explain()` send it through the client the query came from, and on an
+`AsyncClient` they are awaited.
+
+`call` is a named statement's: `call("transfer", {"from": 1, "to": 2,
+"amount": 300}).to_call()` is `("call transfer $1", [{...}])`, the
+arguments one parameter and the name -- the one thing written into the
+text -- checked.
+"""
+
+from __future__ import annotations
+
+import array
+import json
+import math
+import re
+import unicodedata
+from datetime import datetime, timezone
+from typing import Any, Iterable, Mapping, NamedTuple, Sequence, TypeVar
+
+__all__ = [
+    "AsyncQuery",
+    "Call",
+    "Computed",
+    "Cond",
+    "FacetCount",
+    "Param",
+    "Query",
+    "Rows",
+    "and_",
+    "bucket",
+    "call",
+    "collection",
+    "count_distinct",
+    "distance",
+    "expr",
+    "first",
+    "inc",
+    "last",
+    "not_",
+    "or_",
+    "param",
+    "raw",
+]
+
+# Operator names, the symbols and the words for them.
+_OPS = {
+    "=": "=", "eq": "=",
+    "!=": "!=", "ne": "!=", "neq": "!=",
+    "<": "<", "lt": "<",
+    "<=": "<=", "lte": "<=", "le": "<=",
+    ">": ">", "gt": ">",
+    ">=": ">=", "gte": ">=", "ge": ">=",
+    "~": "~", "like": "~", "contains": "~",
+    "has": "has",
+    "in": "in",
+}  # fmt: skip
+
+# The collations the engine knows. The name is spliced into the text, so
+# it is checked against the list rather than the name pattern.
+_COLLATIONS = ("und", "tr")
+
+# The engine refuses a deeper chain; failing here never sends a query.
+MAX_LOOKUP_DEPTH = 8
+
+# What JavaScript's String.prototype.trim takes off, which the JS builder
+# trims an aggregate with: str.strip() also takes U+001C..U+001F and leaves
+# U+FEFF.
+_JS_SPACE = "\t\n\v\f\r " + "".join(map(chr, (0xA0, 0x1680, *range(0x2000, 0x200B), 0x2028, 0x2029, 0x202F, 0x205F, 0x3000, 0xFEFF)))
+
+
+def _err(message: str) -> Exception:
+    # Imported late: the package's __init__ imports this module.
+    from . import FennecError
+
+    return FennecError(message, 0)
+
+
+def _quote(name: Any) -> str:
+    """A name in a message, as JSON.stringify writes it."""
+    try:
+        return json.dumps(name, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return repr(name)
+
+
+# FennecQL's identifier: a Unicode letter or `_`, then letters, digits and
+# `_`, as the lexer reads it -- JavaScript's \p{Alphabetic} and \p{N}. The
+# standard library has no Alphabetic property, which is the letters, the
+# letter numbers and the marks of Other_Alphabetic (a Devanagari vowel
+# sign); after the first character every mark is taken, a name the lexer
+# would refuse being refused by the server rather than let through as text.
+def _starts(ch: str) -> bool:
+    cat = unicodedata.category(ch)
+    return ch == "_" or cat[0] == "L" or cat == "Nl"
+
+
+def _continues(ch: str) -> bool:
+    cat = unicodedata.category(ch)
+    return ch == "_" or cat[0] in "LN" or cat in ("Mn", "Mc")
+
+
+def _is_ident(s: str) -> bool:
+    return bool(s) and _starts(s[0]) and all(_continues(c) for c in s[1:])
+
+
+def _ident(name: Any, what: str = "field") -> str:
+    if not isinstance(name, str) or not _is_ident(name):
+        raise _err(f"invalid {what} name: {_quote(name)}")
+    return name
+
+
+def _path(name: Any) -> str:
+    """A field's name, or a path into a json field: `meta.lang`."""
+    if not isinstance(name, str) or not all(_is_ident(p) for p in name.split(".")):
+        raise _err(f"invalid field name: {_quote(name)}")
+    return name
+
+
+def _ascii_ident(s: str) -> bool:
+    return (
+        bool(s)
+        and s.isascii()
+        and (s[0].isalpha() or s[0] == "_")
+        and all(c.isalnum() or c == "_" for c in s)
+    )
+
+
+# A select item spelled as FennecQL spells an aggregate of one -- `count(*)`,
+# `count(distinct user)`, `sum(total)`, `avg(f)`, `min(f)`, `max(f)`,
+# `first(f)`, `last(f)`, a path where a field goes. ASCII-only and its case
+# folded as ASCII alone, as the JS builder's pattern is: a Unicode-aware one
+# folds the Kelvin sign onto `k` and `ſ` onto `s`, where JavaScript's does
+# not. `\s` there is JavaScript's space, which `_JS_SPACE` spells out.
+_NAMES = r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*"
+_SP = "[" + re.escape(_JS_SPACE) + "]"
+_AGGREGATE = re.compile(
+    rf"(count)\(\*?\)|count\({_SP}*distinct{_SP}+({_NAMES}){_SP}*\)|(sum|avg|min|max|first|last)\(({_NAMES})\)",
+    re.ASCII | re.IGNORECASE,
+)
+# What makes an expression an aggregate's: a call of one.
+_AGGREGATE_CALL = re.compile(
+    rf"(?<![A-Za-z0-9_])(count|sum|avg|min|max|first|last){_SP}*\(", re.ASCII | re.IGNORECASE
+)
+
+
+def _column(name: Any) -> tuple[Any, bool]:
+    """A select item: a field, an aggregate spelled as FennecQL spells it,
+    answering under that name, or an expression (`Computed`), answering
+    under the name its `as_` gives it."""
+    if isinstance(name, Computed) and name.kind == "expr":
+        return name, bool(_AGGREGATE_CALL.search(name.sql))
+    m = _AGGREGATE.fullmatch(name.strip(_JS_SPACE)) if isinstance(name, str) else None
+    if not m:
+        return _path(name), False
+    if m[1]:
+        return "count(*)", True
+    if m[2]:
+        return f"count(distinct {m[2]})", True
+    return f"{m[3].lower()}({m[4]})", True
+
+
+def _group_keys(flat: list) -> list:
+    """`group`'s keys: a field or a path, a name the list gives, or an
+    expression."""
+    if not flat:
+        raise _err("group takes at least one key")
+    return [k if isinstance(k, Computed) and k.kind == "expr" else _path(k) for k in flat]
+
+
+def _key(name: Any) -> str:
+    """An `order` key: a field, a path, or an aggregate by its name."""
+    return _column(name)[0] if isinstance(name, str) else _path(name)
+
+
+def _column_text(c: Any, bind: "_Binder") -> str:
+    """A select item or a group key as text, an expression's values bound."""
+    if isinstance(c, str):
+        return c
+    text = _value("select", c, bind, "")
+    return f"{text} as {c.name}" if c.name is not None else text
+
+
+def _direction(d: Any) -> bool:
+    low = str(d).lower()
+    if low not in ("asc", "desc"):
+        raise _err(f"order direction must be 'asc' or 'desc': {d}")
+    return low == "asc"
+
+
+def _collation(name: Any) -> str | None:
+    if name is None:
+        return None
+    if name not in _COLLATIONS:
+        raise _err(f"unknown collation: {_quote(name)}; there are 'und' and 'tr'")
+    return name
+
+
+def _js_number(n: float) -> str:
+    """A number as JavaScript's `String(n)` writes it, the text every other
+    builder makes: a whole float without its `.0`."""
+    if isinstance(n, float) and n.is_integer() and abs(n) < 1e21:
+        return str(int(n))
+    return repr(n)
+
+
+def _whole(n: Any, what: str) -> int:
+    """A count, a whole number JavaScript holds exactly. `limit`, `offset`
+    and a facet's `top` go as parameters, so a page of any size or place is
+    one text; `ef`, `candidates`, `k` and a snippet's words are written in,
+    as FennecQL takes them."""
+    if isinstance(n, bool) or not isinstance(n, int) or n < 0 or n > 2**53 - 1:
+        raise _err(f"{what} must be a non-negative integer: {_quote(n) if isinstance(n, bool) else n}")
+    return n
+
+
+def _text(v: Any, what: str) -> str:
+    if not isinstance(v, str):
+        raise _err(f"{what} must be text: {_quote(v)}")
+    return v
+
+
+def _tags(pre: Any, post: Any, what: str) -> dict:
+    """A mark's tags: both or neither, each text."""
+    if pre is None and post is None:
+        return {}
+    if pre is None or post is None:
+        raise _err(f"{what} takes both pre and post, or neither")
+    return {"pre": _text(pre, f"{what} pre"), "post": _text(post, f"{what} post")}
+
+
+def _js_date(d: datetime) -> str:
+    """A datetime as JavaScript's toISOString writes it, which the JS
+    builder sends a Date as: UTC, to the millisecond. A naive one is taken
+    for UTC."""
+    if d.tzinfo is not None:
+        d = d.astimezone(timezone.utc)
+    return (
+        f"{d.year:04d}-{d.month:02d}-{d.day:02d}T{d.hour:02d}:{d.minute:02d}:"
+        f"{d.second:02d}.{d.microsecond // 1000:03d}Z"
+    )
+
+
+def _normalize(v: Any, what: str = "value") -> Any:
+    """A value as it goes into the parameters' JSON: a datetime as its ISO
+    text, an `array.array` or anything with `tolist()` (a NumPy array) as
+    a list, a mapping as a json field's object."""
+    if v is None or isinstance(v, (bool, int, float, str)):
+        return v
+    if isinstance(v, datetime):
+        return _js_date(v)
+    if isinstance(v, (list, tuple, array.array)):
+        return [_normalize(x, what) for x in v]
+    if isinstance(v, Mapping):
+        return {k: _normalize(x, what) for k, x in v.items()}
+    # A param is bound where a whole value stands, never from inside a list
+    # or a json value; every builder refuses it in these words
+    # (builder-golden.json).
+    if isinstance(v, Param):
+        raise _err("this object cannot be used as a fennecdb value (a param() inside a value)")
+    tolist = getattr(v, "tolist", None)
+    if callable(tolist):
+        return _normalize(tolist(), what)
+    raise _err(f"this object cannot be used as a fennecdb value ({what})")
+
+
+# ---------------------------------------------------- one value in two places
+
+
+class Param:
+    """What `param()` makes: a value bound once, whichever places it is
+    used in. Each use writes the same `$n`, where the same value given twice
+    is two parameters -- `balance - $1 ... balance >= $1`, the amount taken
+    and the amount checked one value, never two a caller could let drift
+    apart. A param is told by its identity, never its value: two params of
+    equal values stay two parameters, as the JavaScript builder's do."""
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: Any) -> None:
+        if isinstance(value, Param):
+            raise _err("param() takes a value, not another param()")
+        object.__setattr__(self, "value", value)
+
+    # Immutable, as a query is: a param changed after a query took it would
+    # change a statement already written.
+    def __setattr__(self, key: str, value: Any) -> None:
+        raise AttributeError("a param is immutable")
+
+    def __delattr__(self, key: str) -> None:
+        raise AttributeError("a param is immutable")
+
+    def __repr__(self) -> str:
+        return f"param({self.value!r})"
+
+
+def param(value: Any) -> Param:
+    """`param(value)`: one parameter, used wherever a value goes -- a filter,
+    a document, `expr()`, `raw()`, `distance()`, `near`, `match` -- and bound
+    once, at its first place in the text:
+
+        amount = param(300)
+        (collection("accounts").where({"name": "ada", "balance": {"gte": amount}})
+            .to_update({"balance": expr("balance - ?", amount)}, require=1))
+        # ("set accounts {balance: balance - $1} where name = $2 and balance >= $1 require 1",
+        #  [300, "ada"])
+
+    `None` is a value here, FennecQL's null."""
+    return Param(value)
+
+
+def _value_of(v: Any) -> Any:
+    """A value as the builder checks it: a param's own."""
+    return v.value if isinstance(v, Param) else v
+
+
+# ---------------------------------------------------------- the condition tree
+
+
+class Cond:
+    """A condition `or_`, `and_`, `not_` or `raw` made, or one the builder
+    made of a field's. A dict is a condition too -- `{"year": {"gte": 2024}}`
+    -- and stays one: only this class is taken for a node."""
+
+    __slots__ = ("t", "items", "field", "op", "value", "negated", "sql", "params")
+
+    def __init__(self, t: str, **kw: Any):
+        self.t = t
+        self.items: list[Cond] = kw.get("items", [])
+        self.field: str = kw.get("field", "")
+        self.op: str = kw.get("op", "")
+        self.value: Any = kw.get("value")
+        self.negated: bool = kw.get("negated", False)
+        self.sql: str = kw.get("sql", "")
+        self.params: tuple = kw.get("params", ())
+
+    def __repr__(self) -> str:
+        return f"Cond({self.t})"
+
+
+def _flat(conds: Iterable[Any]) -> list:
+    out = []
+    for c in conds:
+        out.extend(c) if isinstance(c, (list, tuple)) else out.append(c)
+    return out
+
+
+def or_(*conds: Any) -> Cond:
+    """`or_(a, b)` / `or_([a, b])`: joins conditions with `or`."""
+    return Cond("or", items=[_to_cond(c) for c in _flat(conds)])
+
+
+def and_(*conds: Any) -> Cond:
+    """`and_(a, b)`: `where` already ands; this is only needed inside `or_`."""
+    return Cond("and", items=[_to_cond(c) for c in _flat(conds)])
+
+
+def not_(cond: Any) -> Cond:
+    return Cond("not", items=[_to_cond(cond)])
+
+
+def raw(sql: str, *params: Any) -> Cond:
+    """Everything the builder cannot express (a function call): each `?` is
+    bound to the next parameter -- a literal `?` goes in as one too.
+
+        .where(raw("cosine(embed, ?) > ?", vector, 0.5))
+    """
+    if not isinstance(sql, str):
+        raise _err("raw() expects text")
+    return Cond("raw", sql=sql, params=params)
+
+
+class Computed:
+    """A value worked out over a row: what `inc` and `expr` make for a
+    write, and what `expr`, `bucket`, `count_distinct`, `first` and `last`
+    make for a select list or a group, rendered as FennecQL with its values
+    as parameters."""
+
+    __slots__ = ("kind", "by", "sql", "params", "name")
+
+    def __init__(
+        self, kind: str, by: Any = None, sql: str = "", params: tuple = (), name: str | None = None
+    ):
+        self.kind, self.by, self.sql, self.params, self.name = kind, by, sql, params, name
+
+    def as_(self, name: str) -> "Computed":
+        """The name the column answers under: `select ... as <name>`
+        (`as` is Python's keyword, hence the underscore)."""
+        return Computed(self.kind, self.by, self.sql, self.params, _ident(name, "column"))
+
+    def __repr__(self) -> str:
+        return f"Computed({self.kind})"
+
+
+def inc(by: Any = 1) -> Computed:
+    """`{"n": inc(1)}` in an update: the field plus `by`, counting from 0
+    where it is null -- `n: coalesce(n, 0) + $1` -- worked out under the
+    server's write lock, so increments from many clients all land."""
+    if isinstance(by, bool) or not isinstance(by, (int, float)) or not math.isfinite(by):
+        text = json.dumps(by, ensure_ascii=False, separators=(",", ":"), default=str)
+        raise _err(f"inc() takes a number: {text}")
+    return Computed("inc", by=by)
+
+
+def expr(sql: str, *params: Any) -> Computed:
+    """A value as a FennecQL expression over the row it is written into,
+    each `?` bound to the next parameter: `{"at": expr("now()")}`,
+    `{"total": expr("price * ?", 1.2)}`.
+
+    The text is trusted FennecQL, written into the statement as it is: the
+    code's own, never a value from a user, which goes in as a `?`'s
+    parameter. Names and this text are where an injection would get
+    through."""
+    if not isinstance(sql, str):
+        raise _err("expr() expects text")
+    return Computed("expr", sql=sql, params=params)
+
+
+# `15m`, `1h`, `1d`, `1w`, `3mo`, `1y`: what `bucket` takes, written into
+# the text as a literal, since it is a part of the statement's shape.
+_INTERVAL = re.compile(r"[1-9][0-9]*(ms|s|m|h|d|w|mo|y)", re.ASCII)
+
+
+def bucket(field: str, interval: str, zone: str | None = None) -> Computed:
+    """`bucket(field, interval [, zone])`: the start of the interval a
+    timestamp falls in -- `"15m"`, `"1h"`, `"1d"`, `"1w"` (from a Monday),
+    `"1mo"`, `"1y"`, in UTC -- for a select list or a group:
+
+        .select(bucket("at", "1m").as_("minute"), "count(*)").group("minute")
+
+    Given a zone -- an IANA name, `"Europe/Istanbul"`, or an offset,
+    `"+03:00"` -- by its clock: a day from local midnight, 23 or 25 hours
+    where it changes to or from daylight time. It goes as a parameter.
+    """
+    if not isinstance(interval, str) or not _INTERVAL.fullmatch(interval):
+        raise _err(
+            "bucket() takes an interval such as '15m', '1h', '1d', '1w' or '1mo': "
+            + json.dumps(interval, ensure_ascii=False, default=str)
+        )
+    if zone is None:
+        return Computed("expr", sql=f"bucket({_path(field)}, {interval})")
+    if not isinstance(zone, str) or zone == "":
+        raise _err(
+            "bucket() takes a zone's name, such as 'Europe/Istanbul', or an offset, such as "
+            "'+03:00': " + json.dumps(zone, ensure_ascii=False, default=str)
+        )
+    return Computed("expr", sql=f"bucket({_path(field)}, {interval}, ?)", params=(zone,))
+
+
+def count_distinct(field: str) -> Computed:
+    """`count(distinct field)`: how many distinct values the rows hold."""
+    return Computed("expr", sql=f"count(distinct {_path(field)})")
+
+
+def distance(field: str, point: Sequence[float]) -> Computed:
+    """`distance(field, point)`: the metres from a point, `[lon, lat]`, to
+    the row's, for a select list -- `distance("loc", [13.4, 52.5]).as_("m")`,
+    what Redis's `GEOSEARCH ... WITHDIST` answers with."""
+    return Computed("expr", sql=f"distance({_path(field)}, ?)", params=(point,))
+
+
+def first(field: str, by: str | None = None) -> Computed:
+    """`first(field)`, or `first(field by key)`: the value of the row least
+    by `key` -- by the order the rows were written without one -- that has
+    a value; a bar's open is `first("px", "at")`."""
+    return _pick("first", field, by)
+
+
+def last(field: str, by: str | None = None) -> Computed:
+    """`last(field [by key])`: as `first`, the row greatest by `key`."""
+    return _pick("last", field, by)
+
+
+def _pick(fn: str, field: str, by: str | None) -> Computed:
+    return Computed("expr", sql=f"{fn}({_path(field)}{'' if by is None else f' by {_path(by)}'})")
+
+
+def _value(k: str, v: Any, bind: "_Binder", write: str) -> str:
+    """A document's value: `inc`'s and `expr`'s text, or a parameter."""
+    if not isinstance(v, Computed):
+        return bind(v, k)
+    if v.kind == "inc":
+        if write == "insert":
+            raise _err(f"inc() reads the row it changes: use it in update (field: {k})")
+        return f"coalesce({k}, 0) + {bind(v.by, k)}"
+    out, i = [], 0
+    parts = v.sql.split("?")
+    for part in parts[:-1]:
+        if i >= len(v.params):
+            raise _err("expr(): more `?` placeholders than parameters")
+        out.append(part + bind(v.params[i], k))
+        i += 1
+    if i != len(v.params):
+        raise _err("expr(): too many parameters given")
+    out.append(parts[-1])
+    return "".join(out)
+
+
+def _to_cond(x: Any) -> Cond:
+    if isinstance(x, Cond):
+        return x
+    if isinstance(x, Mapping):
+        return _object_cond(x)
+    raise _err(f"expected an object as a condition: {_quote(x)}")
+
+
+def _object_cond(obj: Mapping) -> Cond:
+    items = [_field_cond(_path(f), spec) for f, spec in obj.items()]
+    return items[0] if len(items) == 1 else Cond("and", items=items)
+
+
+def _field_cond(field: str, spec: Any) -> Cond:
+    """A raw value is equality, a mapping an operator map."""
+    if spec is None:
+        return Cond("null", field=field)
+    if not isinstance(spec, Mapping):
+        return _cmp(field, "=", spec)
+    items = []
+    for k, v in spec.items():
+        if k == "not":
+            items.append(
+                Cond("null", field=field, negated=True)
+                if v is None
+                else Cond("not", items=[_field_cond(field, v)])
+            )
+            continue
+        # A point's: `{"loc": {"within": [w, s, e, n]}}` and `{"loc":
+        # {"distance": {"from": [lon, lat], "lte": 500}}}`.
+        if k == "within":
+            items.append(Cond("within", field=field, value=v))
+            continue
+        if k == "distance":
+            items.append(_distance_cond(field, v))
+            continue
+        op = _OPS.get(k) if isinstance(k, str) else None
+        if not op:
+            raise _err(f"unknown operator `{k}` (field: {field})")
+        items.append(_in_cond(field, v) if op == "in" else _cmp(field, op, v))
+    if not items:
+        raise _err(f"empty condition object (field: {field})")
+    return items[0] if len(items) == 1 else Cond("and", items=items)
+
+
+def _distance_cond(field: str, spec: Any) -> Cond:
+    """`{"distance": {"from": [lon, lat], "lte": 500}}`: the metres from a
+    point, compared -- `distance(loc, $1) <= $2`, each comparison given its
+    own."""
+    # A param's value is checked, the param itself bound: its `$n` is the one
+    # its other places write.
+    if not isinstance(spec, Mapping) or not isinstance(_value_of(spec.get("from")), (list, tuple)):
+        raise _err(f"distance takes {{ from: [lon, lat], <op>: metres }} (field: {field})")
+    items = []
+    for k, v in spec.items():
+        if k == "from":
+            continue
+        op = _OPS.get(k) if isinstance(k, str) else None
+        n = _value_of(v)
+        number = isinstance(n, (int, float)) and not isinstance(n, bool)
+        if not op or op in ("in", "has", "~") or not number:
+            raise _err(
+                f"distance compares metres with lt, lte, gt, gte, eq or ne: {k} (field: {field})"
+            )
+        items.append(Cond("dist", field=field, op=op, value=(spec["from"], v)))
+    if not items:
+        raise _err(f"distance needs a comparison, as lte: metres (field: {field})")
+    return items[0] if len(items) == 1 else Cond("and", items=items)
+
+
+def _in_cond(field: str, values: Any) -> Cond:
+    # `{"customer": {"in": db.collection("customers").select("id").where(...)}}`:
+    # the inner query runs once, before the outer one, and its one column is
+    # the list -- `customer in (get customers select id where ...)`.
+    if isinstance(values, _Builder):
+        return Cond("sub", field=field, value=values)
+    if not isinstance(values, (list, tuple)):
+        raise _err(f"`in` expects an array (field: {field})")
+    if not values:
+        raise _err(f"`in` does not accept an empty array (field: {field})")
+    return Cond("in", field=field, items=list(values))
+
+
+def _cmp(field: str, op: str, value: Any) -> Cond:
+    # `= null` is never true in FennecQL; what is meant is `is null`.
+    if value is None:
+        if op == "=":
+            return Cond("null", field=field)
+        if op == "!=":
+            return Cond("null", field=field, negated=True)
+        raise _err(f"`{op}` cannot be used with null (field: {field})")
+    return Cond("cmp", field=field, op=op, value=value)
+
+
+def _cond_of(args: tuple) -> Cond:
+    if len(args) == 1:
+        return _to_cond(args[0])
+    if len(args) == 2:
+        return _field_cond(_path(args[0]), args[1])
+    if len(args) == 3:
+        op = _OPS.get(args[1]) if isinstance(args[1], str) else None
+        if not op:
+            raise _err(f"unknown operator `{args[1]}`")
+        field = _path(args[0])
+        return _in_cond(field, args[2]) if op == "in" else _cmp(field, op, args[2])
+    raise _err("where(field, op, value) | where(field, value) | where(object)")
+
+
+def _prune(c: Cond) -> Cond | None:
+    """Flattens empty and single-child junctions before rendering: the
+    parentheses depend on the child count, and rendering binds parameters."""
+    if c.t in ("and", "or"):
+        items = [x for x in (_prune(i) for i in c.items) if x is not None]
+        if not items:
+            return None
+        return items[0] if len(items) == 1 else Cond(c.t, items=items)
+    if c.t == "not":
+        item = _prune(c.items[0])
+        return Cond("not", items=[item]) if item is not None else None
+    return c
+
+
+class _Binder:
+    def __init__(self) -> None:
+        self.params: list = []
+        # A `param()` takes its `$n` at its first use, and every use after
+        # writes that one: kept by the param's identity (`Param` defines no
+        # `__eq__`), so two params of one value stay two parameters.
+        self._once: dict[Param, str] = {}
+
+    def __call__(self, v: Any, what: str) -> str:
+        if isinstance(v, Param):
+            at = self._once.get(v)
+            if at is None:
+                self.params.append(_normalize(v.value, what))
+                at = self._once[v] = f"${len(self.params)}"
+            return at
+        self.params.append(_normalize(v, what))
+        return f"${len(self.params)}"
+
+
+def _render(c: Cond, bind: _Binder, parent: str | None = None) -> str:
+    if c.t in ("and", "or"):
+        s = f" {c.t} ".join(_render(x, bind, c.t) for x in c.items)
+        # `and` binds tighter than `or`: one inside the other needs parens.
+        return f"({s})" if parent and parent != c.t else s
+    if c.t == "not":
+        return f"not ({_render(c.items[0], bind)})"
+    if c.t == "null":
+        return f"{c.field} is {'not ' if c.negated else ''}null"
+    if c.t == "in":
+        return f"{c.field} in [{', '.join(bind(v, c.field) for v in c.items)}]"
+    if c.t == "sub":
+        # Its parameters numbered where its text stands, after the outer
+        # query's before it.
+        return f"{c.field} in ({c.value._inner(bind)})"
+    if c.t == "cmp":
+        return f"{c.field} {c.op} {bind(c.value, c.field)}"
+    if c.t == "within":
+        return f"within({c.field}, {bind(c.value, c.field)})"
+    if c.t == "dist":
+        point, metres = c.value
+        return f"distance({c.field}, {bind(point, c.field)}) {c.op} {bind(metres, c.field)}"
+    # raw
+    out, i = [], 0
+    for part in c.sql.split("?")[:-1]:
+        if i >= len(c.params):
+            raise _err("raw(): more `?` placeholders than parameters")
+        out.append(part + bind(c.params[i], "raw"))
+        i += 1
+    if i != len(c.params):
+        raise _err("raw(): too many parameters given")
+    out.append(c.sql.split("?")[-1])
+    return "".join(out)
+
+
+# ---------------------------------------------------------------- the query
+
+
+def _order_keys(spec: Any) -> list[tuple[str, bool, str | None]]:
+    """A lookup's `order`: `"created"`, or `[("created", "desc"), ...]`, a
+    pair taking `{"collate": ...}` third; a bare name in the list is one
+    ascending key."""
+    if spec is None:
+        return []
+    if isinstance(spec, str):
+        return [(_path(spec), True, None)]
+    keys = []
+    for k in spec:
+        parts = [k] if isinstance(k, str) else list(k)
+        field = parts[0] if parts else None
+        d = parts[1] if len(parts) > 1 else "asc"
+        opts = parts[2] if len(parts) > 2 else {}
+        # Over groups a key may name an aggregate of the list.
+        keys.append((_key(field), _direction(d), _collation((opts or {}).get("collate"))))
+    return keys
+
+
+def _sort_key(k: tuple[Any, bool, str | None], bind: _Binder) -> str:
+    """`name collate tr desc`: one key of an `order`, an expression's values
+    bound where its text stands."""
+    key, asc, collate = k
+    text = _value("order", key, bind, "") if isinstance(key, Computed) else key
+    return f"{text}{f' collate {collate}' if collate else ''} {'asc' if asc else 'desc'}"
+
+
+Q = TypeVar("Q", bound="_Builder")
+
+
+class _Builder:
+    """The chain, shared by `Query` and `AsyncQuery`: everything but sending."""
+
+    __slots__ = ("_s",)
+
+    def __init__(self, collection: str, client: Any = None, _state: dict | None = None):
+        if _state is not None:
+            self._s = _state
+            return
+        self._s = {
+            "collection": _ident(collection, "collection"),
+            "client": client,
+            "project": None,
+            "aggregate": False,
+            "group": None,
+            "cond": [],
+            "near": None,
+            "match": None,
+            # `fuse` writes its two searches in the order they were first
+            # called: `match` first where it came while no `near` was there.
+            "match_first": False,
+            "rerank": None,
+            "fuse": None,
+            "order": [],
+            "limit": None,
+            "offset": 0,
+            "count": False,
+            "lookups": [],
+            "marks": [],
+            "facets": [],
+            "require": "",
+        }
+
+    def _with(self: Q, **patch: Any) -> Q:
+        return type(self)("", _state={**self._s, **patch})
+
+    @property
+    def collection(self) -> str:
+        return self._s["collection"]
+
+    def select(self: Q, *cols: Any) -> Q:
+        """`select a, b`; none, or `"*"`, is every field. Aggregates go in the
+        same list as FennecQL spells them and answer under that name:
+        `select("status", "count(*)", "sum(total)").group("status")`; an
+        expression -- `expr()`, `bucket()`, `count_distinct()`, `first()`,
+        `last()` -- under the name its `as_` gives it:
+        `select("sym", expr("sum(px * qty) / sum(qty)").as_("vwap")).group("sym")`."""
+        flat = _flat(cols)
+        if not flat or any(isinstance(c, str) and c == "*" for c in flat):
+            return self._with(project=None, aggregate=False)
+        cs = [_column(c) for c in flat]
+        return self._with(project=[t for t, _ in cs], aggregate=any(a for _, a in cs))
+
+    def highlight(self: Q, field: str, *, pre: str | None = None, post: str | None = None) -> Q:
+        """`highlight(field)` in the select list: where the terms `match`
+        found stand in the field's text -- `[start, end]` pairs of UTF-16
+        offsets, a JavaScript string's own, as the server counts them -- or,
+        given `pre` and `post`, the text with each mark between them. The
+        text is not escaped: a page that renders it as HTML escapes it
+        first, or builds it from the offsets. Answers under
+        `highlight(field)`, after the fields `select` named."""
+        return self._mark({"field": _ident(field), "words": None, **_tags(pre, post, "highlight")})
+
+    def snippet(
+        self: Q,
+        field: str,
+        words: int,
+        *,
+        ellipsis: str | None = None,
+        pre: str | None = None,
+        post: str | None = None,
+    ) -> Q:
+        """`snippet(field, words)`: the window of `words` words around the
+        densest marks, `{"text", "marks"}` -- or the marked text, given
+        `pre` and `post` -- with `ellipsis` where it leaves text out.
+        Answers under `snippet(field)`."""
+        mark = {"field": _ident(field), "words": _whole(words, "snippet words"), **_tags(pre, post, "snippet")}
+        if mark["words"] == 0:
+            raise _err("snippet shows at least one word")
+        if ellipsis is not None:
+            mark["ellipsis"] = _text(ellipsis, "snippet ellipsis")
+        return self._mark(mark)
+
+    def _mark(self: Q, mark: dict) -> Q:
+        # Each answers under its label, and a row holds a name once.
+        def kind(m: dict) -> str:
+            return "highlight" if m["words"] is None else "snippet"
+
+        if any(kind(m) == kind(mark) and m["field"] == mark["field"] for m in self._s["marks"]):
+            raise _err(f"{kind(mark)}({mark['field']}) is asked twice")
+        return self._with(marks=[*self._s["marks"], mark])
+
+    def facet(
+        self: Q,
+        field: str,
+        *,
+        top: int | None = None,
+        ranges: Sequence[float] | None = None,
+        disjunctive: bool = False,
+    ) -> Q:
+        """`facet field [top N]`: each value the field -- or a path into a
+        json field -- holds over every row the query matches, not only the
+        page, and how many rows hold it, most first; `top` keeps the
+        commonest. A list counts once a row for each value. The counts come
+        back beside the rows, as `rows().facets`.
+
+            (db.collection("products").match("title", "phone").where("price", "<", 500)
+               .facet("brand", top=10).facet("color").limit(20).rows().facets)
+
+        `ranges=[0, 25, 50]` counts the rows in each range of numbers from
+        one bound up to the next, every range in order, its value
+        `[from, to]`; `disjunctive=True` counts as if the filter's own
+        conditions on the field were not there, so the other values a
+        shopper could add are counted too.
+        """
+        name = _path(field)
+        top = None if top is None else _whole(top, "facet top")
+        if top == 0:
+            raise _err(f"facet {name} top 0 answers nothing")
+        if any(g[0] == name for g in self._s["facets"]):
+            raise _err(f"facet {name} is asked twice")
+        bounds = None
+        if ranges is not None:
+            # The engine's rule, refused before anything is sent.
+            ok = (
+                top is None
+                and isinstance(ranges, (list, tuple))
+                and len(ranges) >= 2
+                and all(
+                    isinstance(b, (int, float))
+                    and not isinstance(b, bool)
+                    and math.isfinite(b)
+                    and (i == 0 or b > ranges[i - 1])
+                    for i, b in enumerate(ranges)
+                )
+            )
+            if not ok:
+                raise _err(
+                    f"facet {name} ranges takes 2 to 10 001 numbers, each above the one before, "
+                    "and no top: every range answers, in order"
+                )
+            bounds = [_js_number(b) for b in ranges]
+        if not isinstance(disjunctive, bool):
+            raise _err(f"facet {name} disjunctive is true or false")
+        return self._with(facets=[*self._s["facets"], (name, top, bounds, disjunctive)])
+
+    def group(self: Q, *keys: Any) -> Q:
+        """`group a, b`: a row per distinct set of the keys' values, for a
+        select list that aggregates. A key is a field or a path, a name the
+        list gives a column with `as_`, or an expression: `bucket("at", "1h")`."""
+        flat = _flat(keys)
+        if not flat:
+            raise _err("group takes at least one key")
+        return self._with(group=_group_keys(flat))
+
+    def where(self: Q, *args: Any) -> Q:
+        """`where(field, op, value)`, `where(field, value)` -- a value is
+        equality, a dict an operator map -- or `where(condition)`: a dict of
+        fields, or what `or_`, `and_`, `not_` and `raw` make. Successive
+        calls join with `and`."""
+        return self._with(cond=[*self._s["cond"], _cond_of(args)])
+
+    def or_where(self: Q, *args: Any) -> Q:
+        """Joins everything conditioned so far to a new condition with `or`."""
+        right = _cond_of(args)
+        left = self._s["cond"]
+        if not left:
+            return self._with(cond=[right])
+        return self._with(cond=[Cond("or", items=[Cond("and", items=list(left)), right])])
+
+    def near(self: Q, field: str, vector: Any, *, ef: int | None = None, exact: bool = False) -> Q:
+        """`near field $n [ef N] [exact]`."""
+        return self._with(
+            match_first=False if self._s["match"] is None else self._s["match_first"],
+            near=(_ident(field), vector, None if ef is None else _whole(ef, "ef"), bool(exact)),
+        )
+
+    def match(
+        self: Q, field: str, query: str, *, fuzzy: bool | int = False, prefix: bool = False
+    ) -> Q:
+        """`match field $n [fuzzy [N]] [prefix]`: BM25 over a `@text` index.
+        `fuzzy=True` (`fuzzy` alone, 2 edits) matches each word within the
+        edits its length allows -- none under 5 characters, one up to 8, two
+        from 9 -- `fuzzy=1` one at most; `prefix=True` matches the last word
+        as the start of a word too, as a search box is typed into."""
+        # `True` is an `int` too: asked first, it is the parser's default,
+        # written as `fuzzy` alone, and never 1.
+        if fuzzy is True:
+            edits = True
+        elif fuzzy is False:
+            edits = None
+        elif isinstance(fuzzy, int) and 0 <= fuzzy <= 2:
+            edits = fuzzy
+        else:
+            raise _err(f"fuzzy is true, false or 0 to 2 edits: {fuzzy}")
+        if not isinstance(prefix, bool):
+            raise _err(f"prefix is true or false: {prefix}")
+        return self._with(
+            match_first=True if self._s["near"] is None else self._s["match_first"],
+            match=(_ident(field), query, edits, prefix),
+        )
+
+    def fuse(self: Q, *, k: int | None = None, candidates: int | None = None) -> Q:
+        """`fuse [k N] [candidates N]`: with both `match` and `near`, ranks by
+        both -- a document scores `1 / (k + rank)` from each list it is on."""
+        return self._with(
+            fuse=(
+                None if k is None else _whole(k, "k"),
+                None if candidates is None else _whole(candidates, "candidates"),
+            )
+        )
+
+    def rerank(self: Q, field: str, vector: Any, *, candidates: int | None = None) -> Q:
+        """`rerank field $n [candidates N]`: reorders what `match` found by
+        exact distance, the vectors read out of the store."""
+        return self._with(
+            rerank=(
+                _ident(field),
+                vector,
+                None if candidates is None else _whole(candidates, "candidates"),
+            )
+        )
+
+    def lookup(
+        self: Q,
+        name: str,
+        *,
+        on: str | Sequence[str] | None = None,
+        parent_key: str | Sequence[str] | None = None,
+        select: Any = None,
+        group: Any = None,
+        where: Any = None,
+        required: bool = False,
+        order: Any = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> Q:
+        """`lookup name on child [= parent] ...`: each row's children,
+        attached to it. Everything here binds to the looked-up collection;
+        `limit` counts children per parent. `required` drops a parent no
+        child matches. A key over several fields names a field of each side
+        for each part, `on=["org", "order"], parent_key=["org", "id"]`.
+        Called again, it chains onto the collection the call before named.
+
+        `select` may aggregate, as a query's own list does: each parent's
+        children folded, one row a parent, or with `group` one a group,
+        ordered and paged a parent at a time; ungrouped, `order`, `limit`
+        and `offset` pick the children folded. A query whose list
+        aggregates hangs a lookup off its groups, `parent_key` a column."""
+        names = [on] if isinstance(on, str) else list(on or [])
+        if not names or not names[0]:
+            raise _err("lookup needs `on`: the child field holding the key")
+        child = [_ident(f) for f in names]
+        above = (
+            []
+            if parent_key is None
+            else [_ident(f) for f in ([parent_key] if isinstance(parent_key, str) else parent_key)]
+        )
+        # One child field alone pairs with `id` unless named; several, each
+        # with its own.
+        if (len(child) > 1 or parent_key is not None) and len(above) != len(child):
+            raise _err(f"lookup pairs {len(child)} child fields with {len(above)} parent fields")
+        cols = None if select is None else _flat((select,))
+        listed = None if cols is None or "*" in cols else [_column(c) for c in cols]
+        aggregate = any(a for _, a in listed or [])
+        keys = None if group is None else _group_keys(_flat((group,)))
+        # The engine refuses it too; failing here never sends a query.
+        if keys and not aggregate:
+            text = ", ".join(k if isinstance(k, str) else k.sql for k in keys)
+            raise _err(f"group {text} needs an aggregate in select: 'count(*)'")
+        # A level selects its children's fields, or aggregates of them.
+        if listed and not aggregate and any(not isinstance(c, str) for c, _ in listed):
+            raise _err("a lookup selects its children's fields, or aggregates of them")
+        level = {
+            "collection": _ident(name, "collection"),
+            "on": child,
+            "parent": above,
+            "project": None if listed is None else [c for c, _ in listed],
+            "group": keys,
+            "cond": [] if where is None else [_cond_of((where,))],
+            "required": bool(required),
+            "order": _order_keys(order),
+            "limit": None if limit is None else _whole(limit, "limit"),
+            "offset": 0 if offset is None else _whole(offset, "offset"),
+        }
+        return self._with(lookups=[*self._s["lookups"], level])
+
+    def order(
+        self: Q, field: str | Computed, direction: str = "asc", *, collate: str | None = None
+    ) -> Q:
+        """`order field asc|desc`; each call adds a key. A key may be an
+        expression over the row -- `order(expr("n * 2"), "desc")`,
+        `order(distance("pickup", point))` -- ties going in id order, and
+        picks the rows of an `update` or a `delete` too. `collate="tr"` puts
+        text in Turkish order, `"und"` in Unicode's root order."""
+        if isinstance(field, Computed) and field.kind == "expr":
+            # A name given with `as_` would read as the key's own; the
+            # statement has no such column to order by.
+            if field.name is not None:
+                raise _err(
+                    f"an order key is an expression or a name: order by {field.name} itself, without as"
+                )
+            key: Any = field
+        else:
+            # Over groups a key may be an aggregate of the list, by its name.
+            key = _key(field)
+        return self._with(
+            order=[*self._s["order"], (key, _direction(direction), _collation(collate))]
+        )
+
+    def limit(self: Q, n: int) -> Q:
+        return self._with(limit=_whole(n, "limit"))
+
+    def offset(self: Q, n: int) -> Q:
+        return self._with(offset=_whole(n, "offset"))
+
+    def require(self: Q, n: int, *, reason: str | None = None) -> Q:
+        """`require n`: the rows the query answers, after `limit`, must
+        number `n`, or it is refused (412, `unmet`) and the batch it is in
+        put back, as a write's `require=n` is -- a checkout's guard on a
+        read: `.where(sku=sku, price=price).require(1)`.
+
+        `reason` says why in the refusal, `require n else '<reason>'`: the
+        error's `reason`, by which a caller tells "no such coupon" from
+        "insufficient funds" where a batch's `at` moves with every statement
+        added in front -- `.require(1, reason="no such coupon")`."""
+        return self._with(require=_require_clause(n, reason))
+
+    # ---------------------------------------------------------- the text
+
+    def to_fennecql(self) -> tuple[str, list]:
+        """The statement and its parameters, as they would be sent."""
+        bind = _Binder()
+        return self._text(bind), bind.params
+
+    def _inner(self, bind: _Binder) -> str:
+        """The text as an inner query of `in`, its values bound by the
+        query around it: numbered where its text stands, and a param the two
+        share one `$n`."""
+        s = self._s
+        # One column is the list; the engine refuses the rest too.
+        if (
+            s["project"] is None
+            or len(s["project"]) != 1
+            or s["count"]
+            or s["lookups"]
+            or s["marks"]
+            or s["facets"]
+        ):
+            # The JavaScript builder's spelling, word for word: every
+            # builder's refusal is the same text.
+            raise _err(
+                f"an inner query of `in` selects exactly one column: "
+                f"from('{s['collection']}').select('id')"
+            )
+        if s["require"]:
+            raise _err("an inner query of `in` takes no require: the query around it does")
+        return self._text(bind)
+
+    def _text(self, bind: _Binder) -> str:
+        s = self._s
+        near, match, rerank, fuse = s["near"], s["match"], s["rerank"], s["fuse"]
+        lookups, count, order = s["lookups"], s["count"], s["order"]
+        marks, facets = s["marks"], s["facets"]
+        # The engine refuses each of these too; failing here sends nothing.
+        if s["group"] and not s["aggregate"]:
+            keys = ", ".join(k if isinstance(k, str) else k.sql for k in s["group"])
+            raise _err(f"group {keys} needs an aggregate in select: 'count(*)'")
+        if s["aggregate"]:
+            # Ungrouped, `order`, `limit` and `offset` pick the rows folded;
+            # a lookup hangs off the groups, keyed by a column. Beside them
+            # `match` is a filter: the rows it finds are folded.
+            clash = "near" if near else "count" if count and not s["group"] else None
+            if clash:
+                raise _err(f"aggregates cannot be combined with {clash}")
+            if not s["group"] and s["require"]:
+                raise _err("require counts the rows a query answers, and an aggregate answers one")
+        if marks:
+            what = "highlight" if marks[0]["words"] is None else "snippet"
+            if not match:
+                raise _err(f"{what} needs match: it marks the terms match found")
+            if s["aggregate"]:
+                raise _err(f"{what} marks a row's text; aggregates answer groups")
+        if facets:
+            if near:
+                raise _err(
+                    "facet counts the rows a filter or match selects, and near ranks every "
+                    "row: ask the facets without near"
+                )
+            if s["aggregate"]:
+                raise _err("facet cannot be combined with aggregates: group counts by value")
+        if rerank and not match:
+            raise _err("rerank needs match: it reorders what match found")
+        if match and near and not fuse:
+            raise _err("match and near cannot be combined: both order the result; fuse() ranks by both")
+        if fuse and not (match and near):
+            raise _err("fuse combines match and near: the query needs both")
+        if fuse and rerank:
+            raise _err("fuse and rerank are two ways to use a vector with match: pick one")
+        if lookups:
+            clash = "near" if near else "match" if match else "rerank" if rerank else None
+            if clash:
+                raise _err(f"lookup cannot be combined with {clash}")
+            if count and not lookups[0]["required"]:
+                raise _err(
+                    "count cannot be used with lookup unless it is required: there is "
+                    "nothing to attach children to"
+                )
+            if len(lookups) > MAX_LOOKUP_DEPTH:
+                raise _err(f"lookup chained too deep: at most {MAX_LOOKUP_DEPTH} levels")
+            seen = [s["collection"]]
+            for level in lookups:
+                if level["collection"] in seen:
+                    raise _err(
+                        f"{level['collection']} cannot look itself up: both sides would "
+                        "answer to the same name"
+                    )
+                seen.append(level["collection"])
+        if count:
+            # Beside `count` `match` is a filter: it counts the rows it finds.
+            extra = self._extra_clause(counts=True) or ("require" if s["require"] else None)
+            if extra:
+                raise _err(f"count cannot be used with `{extra}`")
+        sql = f"get {s['collection']}"
+        # The marks after the fields `select` named, or after every field.
+        items = []
+        for m in marks:
+            item = f"{'highlight' if m['words'] is None else 'snippet'}({m['field']}"
+            if m["words"] is not None:
+                item += f", {m['words']}"
+            # A snippet's tags come after its ellipsis, so tags without one
+            # bind the empty one.
+            if "ellipsis" in m or (m["words"] is not None and "pre" in m):
+                item += f", {bind(m.get('ellipsis', ''), 'snippet')}"
+            if "pre" in m:
+                item += f", {bind(m['pre'], m['field'])}, {bind(m['post'], m['field'])}"
+            items.append(item + ")")
+        # The list's values are bound first: they come first in the text.
+        cols = None if s["project"] is None else [_column_text(c, bind) for c in s["project"]]
+        if cols or items:
+            sql += f" select {', '.join([*(cols or ['*']), *items])}"
+        where = self._where(bind)
+        if where:
+            sql += f" where {where}"
+        if s["group"]:
+            sql += f" group {', '.join(_column_text(k, bind) for k in s['group'])}"
+        def near_text() -> str:
+            out = f" near {near[0]} {bind(near[1], near[0])}"
+            if near[2] is not None:
+                out += f" ef {near[2]}"
+            return out + (" exact" if near[3] else "")
+
+        # Before `match` unless `match` was called first: a `fuse` reads both
+        # ways, and the text keeps the chain's order.
+        match_first = bool(match) and s["match_first"]
+        if near and not match_first:
+            sql += near_text()
+        if match:
+            sql += f" match {match[0]} {bind(match[1], match[0])}"
+            # `True` is the parser's default, `fuzzy` alone (2 edits); a
+            # number is written.
+            if match[2] is True:
+                sql += " fuzzy"
+            elif match[2] is not None:
+                sql += f" fuzzy {match[2]}"
+            if match[3]:
+                sql += " prefix"
+        if near and match_first:
+            sql += near_text()
+        if rerank:
+            sql += f" rerank {rerank[0]} {bind(rerank[1], rerank[0])}"
+            if rerank[2] is not None:
+                sql += f" candidates {rerank[2]}"
+        if fuse:
+            sql += " fuse"
+            if fuse[0] is not None:
+                sql += f" k {fuse[0]}"
+            if fuse[1] is not None:
+                sql += f" candidates {fuse[1]}"
+        for i, k in enumerate(order):
+            sql += f"{' order ' if i == 0 else ', '}{_sort_key(k, bind)}"
+        if s["limit"] is not None:
+            sql += f" limit {bind(s['limit'], 'limit')}"
+        if s["offset"]:
+            sql += f" offset {bind(s['offset'], 'offset')}"
+        # Before a lookup, whose clauses are the children's.
+        sql += s["require"]
+        if count:
+            sql += " count"
+        if facets:
+            sql += " facet " + ", ".join(
+                f
+                + ("" if top is None else f" top {bind(top, 'top')}")
+                + ("" if bounds is None else f" ranges [{', '.join(bounds)}]")
+                + (" disjunctive" if disjunctive else "")
+                for f, top, bounds, disjunctive in facets
+            )
+        # Terminal, so every clause after it is the child's -- and last, so
+        # its parameters come after the parent's.
+        def side(names: list[str]) -> str:
+            return f"({', '.join(names)})" if len(names) > 1 else names[0]
+
+        for level in lookups:
+            sql += f" lookup {level['collection']} on {side(level['on'])}"
+            if level["parent"]:
+                sql += f" = {side(level['parent'])}"
+            if level["required"]:
+                sql += " required"
+            if level["project"]:
+                sql += f" select {', '.join(_column_text(c, bind) for c in level['project'])}"
+            root = _prune(Cond("and", items=level["cond"]))
+            if root is not None:
+                sql += f" where {_render(root, bind)}"
+            if level["group"]:
+                sql += f" group {', '.join(_column_text(k, bind) for k in level['group'])}"
+            for i, k in enumerate(level["order"]):
+                sql += f"{' order ' if i == 0 else ', '}{_sort_key(k, bind)}"
+            if level["limit"] is not None:
+                sql += f" limit {bind(level['limit'], 'limit')}"
+            if level["offset"]:
+                sql += f" offset {bind(level['offset'], 'offset')}"
+        return sql
+
+    def to_insert(
+        self,
+        docs: Mapping | Sequence[Mapping],
+        *,
+        if_absent: bool = False,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+    ) -> tuple[str, list]:
+        """The `put` of a document or a list of them, not sent. With
+        `if_absent=True`, `put ... if absent`: a document whose id or
+        `@unique` value is held is passed over, and not counted. With
+        `require=n` on any write, `... require n`: unless it wrote exactly
+        `n` rows it is refused (412) and its batch put back; `reason=` beside
+        it, `require n else '<reason>'`, is the refusal's `reason`.
+        `returning=True`, or a list of fields, answers the rows written, ids
+        and all."""
+        return self._put("put", docs, if_absent, require, reason, returning)
+
+    def to_insert_new(
+        self,
+        docs: Mapping | Sequence[Mapping],
+        *,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+    ) -> tuple[str, list]:
+        """The `insert` of a document or a list of them, not sent: one
+        naming an id a row holds is refused -- 409, `duplicate` -- and the
+        statement, a block of one, put back whole, where `to_insert`'s `put`
+        writes over that row. `require`, `reason` and `returning` as
+        `to_insert`'s; no `if_absent`, which passes over a held id where
+        this refuses it."""
+        return self._put("insert", docs, False, require, reason, returning)
+
+    def _put(
+        self, verb: str, docs: Any, if_absent: Any, require: Any, reason: Any, returning: Any
+    ) -> tuple[str, list]:
+        # Both verbs are checked as `insert`, so their refusals read alike.
+        self._assert_plain("insert")
+        items = list(docs) if isinstance(docs, (list, tuple)) else [docs]
+        if not items:
+            raise _err("cannot write an empty document list")
+        bind = _Binder()
+        body = ", ".join(_render_doc(d, bind, "insert") for d in items)
+        absent = " if absent" if if_absent is True else ""
+        tail = _returning_clause(returning) + _require_clause(require, reason)
+        many = body if len(items) == 1 else f"[{body}]"
+        return f"{verb} {self.collection} {many}{absent}{tail}", bind.params
+
+    def to_update(
+        self,
+        patch: Mapping,
+        *,
+        all: bool = False,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+    ) -> tuple[str, list]:
+        """The `set` of the rows the filter names, not sent. `order` and
+        `limit` before it pick the rows it writes -- the page a `get` with
+        them answers -- and `returning=True`, or a list of fields, answers
+        them as written: a job queue's claim,
+        `q.where(raw("run_at <= now()")).order("run_at").limit(10)
+        .update({...}, returning=True)`."""
+        self._assert_plain("update")
+        bind = _Binder()
+        body = _render_doc(patch, bind, "update")
+        where = self._require_filter("update", all, bind)
+        tail = f"{self._pick(returning, bind)}{_require_clause(require, reason)}"
+        return f"set {self.collection} {body}{where}{tail}", bind.params
+
+    def to_upsert(
+        self,
+        docs: Mapping | Sequence[Mapping],
+        patch: Mapping,
+        *,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+    ) -> tuple[str, list]:
+        """The upsert, `put ... if absent else set {patch}`, not sent: a
+        document whose id or first `@unique` value a row holds sets that row
+        by the patch -- an update's, `inc(n)` and `expr(...)` with it, and
+        in an expression `new.f` the document's own `f` -- and every other
+        one is inserted. The documents' parameters come first, then the
+        patch's."""
+        self._assert_plain("upsert")
+        items = list(docs) if isinstance(docs, (list, tuple)) else [docs]
+        if not items:
+            raise _err("cannot write an empty document list")
+        bind = _Binder()
+        body = ", ".join(_render_doc(d, bind, "insert") for d in items)
+        patched = _render_doc(patch, bind, "update")
+        tail = _returning_clause(returning) + _require_clause(require, reason)
+        many = body if len(items) == 1 else f"[{body}]"
+        return f"put {self.collection} {many} if absent else set {patched}{tail}", bind.params
+
+    def to_delete(
+        self,
+        *,
+        all: bool = False,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+    ) -> tuple[str, list]:
+        """The `del` of the rows the filter names, not sent; `order`,
+        `limit` and `returning` as `to_update`'s, the rows answered as they
+        were: a pop."""
+        self._assert_plain("delete")
+        bind = _Binder()
+        where = self._require_filter("delete", all, bind)
+        tail = f"{self._pick(returning, bind)}{_require_clause(require, reason)}"
+        return f"del {self.collection}{where}{tail}", bind.params
+
+    # `near`, `offset`, `select` mean something only to a read; dropped from
+    # a write, `.offset(1).delete()` would delete from the first row. `order`
+    # and `limit` pick the rows an update or a delete writes.
+    def _assert_plain(self, verb: str) -> None:
+        if self._s["require"]:
+            raise _err(f"{verb} takes require as its option: {verb}(..., {{ require: n }})")
+        extra = self._extra_clause(verb in ("update", "delete"))
+        if extra:
+            raise _err(f"{verb} cannot be used with `{extra}`")
+        if self._s["lookups"]:
+            raise _err(f"{verb} cannot be used with `lookup`")
+        if self._s["facets"]:
+            raise _err(f"{verb} cannot be used with `facet`")
+        if verb in ("insert", "upsert") and self._s["cond"]:
+            raise _err(f"{verb} cannot be used with `where`")
+
+    def _extra_clause(self, picks: bool = False, counts: bool = False) -> str | None:
+        s = self._s
+        return (
+            "near" if s["near"]
+            else "match" if s["match"] and not counts
+            else "rerank" if s["rerank"]
+            else "order" if s["order"] and not picks
+            else "limit" if s["limit"] is not None and not picks
+            else "offset" if s["offset"]
+            else "select" if s["project"]
+            else None
+        )  # fmt: skip
+
+    # An update's or a delete's ` order ... limit $n returning ...`.
+    def _pick(self, returning: Any, bind: _Binder) -> str:
+        sql = ""
+        for i, k in enumerate(self._s["order"]):
+            sql += f"{' order ' if i == 0 else ', '}{_sort_key(k, bind)}"
+        if self._s["limit"] is not None:
+            sql += f" limit {bind(self._s['limit'], 'limit')}"
+        return sql + _returning_clause(returning)
+
+    # An update or delete of every row is too easy to do by accident and
+    # cannot be undone: it has to be asked for. A `limit` bounds it.
+    def _require_filter(self, verb: str, everything: bool, bind: _Binder) -> str:
+        where = self._where(bind)
+        if where:
+            return f" where {where}"
+        if everything is True or self._s["limit"] is not None:
+            return ""
+        raise _err(
+            f"an unfiltered {verb} covers the whole collection; if you mean it, "
+            f"{verb}({{ all: true }})"
+        )
+
+    def _where(self, bind: _Binder) -> str | None:
+        root = _prune(Cond("and", items=self._s["cond"]))
+        return None if root is None else _render(root, bind)
+
+    def _client(self) -> Any:
+        client = self._s["client"]
+        if client is None:
+            raise _err(
+                "query is not bound to a connection: use db.collection(...) "
+                "(to_fennecql() if you only want the text)"
+            )
+        return client
+
+    def _counted(self: Q) -> Q:
+        return self._with(count=True)
+
+
+def _render_doc(doc: Any, bind: _Binder, write: str) -> str:
+    if not isinstance(doc, Mapping):
+        raise _err("expected a document object")
+    pairs = [f"{_path(k)}: {_value(k, v, bind, write)}" for k, v in doc.items()]
+    if not pairs:
+        raise _err("cannot write an empty document")
+    return "{" + ", ".join(pairs) + "}"
+
+
+class FacetCount(NamedTuple):
+    """A value a facet counted -- any JSON value, `None` for the rows whose
+    field is null -- and how many rows hold it."""
+
+    value: Any
+    count: int
+
+
+class Rows(list):
+    """A query's rows, a dict each -- a list, and equal to one -- with what
+    `facet` counted beside them as `facets`: each field asked, in the order
+    asked, to its values most first. Empty when the query asked none."""
+
+    facets: dict[str, list[FacetCount]]
+
+    def __init__(self, rows: Iterable = (), facets: Mapping | None = None):
+        super().__init__(rows)
+        self.facets = {
+            k: [FacetCount(c.get("value"), c.get("count", 0)) for c in v]
+            for k, v in (facets or {}).items()
+        }
+
+
+def _rows(answer: Any) -> Rows:
+    """The rows of a `/query` answer: the bare array, or -- for a query that
+    asked facets -- `{"rows": [...], "facets": {...}}`, the counts beside
+    the rows since they answer for every row matched, not one."""
+    if isinstance(answer, Rows):
+        return answer
+    if isinstance(answer, list):
+        return Rows(answer)
+    if isinstance(answer, Mapping) and isinstance(answer.get("rows"), list):
+        return Rows(answer["rows"], answer.get("facets"))
+    return Rows()
+
+
+def _affected(answer: Any) -> int:
+    return answer.get("affected", 0) if isinstance(answer, dict) else 0
+
+
+def _written(answer: Any, returning: Any) -> Any:
+    """A write's answer: its count, or with `returning` its rows."""
+    if returning is None or returning is False:
+        return _affected(answer)
+    return _rows(answer)
+
+
+def _returning_clause(returning: Any) -> str:
+    """` returning ...` for a write's `returning`: `True` or `["*"]` every
+    field, or the fields named, each a field or a path."""
+    if returning is None or returning is False:
+        return ""
+    if returning is True:
+        return " returning *"
+    if isinstance(returning, str) or not isinstance(returning, (list, tuple)) or not returning:
+        raise _err("returning names the fields it answers, or * for every one")
+    if "*" in returning:
+        if len(returning) > 1:
+            raise _err("returning * answers every field: it takes no other")
+        return " returning *"
+    return " returning " + ", ".join(_path(f) for f in returning)
+
+
+def _count(answer: Any) -> int:
+    rows = _rows(answer)
+    return rows[0].get("count", 0) if rows and isinstance(rows[0], dict) else 0
+
+
+class _Built:
+    """The `read` a builder's read hands `Client` and `AsyncClient`, true as
+    `read=True` is: a read the builder made itself, a `get` whatever the
+    caller says, which may go again after a reset (`Retry`). A caller's
+    `read=True` is a claim nothing checks at home, and grants no resend."""
+
+    __slots__ = ()
+
+    def __bool__(self) -> bool:
+        return True
+
+    def __repr__(self) -> str:
+        return "_BUILT"
+
+
+_BUILT = _Built()
+
+
+def _read_kw(client: Any) -> dict:
+    """What a query's read passes its client beside the text: `read=_BUILT`
+    to `Client` and `AsyncClient` -- one reading near (`reads="nearest"`)
+    marks it for a read replica near it, and either sends it again after a
+    reset, as a read the builder made may be (`Retry`); nothing to any
+    other, a client of one's own making among them."""
+    return {"read": _BUILT} if getattr(client, "reads", None) in ("home", "nearest") else {}
+
+
+class Query(_Builder):
+    """A query over a `Client`: immutable, its endpoints sending it."""
+
+    __slots__ = ()
+
+    def rows(self) -> Rows:
+        """Every row the query answers, a dict each -- and, for a query that
+        asked facets, the counts as the list's `facets`."""
+        client = self._client()
+        return _rows(client.query(*self.to_fennecql(), **_read_kw(client)))
+
+    def first(self) -> dict | None:
+        """The first row, or None: the query with `limit 1`."""
+        rows = self.limit(1).rows()
+        return rows[0] if rows else None
+
+    def count(self) -> int:
+        """How many rows match: `get ... count`, no row decoded."""
+        q = self._counted()
+        client = q._client()
+        return _count(client.query(*q.to_fennecql(), **_read_kw(client)))
+
+    def explain(self) -> list[str]:
+        """The path the query took, a line a step; the query runs to tell."""
+        sql, params = self.to_fennecql()
+        client = self._client()
+        answer = client.query(f"explain {sql}", params, **_read_kw(client))
+        return [r.get("plan") for r in _rows(answer)]
+
+    def insert(
+        self,
+        docs: Mapping | Sequence[Mapping],
+        *,
+        if_absent: bool = False,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+    ) -> Any:
+        """`put` of a document or a list of them: how many were written --
+        with `if_absent=True` those whose id or `@unique` value was held
+        left out, so a lock taken answers 1 and one held 0 -- or with
+        `returning` the rows written, ids and all, in the documents' order.
+        With `require=n` (on `update` and `delete` too) a write that did not
+        write exactly `n` rows is refused, 412, and its batch put back;
+        `reason="..."` beside it is the `FennecError`'s `reason`, which tells
+        one refusal from another where a batch's `at` moves with every
+        statement added in front."""
+        if isinstance(docs, (list, tuple)) and not docs:
+            return _written({}, returning)
+        text = self.to_insert(
+            docs, if_absent=if_absent, require=require, reason=reason, returning=returning
+        )
+        return _written(self._client().query(*text), returning)
+
+    def insert_new(
+        self,
+        docs: Mapping | Sequence[Mapping],
+        *,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+    ) -> Any:
+        """`insert` of a document or a list of them, refused whole (409,
+        `duplicate`) where one names an id a row holds: a row made once,
+        never written over, where `insert`'s `put` writes over it. How many
+        were written, or with `returning` the rows written, ids and all."""
+        if isinstance(docs, (list, tuple)) and not docs:
+            return _written({}, returning)
+        text = self.to_insert_new(docs, require=require, reason=reason, returning=returning)
+        return _written(self._client().query(*text), returning)
+
+    def upsert(
+        self,
+        docs: Mapping | Sequence[Mapping],
+        patch: Mapping,
+        *,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+    ) -> Any:
+        """`put ... if absent else set`: each document inserted, or where a
+        row holds its id or `@unique` value, that row set by the patch --
+        `upsert({"key": k, "n": 1}, {"n": expr("n + new.n")})`. How many
+        rows it set and made together, or with `returning` those rows."""
+        if isinstance(docs, (list, tuple)) and not docs:
+            return _written({}, returning)
+        text = self.to_upsert(docs, patch, require=require, reason=reason, returning=returning)
+        return _written(self._client().query(*text), returning)
+
+    def update(
+        self,
+        patch: Mapping,
+        *,
+        all: bool = False,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+        wait: float | None = None,
+    ) -> Any:
+        """`set` over the rows the filter names: how many it changed, or
+        with `returning` the rows as written. With no filter it is refused
+        unless `all=True` or a `limit` bounds it. With `wait`, one that
+        writes nothing is held at the server until it can, or that many
+        seconds: a claim waiting for a job."""
+        text = self.to_update(patch, all=all, require=require, reason=reason, returning=returning)
+        return _written(self._client().query(*text, **_held(wait)), returning)
+
+    def delete(
+        self,
+        *,
+        all: bool = False,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+        wait: float | None = None,
+    ) -> Any:
+        """`del` of the rows the filter names: how many it deleted, or with
+        `returning` the rows as they were. With no filter it is refused
+        unless `all=True` or a `limit` bounds it. `wait` as `update`'s."""
+        text = self.to_delete(all=all, require=require, reason=reason, returning=returning)
+        return _written(self._client().query(*text, **_held(wait)), returning)
+
+
+class AsyncQuery(_Builder):
+    """A query over an `AsyncClient`: `Query`'s endpoints, awaited."""
+
+    __slots__ = ()
+
+    async def rows(self) -> Rows:
+        client = self._client()
+        return _rows(await client.query(*self.to_fennecql(), **_read_kw(client)))
+
+    async def first(self) -> dict | None:
+        rows = await self.limit(1).rows()
+        return rows[0] if rows else None
+
+    async def count(self) -> int:
+        q = self._counted()
+        client = q._client()
+        return _count(await client.query(*q.to_fennecql(), **_read_kw(client)))
+
+    async def explain(self) -> list[str]:
+        sql, params = self.to_fennecql()
+        client = self._client()
+        answer = await client.query(f"explain {sql}", params, **_read_kw(client))
+        return [r.get("plan") for r in _rows(answer)]
+
+    async def insert(
+        self,
+        docs: Mapping | Sequence[Mapping],
+        *,
+        if_absent: bool = False,
+        require: int | None = None,
+        reason: str | None = None,
+    ) -> int:
+        if isinstance(docs, (list, tuple)) and not docs:
+            return 0
+        text = self.to_insert(docs, if_absent=if_absent, require=require, reason=reason)
+        return _affected(await self._client().query(*text))
+
+    async def insert_new(
+        self,
+        docs: Mapping | Sequence[Mapping],
+        *,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+    ) -> Any:
+        if isinstance(docs, (list, tuple)) and not docs:
+            return _written({}, returning)
+        text = self.to_insert_new(docs, require=require, reason=reason, returning=returning)
+        return _written(await self._client().query(*text), returning)
+
+    async def upsert(
+        self,
+        docs: Mapping | Sequence[Mapping],
+        patch: Mapping,
+        *,
+        require: int | None = None,
+        reason: str | None = None,
+    ) -> int:
+        if isinstance(docs, (list, tuple)) and not docs:
+            return 0
+        text = self.to_upsert(docs, patch, require=require, reason=reason)
+        return _affected(await self._client().query(*text))
+
+    async def update(
+        self,
+        patch: Mapping,
+        *,
+        all: bool = False,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+        wait: float | None = None,
+    ) -> Any:
+        text = self.to_update(patch, all=all, require=require, reason=reason, returning=returning)
+        return _written(await self._client().query(*text, **_held(wait)), returning)
+
+    async def delete(
+        self,
+        *,
+        all: bool = False,
+        require: int | None = None,
+        reason: str | None = None,
+        returning: Any = None,
+        wait: float | None = None,
+    ) -> Any:
+        text = self.to_delete(all=all, require=require, reason=reason, returning=returning)
+        return _written(await self._client().query(*text, **_held(wait)), returning)
+
+
+def _held(wait: float | None) -> dict:
+    """`wait` for the client's `query`, where it was given one: a client
+    that holds nothing takes the statement alone."""
+    return {} if wait is None else {"wait": wait}
+
+
+# ` require n` for a write's `require=n`: the rows it must write, a whole
+# number from 0 written in -- FennecQL takes no parameter there: the count is
+# what the statement guards, a constant of the code, where a page's `limit`
+# and `offset` change with each request and go as parameters. A bool is an
+# int to Python and is refused, as JavaScript's builder refuses `true`.
+def _require_clause(n: Any, reason: Any = None) -> str:
+    if n is None:
+        if reason is not None:
+            raise _err("a reason says why a require refused, and goes with one")
+        return ""
+    if isinstance(n, bool) or not isinstance(n, int) or n < 0:
+        raise _err(f"require takes a count of rows, a whole number from 0 (got {n})")
+    return f" require {n}{_reason_clause(reason)}"
+
+
+# ` else '<reason>'` for a require's `reason`: written into the text, a
+# quote doubled and a backslash escaped, as FennecQL takes it -- never a
+# parameter, as the count is not: it is the statement's own words, by which
+# a caller tells one refusal from another. 1 to 200 bytes of UTF-8, as the
+# parser holds it: bytes, not characters, so "ş" counts 2; a lone surrogate
+# is no text UTF-8 can send, refused as one rather than a UnicodeEncodeError.
+# No backtick: the refusal quotes its statement with them, and the reason is
+# read back as its words up to the first "(`".
+def _reason_clause(reason: Any) -> str:
+    if reason is None:
+        return ""
+    try:
+        size = len(reason.encode("utf-8")) if isinstance(reason, str) else 0
+    except UnicodeEncodeError:
+        size = 0
+    if not 1 <= size <= 200:
+        raise _err("a require's reason is a text of 1 to 200 bytes")
+    if "`" in reason:
+        raise _err("a require's reason holds no backtick")
+    return " else '" + reason.replace("\\", "\\\\").replace("'", "''") + "'"
+
+
+def collection(name: str) -> Query:
+    """A query bound to no client: for its text alone, `to_fennecql()`."""
+    return Query(name)
+
+
+# A named statement's name: ASCII letters, digits and `_`, starting with a
+# letter, at most 59 bytes -- the engine's rule (`named::valid_name`), a path
+# segment with nothing to escape. The name is the one thing of a call written
+# into its text, so this is its injection boundary. `fullmatch`, not `$`,
+# which also matches before a trailing newline.
+_STATEMENT = re.compile(r"[A-Za-z][A-Za-z0-9_]{0,58}")
+
+
+def _given(v: Any, what: str) -> Mapping | None:
+    """A call's arguments or claims: an object of values by name, or none."""
+    if v is None:
+        return None
+    if not isinstance(v, Mapping):
+        raise _err(f"a call's {what} are an object of values by name")
+    return v
+
+
+class Call:
+    """A call of a named statement: `call <name> $1`, its arguments the one
+    parameter -- a mapping, by name -- and `claims=` after them `as $2`, the
+    claims the server's token makes the call with (a scoped token's own are
+    its token's, and it may not say them). Bound to no collection or client,
+    so `call(...)` stands beside `collection(...)`:
+
+        call("transfer", {"from": 1, "to": 2, "amount": 300}).to_call()
+        # ("call transfer $1", [{"from": 1, "to": 2, "amount": 300}])
+
+    `db.call(name, args)` runs it. No arguments is a statement of none --
+    `call stamp` -- and an empty mapping is still one argument. The values
+    are parameters as a query's are -- a `datetime` its ISO text, an
+    `array.array` its numbers -- and never the text. Immutable."""
+
+    __slots__ = ("_name", "_args", "_claims")
+
+    def __init__(self, name: str, args: Mapping | None = None, *, claims: Mapping | None = None) -> None:
+        if not isinstance(name, str) or not _STATEMENT.fullmatch(name):
+            raise _err(f"invalid statement name: {_quote(name)}")
+        object.__setattr__(self, "_name", name)
+        object.__setattr__(self, "_args", _given(args, "arguments"))
+        object.__setattr__(self, "_claims", _given(claims, "claims"))
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        raise AttributeError("a Call is immutable")
+
+    def __delattr__(self, key: str) -> None:
+        raise AttributeError("a Call is immutable")
+
+    def __repr__(self) -> str:
+        return f"Call({self._name!r})"
+
+    @property
+    def name(self) -> str:
+        """The statement's name."""
+        return self._name
+
+    def to_call(self) -> tuple[str, list]:
+        """The call's FennecQL and its parameters, `(text, params)`: what
+        `Client.query` and a `batch` take."""
+        bind = _Binder()
+        sql = f"call {self._name}"
+        if self._args is not None:
+            sql += f" {bind(self._args, 'argument')}"
+        if self._claims is not None:
+            sql += f" as {bind(self._claims, 'claim')}"
+        return sql, bind.params
+
+
+def call(name: str, args: Mapping | None = None, *, claims: Mapping | None = None) -> Call:
+    """A call of the named statement `name`, for its text alone,
+    `to_call()`; `Client.call` sends one."""
+    return Call(name, args, claims=claims)
+