Skip to content

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 ← dataloader

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>) per belongs_to on 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;
  • PkLoadable and RelatedTo<Parent, Via> impls so the inverse side (the parent’s has_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.
crates/features/src/posts/entities/post.rs (from the demo, abridged)
#[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).

#[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:

crates/features/src/posts/service.rs
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 empty HashMap — that turns a failure into a silent miss, the worst kind.
  • Repo::scoped(Read), not raw Posts::find(). The ability filter applies, so a batch on behalf of one caller never returns another tenant’s rows.

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:

crates/features/src/authors/graphql/resolver.rs
#[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:

crates/features/src/posts/graphql/resolver.rs
#[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:

Terminal window
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.

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.

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.

  • Database — the slice the loader hangs off.
  • Repo and executor — the executor a Repo query runs on, what Repo::scoped filters.
  • GraphQL — #[resolver], #[field_resolver], the schema-discovery seam.
  • Security — the ability that drives Repo::scoped’s row-level filter.