Field complexity
What one field adds to a query's complexity score — the page factor #[expose] writes on a HasMany, and the override any exposed or hand-written field takes.
A query’s complexity is the sum of what each selected field scores, held to the
ceiling Query limits sets. A field scores
async-graphql’s 1 + child_complexity unless it says otherwise; this page is
what a relation says for you, and how any field says it itself.
The auto-emitted HasMany factor
Section titled “The auto-emitted HasMany factor”A HasMany relation resolves a page of children per parent. With
async-graphql’s default scoring, that field costs 1 — no penalty for the
fanout, even though a hundred rows resolve.
#[expose] patches that automatically, using the page the client asked
for rather than a guessed constant:
#[graphql(complexity = "first.unwrap_or(20).clamp(1, 100) as usize * child_complexity")]async fn users(&self, …, first: Option<u64>, after: Option<String>) -> Connection<String, User> { … }So users(first: 5) scores a twentieth of users(first: 100), and three
levels of HasMany (organizations → teams → members) left at the
default page size score 20³. Tune the ceiling, not the formula — the
formula is hard-wired across the framework so the calibration story stays
the same app-wide. The 20 mirrors nest_rs_seaorm::DEFAULT_PAGE_SIZE.
BelongsTo resolvers keep async-graphql’s default 1 + child_complexity — they load at most one parent row, and an ability
denial drops that to zero, so no fanout penalty is needed. That means
HasMany and BelongsTo use asymmetric base scoring by default
(multiplicative vs additive); the asymmetry is the point.
Override on the field
Section titled “Override on the field”#[expose(complexity = …)] overrides the auto-emitted factor:
#[expose(name = "Org", service = …, graphql)]#[sea_orm::model]pub struct Model { #[expose] pub id: Uuid, #[expose] pub name: String,
#[sea_orm(has_many)] #[expose(complexity = "20 * child_complexity")] pub users: HasMany<crate::users::Entity>,}Two shapes:
- Literal —
#[expose(complexity = 5)]pins a fixed score. - Expression —
#[expose(complexity = "20 * child_complexity")]uses async-graphql’s expression grammar with the reservedchild_complexityvariable, plus the field’s own arguments. An auto-emittedHasManytakesfirst: Option<u64>andafter: Option<String>, sofirst.unwrap_or(20).clamp(1, 100) as usize * child_complexityis available there — keep the clamp, sincefirstarrives as anyu64and the product can overflow; every other field has no arguments to name, and an unknown name is an unbound identifier that fails the expansion.
The override applies to any exposed field, scalar or relation:
#[expose(name = "Report", service = …, graphql)]pub struct Model { #[expose] pub id: Uuid, /// Aggregates 24h of metric points server-side. #[expose(complexity = 50)] pub rolling_avg: f64,}Argument-aware expressions
Section titled “Argument-aware expressions”An expression that reads a GraphQL argument only resolves when the field
declares that argument. The auto-emitted HasMany declares first
and after, which is why its default formula can be argument-aware at
all. A hand-written #[field_resolver] taking its own arguments does the
same with a regular #[graphql(complexity = …)]:
// No #[expose] => no auto-emission; own it on the resolver.#[sea_orm(has_many)]pub posts: HasMany<crate::posts::Entity>,
// in the resolver file:#[operations]impl UsersResolver { #[field_resolver] #[graphql(complexity = "limit as usize * child_complexity")] async fn recent_posts(&self, parent: &User, limit: u32) -> Result<Vec<Post>> { … }}Going further
Section titled “Going further”- Query limits — the depth and complexity ceilings every score is held to, and how to calibrate them.
- Relations — the auto-emitted
HasManyconnection whose page the factor multiplies. - Field resolvers — the hand-written field a
#[graphql(complexity = …)]costs.