How does Apollo Federation v2 resolve distributed entities across multiple subgraphs using @key and __resolveReference?

In Apollo Federation v2, an entity is an object type whose fields can be defined and resolved across multiple distinct subgraphs. The originating subgraph defines the entity with a primary key directive, e.g., type Product @key(fields: "id"). Another subgraph (such as Reviews or Inventory) extends that entity by re-declaring the type with the exact same @key(fields: "id") and adding its own domain-specific fields (e.g. reviews: [Review]). When a client query requests fields from both subgraphs, the Federation Router queries the base Product first, extracts the "id" key, and sends an internal federated entity representation query (_entities(representations: [{ __typename: "Product", id: "123" }])) to the secondary subgraph. The secondary subgraph implements a __resolveReference resolver that receives the representation representation and fetches the corresponding local records.

What is the architectural purpose of @provides and @requires in federated query planning?

@provides allows a subgraph to optimistically resolve fields on an entity that it does not formally own, eliminating redundant downstream network roundtrips. For example, if the Reviews subgraph stores a cached author username on review records, it can annotate author: User @provides(fields: "username"). When a query asks for review author usernames, the Router satisfies the username directly from Reviews without querying the Users subgraph. Conversely, @requires is applied to a field that needs data from another subgraph to compute its own value. For instance, in an Inventory subgraph, a field shippingCost: Float @requires(fields: "weight dimensions { length width }") tells the Router that it must first fetch weight and dimensions from the Products subgraph before invoking the shippingCost resolver in Inventory.

Why did the GraphQL ecosystem transition from Node.js Apollo Gateway to Apollo Router (Rust) and WunderGraph Cosmo (Go)?

The legacy Apollo Gateway ran on Node.js as an Express or Fastify middleware. Because Node.js is single-threaded and relies on V8 garbage collection, high-concurrency production workloads (10,000+ RPS) suffered from heavy GC pauses, high memory consumption (500 MB - 2 GB per pod), and significant request serialization latency. Modern federation gateways like Apollo Router (written in pure Rust) and WunderGraph Cosmo (written in Go) compile to native binary executables that bypass V8 completely. Apollo Router executes query planning, subgraph batching, and HTTP/2 multiplexing across multi-threaded asynchronous runtimes (Tokio), achieving over 50,000 RPS per instance with sub-millisecond overhead and less than 50 MB of memory.

How does the Federation Router prevent the N+1 problem across distributed subgraph HTTP calls?

If a client queries a list of 50 products and requests the inventory for each, a naive router implementation would execute 50 individual HTTP requests to the Inventory subgraph. Modern federation routers solve this by batching entity representations within each query execution stage. The query planner aggregates all 50 product IDs into a single federated batch request: query { _entities(representations: [{__typename: "Product", id: "1"}, {__typename: "Product", id: "2"}, ...]) { ... on Product { inStock inventoryCount } } }. This collapses 50 network calls into 1 single HTTP POST request to the Inventory subgraph, preserving database efficiency and eliminating network latency waterfalls.

What is the difference between @shareable and @override in Apollo Federation v2?

@shareable indicates that a field can be resolved by multiple subgraphs simultaneously without causing a composition error. In Federation v2, fields are unshareable by default (owned strictly by one subgraph) to enforce domain boundaries. If two subgraphs both compute a field (such as a calculated tax rate or formatted label), adding @shareable to both definitions permits composition. In contrast, @override(from: "subgraph-a") is used for progressive zero-downtime microservice migrations. It allows a new subgraph (subgraph-b) to take over resolution of an existing field from subgraph-a. Once the Router loads the new supergraph schema, it routes all traffic for that field to subgraph-b without requiring coordinated changes or downtime in subgraph-a.

Verified Specification | Standardized Formulas | Instant Precision

Secure & Private (Zero Data Retention) Free Access • No Sign-Up

Apollo Federation v2.7 Cosmo Supergraph Standard Query Planner AST Rust Router Benchmark

GraphQL Federation, Supergraph & Subgraph Architecture Studio

Architect enterprise federated GraphQL platforms: model cross-subgraph entity resolution with @key, @provides, and @requires, visualize parallel query execution plans, benchmark Apollo Router (Rust) vs Node Gateway, and synthesize production schemas.

