Dataloaders
Batch field fetches without N+1 — auto-emitted PK and FK loaders from #[expose], plus #[dataloader] for custom keys.
Most “resolver looks fine but the query log is on fire” stories end here. A dataloader is a batched DB read, request-scoped, shared across one response — each parent call gets coalesced into a single query against the keys collected during that frame. NestRS builds on async-graphql for the loader runtime; the framework auto-emits the loaders relations need and lets you write your own for custom keys.
A naïve resolver loop runs one query per parent; a dataloader collapses the N
to 1:
POST /graphql { orgs { name users { name } } } └─ select * from org # 1 └─ select * from "user" where org_id = ? (per org) # N ← naïve └─ select * from "user" where org_id in ($1, … $n) # 1 ← dataloaderMost relations need no loader code
Section titled “Most relations need no loader code”A belongs_to or has_many whose relation field carries #[expose] becomes a
GraphQL field auto-resolved through a dataloader. The macro emits:
- a PK loader on the owner’s service (
<Service>ById) for every entity with#[expose(name = ..., service = ..., graphql)]— used by every inverse side to reach the parent; - an FK loader (
<Service>By<FkCol>) perbelongs_toon the FK-owning side, keyed on the parent id and the page window, so it returns one page per parent rather than a share of one global limit; PkLoadableandRelatedTo<Parent, Via>impls so the inverse side (the parent’shas_many) reaches the loader without naming the other service — no cross-feature wiring;- a
#[ComplexObject]field resolver on the wire DTO that calls the matching loader and returns the related object.
#[expose( name = "Post", service = super::super::service::PostsService, graphql, // …)]#[sea_orm::model]#[derive(Clone, Debug, DeriveEntityModel)]#[sea_orm(table_name = "post")]pub struct Model { #[sea_orm(primary_key, auto_increment = false)] #[expose] pub id: Uuid, #[expose] pub org_id: Uuid, // … #[expose(input(create, update), validate(length(min = 1)))] pub title: String, // … #[sea_orm(belongs_to, from = "org_id", to = "id")] #[expose] pub org: HasOne<crate::orgs::Entity>, // …}The relation is a field on the model — #[sea_orm(belongs_to, from, to)]
naming the two columns, #[expose] deciding it crosses the wire. There is no
enum Relation to write and no Column:: path to keep in sync;
Entities is the reference for the whole grammar.
From this, the GraphQL Post.org field resolves through a per-request
dataloader. No #[dataloader] to write, no wiring on the resolver — and
every batch runs through Repo::scoped(Action::Read), so the ability filter
applies row-level on related rows as on any other read.
Leave a single relation unexposed (no #[expose]) and write a custom
#[field_resolver] if you need a non-default shape (cursor connection,
extra filter).
Writing a custom loader
Section titled “Writing a custom loader”#[dataloader] lives in nest-rs-graphql. Use it for a key that isn’t a
relation — by_name, by_tag, a denormalized lookup. The signature is
fixed by the trait:
use std::collections::HashMap;use nest_rs::authz::Action;use nest_rs::graphql::dataloader;use nest_rs::seaorm::{Repo, ServiceError};
#[dataloader]impl PostsService { async fn by_name( &self, names: &[String], ) -> Result<HashMap<String, Vec<Post>>, ServiceError> { if names.is_empty() { return Ok(HashMap::new()); } let rows = Repo::<Posts>::scoped(Action::Read) .filter(entity::Column::Title.is_in(names.iter().cloned())) .all() .await?; Ok(group_by_name(names, rows)) }}Three properties make this loader correct:
- Empty-keys short-circuit. A frame with no keys returns the empty map without touching the database — no query, no connection drawn.
- Result, not silent empty. A DB error returns
Err(_). Never map a DB error to an emptyHashMap— that turns a failure into a silent miss, the worst kind. Repo::scoped(Read), not rawPosts::find(). The ability filter applies, so a batch on behalf of one caller never returns another tenant’s rows.
Reading a loader
Section titled “Reading a loader”A #[field_resolver] takes the loader as a parameter and calls .load_one(key)
per parent — the runtime batches every call into a single query:
#[field_resolver]async fn namesakes( &self, author: &Author, posts: &DataLoader<PostsServiceByName>,) -> Result<Vec<Post>, ServiceError> { Ok(posts.load_one(author.name.clone()).await?.unwrap_or_default())}A root field — #[query], #[mutation], #[subscription], #[entity] — takes it the
same way, and the parameter is no argument of the schema, nor part of an entity’s key:
#[query]#[authorize(Read, posts::Entity)]async fn posts_named( &self, name: String, posts: &DataLoader<PostsServiceByName>,) -> Result<Vec<Post>, ServiceError> { Ok(posts.load_one(name).await?.unwrap_or_default())}A batch carries the request’s values, never one field’s,
so a field naming a visitor’s read reads nothing
through a loader: under #[public(Read, posts::Entity)] a visitor’s batch runs with no
ability, and Repo denies every row, with the warn on nest_rs::orm. Read those rows in
the field’s own body. A caller a token backs reads through the loader by define, on either
line.
A loader’s rows are wire rows, judged where the batch builds them for the caller whose
request runs it: the batch decides the rows, and the caller’s grants their
columns,
a withheld one reading None, as a root field’s rows do. A scalar a body derives from a
Model it read whole is its own line.
The parameter is the whole wiring, and it declares the need. A loader is seeded only for an owner the app reaches, so the schema build reads the parameter and refuses a served field whose loader’s owner the app does not import, as it does for an exposed relation, naming the line to add:
a served field reads a loader this app does not reach, so every query selecting it would fail: `Author.namesakes` (declared on `features::authors::Author`) reads a loader of `features::posts::PostsService`: import `PostsModule` into the module serving `Author`A root field is named by its role, query posts_named (declared on its resolver).
The loader’s name comes from #[dataloader], so the parameter takes only one
#[dataloader] generated: the macro’s own association is what the boot reads,
and a hand-written Loader here is a compile error saying so.
The cross-entity rule
Section titled “The cross-entity rule”A loader for entity A lives on A’s service. A service that reaches
into entity B (e.g. NotificationsService returning the post it
announces) injects Arc<PostsService> and calls its loader — it does not
write its own loader against the post table.
The FK loader is part of the owner’s service, never the consumer’s.
A resolver returning Post from a notification field uses the auto-emitted
PostsServiceById; the loader is the property of PostsService and any
new feature reaches it through the existing one.
Batches carry the request with them
Section titled “Batches carry the request with them”async-graphql runs each batch on a task of its own, which starts with
nothing ambient. The spawner captures what the request carries the moment a
field asks the loader — its trace, the caller’s ability, every value it
carries — and runs the batch under it. You bind nothing for this: a batch
reads through Repo filtered by the caller’s ability, and every line it
logs carries the request’s trace_id.
A batch is shared by every field of the request that loads through the loader, so it belongs to the request: it carries the request’s values, never one field’s, and its lines and spans sit in the request’s span, not under the field that asked first. One exception keeps a root field’s rows its own: where a query’s or a mutation’s own guards attached the ability its request did not carry, its answer and its loader parameters read through loaders of the field’s own, whose batches judge their rows under that ability — no other root field’s keys join them. A subscription’s opening reads the request’s, since its operation holds no other root field: a second is refused before either opens (Subscriptions). Its executor is the pool, never the request transaction — a batch runs beside the request, and a write inside a loader would race the commit. So a relation resolved in a mutation’s own response reads the rows as they stood before the mutation’s transaction: a row the mutation wrote is not there yet. Loaders are reads.
A batch that panics is contained on its task and said once, at error on
nest_rs::graphql, with the panic’s message; the fields waiting on it fail
with it, as a field that panics itself does.
Going further
Section titled “Going further”- Database — the slice the loader hangs off.
- Repo and executor — the executor a
Repoquery runs on, whatRepo::scopedfilters. - GraphQL —
#[resolver],#[field_resolver], the schema-discovery seam. - Security — the ability that drives
Repo::scoped’s row-level filter.