Skip to content

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.

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:

from the macro expansion
#[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.

#[expose(complexity = …)] overrides the auto-emitted factor:

crates/features/src/orgs/entity.rs
#[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 reserved child_complexity variable, plus the field’s own arguments. An auto-emitted HasMany takes first: Option<u64> and after: Option<String>, so first.unwrap_or(20).clamp(1, 100) as usize * child_complexity is available there — keep the clamp, since first arrives as any u64 and 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:

cost an expensive computed scalar
#[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,
}

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 = …)]:

the entity, then the resolver
// 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>> { … }
}
  • Query limits — the depth and complexity ceilings every score is held to, and how to calibrate them.
  • Relations — the auto-emitted HasMany connection whose page the factor multiplies.
  • Field resolvers — the hand-written field a #[graphql(complexity = …)] costs.