4 Subgraphs

Active Supergraph Schema

2 Stages

Planner Execution Depth

52,000 RPS

Apollo Router (Rust) Max RPS

14.8x

Throughput vs Node Gateway

Federated Query Planner & Subgraph Execution Tree

Inspect how the Federation Router analyzes a client query, breaks it down into distinct sub-queries, and orchestrates parallel vs sequential network fetches across microservices.

Sample Client Query Selection

Client Query Preview

Router Execution Plan (Stages)

Entity Directives Architecture (@key, @provides, @requires, @shareable)

Interactive directive matrix demonstrating how Federation v2 establishes distributed entity boundaries and enables inter-service dependency resolution.

@key(fields: "id")

Defines the entity primary identifier. Subgraphs that reference or extend this entity must implement a __resolveReference handler to fetch local data by key.

@provides(fields: "username")

Allows the local subgraph to satisfy fields that it does not own, preventing the Router from executing an extra network hop to the authoring service.

@requires(fields: "weight")

Declares that a field resolver requires data from another subgraph before executing (e.g. shipping cost calculation requires package weight from Products).

@override(from: "catalog")

Seamlessly migrates a field from an older microservice to a new service with zero downtime, instructing the Router to redirect all field queries to the new subgraph.

Interactive Directive Playground

Target Architecture Scenario

DataLoader Batching & In-Memory Entity Cache Sizer

Model how the Router and Subgraph DataLoaders aggregate N-requests during event-loop ticks to prevent database exhaustion and size cache memory footprints.

Concurrent Requests (RPS): 2,500 req/s

Entities Requested per Query: 25 entities

Average Entity Payload Size: 1.2 KB

Batching & Network Reduction

62,500 / s

Naive N+1 Subgraph HTTP Calls

2,500 / s

Batched _entities Calls (96% drop)

• Router Concurrency In-Flight Memory: 75.0 MB

• Network Latency Savings: ~24 round-trips avoided per query

Gateway Performance Benchmark (Apollo Router Rust vs Cosmo Go vs Node)

Compare latency, throughput, and CPU/memory footprint across the three major federation router runtime implementations.

Runtime / Architecture	Apollo Router (Rust)	WunderGraph Cosmo (Go)	Legacy Apollo Gateway (Node.js)
Underlying Engine	Rust (Tokio Async Runtime)	Go (Fiber / Netpoll)	JavaScript / V8 Engine
Peak Throughput (Single Instance)	~52,000 RPS	~46,000 RPS	~3,500 RPS (14.8x slower)
p99 Router Added Latency	< 0.8 ms	< 1.4 ms	~8.5 ms (GC pauses)
Baseline RAM per Pod	~45 MB	~85 MB	~550 MB (V8 Heap)
Garbage Collection Overhead	Zero (RAII Memory Management)	Low (Go Tracing GC)	High (V8 Stop-the-world GC)
Plugin / Extension Model	Rhai Scripting + Native Rust	Go Plugins + TypeScript Workers	Node.js Express / Fastify Plugins

Production Supergraph & Subgraph Schema Synthesizer

Generate ready-to-compose Apollo Federation v2 schema files and production Apollo Router configuration files.

GraphQL Federation, Supergraph & Subgraph Architecture Studio

Federated Query Planner & Subgraph Execution Tree

Entity Directives Architecture (@key, @provides, @requires, @shareable)

Interactive Directive Playground

DataLoader Batching & In-Memory Entity Cache Sizer

Gateway Performance Benchmark (Apollo Router Rust vs Cosmo Go vs Node)

Production Supergraph & Subgraph Schema Synthesizer

🔍 Companion Workbenches & Verification Tools

Cryptographic Hash Generator (SHA-256, SHA-512, SHA-384, SHA-1, MD5)

B-Tree, B+ Tree & Storage Engine Internals Studio

Distributed Consensus, Raft & Paxos State Machine Studio

SemVer Semantic Version Calculator & Dependency Range Evaluator

Why Smart Users Are Switching to This Free Toolkit

The Browser Feature Most People Never Use

Stop Paying for Software You Can Get Free

File Conversion Tricks That Save Hours Every Week

This Free Tool Replaced 5 Paid Apps for Our Team

What Your Browser Can Do Without Any Extensions