Immutable generated queries¶
Each generated package exports a query facade bound to that package's verified projection. It provides the same supported application outcomes in Python, TypeScript/Node, and Rust without routing generated models through handwritten model descriptors.
Start a session¶
from app_models import Age, Employment, Person
session = Person.query(db)
person = session.exact(Person)
employment = session.exact(Employment)
Person.query(db) and the package's QuerySession(db) constructor produce the
same package-scoped session. The connection decides where terminals run: a
direct Database or TransactionContext, or a proxy connection (see
Proxy connections). Composition is synchronous; every
terminal is a coroutine on every connection, so Python code awaits it.
TypeScript is the same: new QuerySession(connection) takes a RustDatabase,
a transaction, or a proxy connection, and every terminal returns a Promise.
Use exact(Model) for exactly one schema type and subtypes(Model) for a
polymorphic binding. Concrete result evidence determines the generated class
used for hydration.
Match fields and roles¶
adult = person.field(Person.age).gte(Age(18))
employee = employment.role(Employment.employee).connects(person)
query = session.query(person, employment).where(adult, employee)
Bindings, field tokens, role tokens, predicates, selections, and queries are immutable and carry one projection identity. Cross-package composition fails before execution.
Low-level Query V2 plans¶
The generated facade is the usual application API. The separately retained
@type-bridge/node/query-v2 entry point authors a complete prepared plan when
an application needs the low-level Query V2 vocabulary without model classes.
Rust owns its identities, validation, canonical bytes, and capabilities.
The equivalent Node authoring uses the same operation names and order. Keep the low-level authority outside this builder function so the plan vocabulary cannot silently replace the generated package's authority:
import {
QueryPlanBuilder,
type AuthoredQueryInvocation,
type QueryV2Authority,
} from "@type-bridge/node/query-v2";
function authorInvocation(authority: QueryV2Authority): AuthoredQueryInvocation {
const builder = new QueryPlanBuilder(authority);
const person = builder.binding("person");
const name = builder.binding("name");
const wanted = builder.input("wanted_name", "string", false);
builder.match([
builder.isa(person, "entity", "smoke-person", true),
builder.has(person, name, "smoke-name"),
builder.value(
"equal",
builder.bindingOperand(name),
builder.inputOperand(wanted),
),
]);
return builder.finalizeRows([person, name]).rows([["Alice"]]);
}
Builder transitions perform no provider or network I/O. Finalization is
terminal, and a rejected transition leaves the builder at its preceding valid
state. Explicit construction of QueryV2Authority remains a low-level API for
integrators that already own canonical declared-schema bytes and their trust
policy. schema export-declared is retained only as a debug/compatibility tool;
generated sessions do not call it, read its JSON, or use it as an authoring
input.
Connectivity and explicit cross joins¶
Every selected binding must be connected by a predicate, match witness, or bounded reachability path. An intentional Cartesian product must be declared:
left = session.exact(Person)
right = session.exact(Person)
rows = await (
session.query(left, right)
.allow_cross_join(left, right)
.rows(limit=10)
)
This prevents a missing join predicate from silently becoming an expensive cross product.
Bounded reachability¶
source = session.exact(Person)
target = session.exact(Person)
path = session.reachable(
source,
target,
NetworkLink,
NetworkLink.origin,
NetworkLink.destination,
min_depth=1,
max_depth=3,
)
connected = await session.query(source, target).where(path).rows(limit=100)
The relation and both role tokens are generated evidence. Depth bounds are mandatory and validated before execution.
Selection shapes¶
One binding produces one model; multiple bindings produce a tuple:
one_person = await session.query(person).one()
pairs = await session.query(person, employment).where(employee).rows(limit=100)
Generated Python and TypeScript support positional selections through 16 slots. Named selections map into an immutable declared row shape. Collection preserves one root with zero or more related values:
from dataclasses import dataclass
@dataclass(frozen=True, slots=True)
class EmploymentRow:
person: Person
employments: tuple[Employment, ...]
page = await (
session.query_as(
EmploymentRow,
person=person,
employments=employment.collect().distinct(),
)
.where(employee)
.page_by(person, limit=25, include_total=True)
)
Collections may have their own generated-field ordering. page_by keeps root
pagination distinct from collection membership.
Terminals¶
await query.one()
await query.first(order_by=(person.field(Person.person_id).asc(),))
await query.rows(limit=100, offset=0)
await query.page_by(person, limit=25, include_total=True)
await query.count_by(person)
await query.exists_by(person)
one requires exactly one result. first returns None when empty. Materialized
rows and pages are bounded; unbounded implicit fetches are not part of the
generated contract.
Direct reductions and grouping¶
from app_models import aggregate
score = person.field(Person.score)
count, total, mean = await session.query(person).aggregate(
person,
aggregate.count(),
aggregate.sum(score),
aggregate.mean(score),
)
grouped = await (
session.query(person, employment)
.where(employee)
.group_by(person, employment)
.aggregate(aggregate.count(), aggregate.max(score))
)
Reducer inputs are owner/scalar checked. Grouping returns exact generated group values plus typed reducer tuples.
Proxy connections¶
A proxy connection runs the same session against a TypeBridge server instead of TypeDB. Only the connection object changes; the query program is the same:
from app_models import ExchangeConnection, Person, QueryExecutionResourceLimits, connect_proxy
# The built-in HTTP route to the server's /v2/capabilities and /v2/query.
session = Person.query(connect_proxy("https://typebridge.example"))
# Or a host-owned transport that routes and authenticates itself.
session = Person.query(
ExchangeConnection(advertisement_bytes, exchange),
resources=QueryExecutionResourceLimits(items=100, timeout_milliseconds=30_000),
)
person = session.exact(Person)
rows = await session.query(person).rows(limit=50)
Both connections reconstruct Query V2 authority from private, verified package
evidence; no authority file or low-level QueryV2Authority argument is
involved. connect_proxy fetches the advertisement over the configured TLS
connection, or takes a pinned advertisement=; headers= carries caller
authentication. ExchangeConnection(advertisement, exchange) takes
advertisement bytes and a coroutine that sends one request and returns its
reply; the caller owns transport, credentials, and retry policy. Either takes
answer_limits=, the ceiling every session on the connection runs under;
without it a proxy connection uses the proxy defaults (65,536 items,
32 MiB), lower than a direct connection's.
TypeScript passes the same connections to the same QuerySession:
import {
ExchangeConnection,
Person,
QueryExecutionResourceLimits,
QuerySession,
connectProxy,
} from "app-models";
const session = new QuerySession(await connectProxy("https://typebridge.example"));
const hosted = new QuerySession(new ExchangeConnection(advertisementBytes, exchange), {
resources: new QueryExecutionResourceLimits({ items: 100n, timeoutMilliseconds: 30_000n }),
});
const person = hosted.exact(Person);
const rows = await hosted.query(person).rows({ limit: 50n });
connectProxy takes advertisement, headers, tls, and answerLimits
options; ExchangeConnection(advertisement, exchange, { answerLimits }) takes
a function that sends one request and resolves to its reply. Composition
remains local; one terminal performs one exchange and materializes through
the same package projection as direct execution.
Rust opens either connection from one policy with SCHEMA.connect(policy)
(Direct or proxy); C runs each terminal on a proxy
connection with the same arguments as on a database
(Run a query on a database or a TypeBridge server).
Scripts without an event loop wrap a session in type_bridge_core.blocking,
which runs each terminal to completion on a private event-loop thread:
from type_bridge_core import blocking
session = blocking(Person.query(db))
person = session.exact(Person)
rows = session.query(person).rows(limit=50)
Supported remote terminals are one, first, bounded rows, page_by,
count_by, exists_by, and typed aggregate/group_by, including exact/subtype
hydration, predicates, roles, reachability, explicit cross joins, selected
shapes, all reducers, and binding/field/tuple-field grouping. Reduction replies
echo the exact root, grouping, and reducer contract and are authenticated before
materialization through the same projection as direct execution.
Staged transactions and plans in Python¶
A plan is one typed query-plan/v3 pipeline: a match with comparisons and
let_ values, then updates, inserts, puts and deletes. Plan.builder()
(type_bridge.plan) takes the generated model, field and role tokens and
forwards every call to the shared Rust builder, so the bytes equal the same
plan built in Rust, TypeScript or C. where_ and let_ carry a trailing
underscore because where and let read as keywords; comparisons are
eq, ne, lt, le, gt and ge, and + - * / % and
PlanExpr.{pow,abs,ceil,floor,round,min,max,length} build expressions.
bool, int, float, str, Decimal, date and datetime literals are
typed automatically; literal("duration", "P1D") types the rest.
from type_bridge.plan import Matched, Plan
from generated.python import Account, Item, Purchase, schema_authority
def purchase(order: str, item_id: str, account_id: str) -> Plan:
plan = Plan.builder()
item = plan.exact(Item)
buyer = plan.exact(Account)
order_input = plan.input("order_id", "string")
item_input = plan.input("item_id", "string")
account_input = plan.input("account_id", "string")
stock = plan.field(item, Item.stock)
price = plan.field(item, Item.price)
balance = plan.field(buyer, Account.balance)
plan.where_(plan.field(item, Item.item_id).eq(item_input))
plan.where_(plan.field(buyer, Account.account_id).eq(account_input))
plan.where_(stock.gt(0)).where_(balance.ge(price))
plan.update(item, Item.stock, plan.let_("next_stock", stock - 1))
plan.update(buyer, Account.balance, plan.let_("next_balance", balance - price))
(
plan.insert(Purchase)
.field(Purchase.order_id, order_input)
.player(Purchase.buyer, buyer)
.player(Purchase.item, item)
)
plan.row([order_input.value(order), item_input.value(item_id), account_input.value(account_id)])
return plan.build(schema_authority())
with db.staged_transaction() as tx: # db: type_bridge.Database
bought = tx.stage(purchase("O1", "I1", "A1"))
assert bought.result() in (Matched(1), Matched(0))
Calls never fail on content; build raises the first invalid call as a
QueryV2Error with .code (for example query_plan_builder_duplicate_name).
A handle from another builder raises TypeError at once. A generated
package's schema_authority() is its embedded, verified authority.
Database.staged_transaction(kind=None, *, commit_on_exit=True) (and
RustDatabase.staged_transaction) returns the core staged transaction:
stage(plan), commit(), rollback() and close(). Nothing opens before commit(); an omitted kind
is inferred from the staged plans. Pending.result() answers Rows(rows),
Count(count), Exists(exists) or Matched(count), raises the commit's
typed failure (.code, .failure), or raises RuntimeError before commit.
A with block commits on a clean exit unless commit_on_exit=False,
discards on an exception, and always closes.
Database.transaction() keeps its released eager context.
Replacing update_with¶
update_with(func) reads every match, runs func in Python and writes each
instance back. It is deprecated since 2.3.0, warns with a
DeprecationWarning, and is removed in 3.0. Compute the new value in the
plan with let_ instead, so the read and the write are one query:
from type_bridge.plan import Plan
from generated.python import Account, schema_authority
# Before: accounts.filter(tier=Tier("gold")).update_with(add_bonus)
plan = Plan.builder()
account = plan.exact(Account)
tier = plan.input("tier", "string")
balance = plan.field(account, Account.balance)
plan.where_(plan.field(account, Account.tier).eq(tier))
plan.update(account, Account.balance, plan.let_("next_balance", balance + 10))
plan.row([tier.value("gold")])
with db.staged_transaction() as tx:
updated = tx.stage(plan.build(schema_authority()))
Staged transactions over the proxy¶
Writes cross the proxy as staged transactions. transaction(kind) on a proxy
connection (Rust ProxyDatabase::transaction(options), Python and TypeScript
ProxyConnection.transaction(kind)) returns the core staged transaction: stage
plans (Rust and TypeScript stage and Python stage of a built Plan;
canonical query-plan/v3 bytes also through Python stage and TypeScript
stagePlan), then commit(). The commit sends the whole stack as one
typebridge.query-remote-request/v3 envelope to POST /v3/staged; the server
runs it on one TypeDB transaction and returns a signed reply that the SDK
verifies before resolving any answer. Answers and typed failures are the same
as direct execution, and commit_outcome_unknown stays an unknown outcome.
Each commit is one request under a fresh nonce, and the proxy keeps no
replies. A dropped or unverifiable reply, and a cancelled commit, leave the
outcome unknown (commit_outcome_unknown): the writes may have applied, and
the caller reads the database to find out, as after a lost direct commit.
Every other signed refusal keeps the server's code and applied nothing. Raw
TypeQL and typed match reads are not staged over the proxy; they are refused
at stage time.
The SDK verifies staged replies only under the signer it already trusts: the
/v3/capabilities advertisement must name the same executor and reply key as
the connection's advertisement, or the transaction fails with
query_remote_v3_advertisement_mismatch. It is fetched once per connection,
or pinned out of band (Rust ProxyConnectionPolicy::staged_advertisement,
Python staged_advertisement=, TypeScript stagedAdvertisement).
The server admits a staged write only from a caller an interceptor vouches for
(on_v3_write_authority), or from any caller when the operator sets
[v2] allow_unauthenticated_staged_writes; otherwise the commit fails with the
typed staged_write_not_authorized failure. The staged remote envelope
defines the wire format.
Query limits¶
A query is held to limits on its size and shape: encoded bytes, nesting depth, bindings, predicate nodes, and so on. They default to fixed ceilings. A session can lower them for an untrusted workload or raise them for a query the defaults refuse, such as a predicate with a literal over 16 MiB:
from app_models import Person, QueryLimits
session = Person.query(
db,
query_limits=QueryLimits(canonical_bytes=64 * 1024 * 1024),
)
import { QueryLimits, QuerySession } from "app-models";
const session = new QuerySession(database, {
queryLimits: new QueryLimits({ canonical_bytes: 64n * 1024n * 1024n }),
});
use type_bridge::QueryLimits;
let session = db
.query()?
.with_query_limits(QueryLimits::from_overrides([("canonical_bytes", 64 << 20)])?)?;
Proxy sessions take the same option, since a proxy connection is passed to
the same session. C callers use
<prefix>_query_session_open_with_limits with an array of named overrides.
Limits are named identically in every language. The engine validates them, so an unknown name or an unsupported value fails when the limits are built.
Raising a limit locally is not enough for a remote query: the executor
advertises the limits it enforces and a request is held to the stricter of the
two. A refusal names the limit, the maximum it was held to, and a source
of default, configured, or advertised, so it is clear whether changing
the session's limits can help. The
typed-query contract
lists every limit with its default.
Safety contract¶
- Schema and projection fingerprints are verified at package installation.
- Only exact registered generated classes and tokens are accepted.
- Queries are immutable and package-scoped.
- Disconnected selections fail unless cross joins are explicit.
- Result evidence is revalidated before hydration.
- Remote limits and capability advertisements fail closed.
The normative cross-language behavior is maintained in the unified typed-query contract.