Using @external and @requires for Field Resolution

In distributed GraphQL architectures, resolving fields that span multiple services requires precise directive orchestration. Mastering Subgraph Implementation & Entity Resolution is foundational for teams scaling federated graphs. When a subgraph needs data owned by another service to compute a field, the @external and @requires directives establish explicit dependency contracts without duplicating business logic. This guide details schema annotation patterns, resolver wiring, and query planner implications for production-grade deployments.

Directive Semantics & Schema Contracts

The @external directive declares that a field originates in another subgraph but is required locally for computation, validation, or entity resolution. Conversely, @requires(fields: "...") explicitly lists the external dependencies a resolver must receive before execution begins. This contract prevents over-fetching and ensures the gateway routes queries along optimal execution paths. Pairing these directives with Implementing Entity Resolvers with @key Directives guarantees type-safe entity stitching across service boundaries.

The schema contract must explicitly list required fields in the SDL, and the resolver signature must accept them via the parent object. Federation v2 enforces strict validation during composition: any field referenced in @requires that is not owned by the current subgraph must be annotated with @external (or reside on an extend type where the field is implicitly external).

Implementation Checklist

  • Declare @external on every field definition in the dependent subgraph that originates elsewhere.
  • Apply @requires(fields: "field1 field2") to the computed field, using exact SDL field names.
  • Validate that the gateway’s query planner recognizes the dependency chain during rover subgraph check.

Configuration Patterns & Resolver Workflows

Configuration involves annotating the SDL in the dependent subgraph and wiring the resolver to receive the required fields via the parent object. The Apollo Router or Gateway automatically batches and fetches the declared external fields using the entity reference resolver pipeline. When dealing with complex types, binary payloads, or non-standard serialization formats, integrating Custom Scalars in Federated GraphQL Schemas alongside @requires guarantees accurate data transfer during cross-service resolution.

Resolver implementations must strictly avoid re-fetching data that the gateway has already injected into the execution context. Redundant database calls inside a @requires resolver negate the benefits of federation and introduce unpredictable latency.

SDL Definition 

extend type Review @key(fields: "id") {
 id: ID! @external
 author: User @external
 product: Product @external
 score: Int! @external
 isHighlyRated: Boolean @requires(fields: "score")
}

Resolver Implementation (Node.js/Apollo) 

const resolvers = {
 Review: {
 isHighlyRated: (parent, _args, context, info) => {
 // The gateway guarantees parent.score exists due to @requires
 if (typeof parent.score !== 'number') {
 throw new Error('Missing required external field: score');
 }
 return parent.score >= 4;
 }
 }
};

Performance Trade-offs & Execution Planning

While @requires simplifies dependency declaration, it introduces additional network hops and resolver latency. The query planner must fetch external fields before executing the local resolver, which can impact tail latency under high concurrency. Optimizing these paths often involves denormalizing frequently accessed fields, caching at the entity level, or refactoring to push computation closer to the data owner. For advanced computed field strategies, developers should review How to implement @requires for computed fields to balance computational overhead with data freshness.

Monitoring query execution traces is critical to identifying N+1 patterns introduced by poorly scoped requirements. Sequential external fetches compound latency linearly, whereas parallelized fetches leverage the gateway’s batching capabilities.

Optimization & Debugging Workflow

  1. Audit Query Plans: Use Apollo Studio or rover dev --trace to inspect the execution tree. Look for sequential Fetch nodes that could be parallelized.
  2. Scope Requirements Minimally: Only list fields in @requires that are strictly necessary. Extraneous fields increase payload size and memory pressure on the router.
  3. Implement Field-Level Caching: Apply @cacheControl directives or HTTP cache headers to stable external dependencies. Ensure cache invalidation accounts for upstream mutations.
  4. Use @provides Sparingly: When a subgraph can compute a field more efficiently than the owner, use @provides to override resolution paths, but document the trade-off clearly to avoid schema drift.

Common Pitfalls & Troubleshooting

Symptom Root Cause Resolution
Schema composition failed: Field X is not marked as @external Omitting @external on a field referenced by @requires Add @external to the field definition in the dependent subgraph’s SDL.
High resolver latency / Gateway timeout Requesting more fields in @requires than necessary Trim the fields string to only include strictly required data.
TypeError: Cannot read properties of undefined (reading 'score') Attempting to resolve @requires fields inside the resolver Rely on gateway injection. Remove internal fetch logic and validate parent structure.
Field type mismatch during composition Divergent field types between owning and requiring subgraphs Align SDL types exactly. Use shared scalar definitions or federation type extensions.
Hidden sequential fetches in production traces N+1 resolution chains from unbatched external dependencies Implement DataLoader or equivalent batching utilities in the entity reference resolver.

FAQ

Can I use @requires without @external?

No. The directive explicitly depends on @external to establish a valid cross-subgraph contract. The gateway will reject the schema during composition if a required field is not marked as external in the dependent subgraph.

How does the query planner handle @requires dependencies?

The planner identifies the dependency graph, fetches the required external fields in parallel where possible, and injects them into the parent object before executing the local resolver. Execution order is strictly enforced to maintain data consistency and prevent race conditions.

Does @requires impact caching strategies?

Yes. Since the computed field depends on external data, cache invalidation must account for changes in the required fields. Implementing field-level cache tags or propagating the owning subgraph’s cache headers is recommended to prevent stale computed values.