Federation

Query Execution

Query Planning

Router analyzes incoming queries and creates an execution plan:

1. Parse Query: break down the query into field selections
2. Identify Entities: determine which entities need to be resolved
3. Plan Execution: create optimal execution order
4. Execute Subqueries: send requests to appropriate subgraphs
5. Compose Response: merge responses into final result

Query Execution

Based on the query execution plan generated by the router, the query could be executed sequentially or in parallel across multiple subgraphs. The router orchestrates the execution, ensuring that dependencies are resolved correctly.

Schema Composition

Aspect	Rule	Details	Example
Type Merging	Types (objects, interfaces, enums, scalars, unions, inputs) with the same name across different subgraphs are merged into a single, unified type in the Supergraph schema.	Fields: fields within merged object types are additive. If multiple subgraphs define the same type, all unique fields from those types are combined. Conflict Resolution: if 2 subgraphs define fields with the same name on a merged type but with different types, this results in a composition error. The field type must be consistent across all subgraphs that define it. Directives: directives applied to merged types or their fields are also merged. Conflicts arise if the same directive is applied with conflicting arguments.	# if Subgraph A defines type Product { id: ID! name: String! } # and Subgraph B defines type Product { id: ID! price: Float! } # the merged Supergraph type will be type Product { id: ID! name: String! price: Float! }
Field Uniqueness and Ownership	Each field on an object type must be "owned" by exactly one subgraph, unless it's a @shareable field.	Single Source of Truth: this rule ensures a single source of truth for a field's resolution logic. If multiple subgraphs define the same field on a type, only one subgraph is designated as the "owner" responsible for resolving that field. @shareable Directive: fields marked with the @shareable directive can be defined and owned by multiple subgraphs. This is typically used for fields that are stable and can be resolved identically by different services (e.g., ID fields, static data). Composition Errors: if a non-shareable field is defined in multiple subgraphs without explicit ownership delegation (e.g., through @external and @provides or @requires), it will lead to a composition error.	type Product @key(fields: "id") { id: ID! # provided by one subgraph name: String! @external # provided by another subgraph # using `@external` on the consuming subgraph price: Float! }
Entity Extensions	Entities (types marked with @key) can be extended across multiple subgraphs. This allows different services to contribute fields to the same entity.	@key Directive: defines the primary key(s) for an entity, allowing the Supergraph to uniquely identify instances of that type. @extends Directive: used in a subgraph to indicate that a type is an extension of an entity defined in another subgraph. The subgraph adding the extension does not "own" the base entity, but rather contributes additional fields to it. @external Directive: marks a field as being defined in another subgraph. This is used in conjunction with @extends to declare fields that are part of the entity's key or are required from another subgraph to resolve local fields. @requires Directive: specifies that a field's resolution depends on the values of other external fields from the same entity. @provides Directive: used to declare that a subgraph can resolve a field from a federated entity even if it's not the primary owner, typically for optimizing query plans.	# Subgraph A defines User type User @key(fields: "id") { id: ID! name: String! } # Subgraph B extends User extend type User @key(fields: "id") { id: ID! @external reviews: [Review!]! @requires(fields: "id") }
Directive Validation	Federation-specific directives (@key, @extends, @external, @requires, @provides, @shareable, @inaccessible, @tag, @override, etc.) are rigorously validated during composition to ensure correct usage and prevent inconsistencies.	Placement: directives must be applied to the correct schema locations (e.g., @key on object types, @external on fields). Arguments: directive arguments must be valid and adhere to their definitions (e.g., fields argument of @key must refer to existing fields). Semantic Checks: the composer performs semantic checks, such as ensuring that @requires fields are also marked @external and that key fields are always available for resolution. Composition Errors: invalid directive usage or conflicts in directive application will result in composition errors, preventing the Supergraph schema from being built.
Root Operation Type Merging (Query, Mutation, Subscription)	Root operation types (Query, Mutation, Subscription) are special: they are always merged, and their fields are additive across all subgraphs.	Additive Fields: if multiple subgraphs define fields on Query, Mutation, or Subscription, all unique fields are combined into a single root type in the Supergraph. No Ownership Conflict: unlike regular object fields, fields on root operation types do not have ownership conflicts, as each subgraph provides its own set of root fields.	# Subgraph A has type Query { users: [User!]! } # Subgraph B has type Query { products: [Product!]! } # Supergraph Query will have both type Query { users: [User!]! products: [Product!]! }
Interface and Union Type Compatibility	When an interface or union type is merged or extended, all implementing types or member types must be resolvable and consistent across subgraphs.	Implementations: if an interface is implemented by a type that is also part of the Supergraph, that type must adhere to the interface contract. Union Members: all member types of a union must be resolvable entity types within the Supergraph. Composition Errors: inconsistencies in type implementations or unresolved union members will lead to composition errors.
Enum and Scalar Type Consistency	Enum and scalar types with the same name must have identical definitions (values for enums, and underlying serialization/deserialization logic for scalars) across all subgraphs.	Exact Match: for enums, the set of values must be an exact match. Any discrepancy in values or their order will cause a composition error. Standard Scalars: standard GraphQL scalars (ID, String, Int, Float, Boolean) are implicitly consistent. Custom Scalars: custom scalars require careful coordination to ensure their serialization and deserialization logic is consistent across all subgraphs that define or use them.	# Subgraph A defines enum Status { ACTIVE INACTIVE } # Subgraph B defines enum Status { ACTIVE PENDING } # this will cause a composition error # due to inconsistent enum values
Schema Directives and Metadata	Directives defined at the schema level and other schema-level metadata (like @link) are also composed, with rules for merging and conflict resolution.	@link Directive: used to declare the usage of external schema specifications (like @federation from https://specs.apollo.dev/federation/v2.0). Conflicts can arise if linked specifications clash. Additive Behavior: generally, schema-level directives and extensions (e.g., extend schema) are additive, but conflicts in arguments or contradictory definitions can lead to composition errors.

Query Optimization

• Query Planning: optimize execution order
• Parallel Execution: execute independent subqueries in parallel
• Query Deduplication: cache and reuse identical queries
• Field Selection: only fetch requested fields
• Minimize Operations Spanning Multiple Subgraphs: design schemas to keep most queries within single subgraphs when possible, as cross-subgraph operations add query plan complexity and increase latency
• Overusing of @shareable and Shared Types: the @shareable directive enables multiple subgraphs to resolve the same entities or fields, offering query planner flexibility. However, overusing @shareable can exponentially increase potential query paths, which degrades performance. Use it primarily where consistency between subgraphs is guaranteed and necessary
• Schema Evolution and Compatibility: changes to fields and directives like @requires can impact current query plans and introduce latency. Manage schema migrations carefully, deploying them atomically to avoid disruptions or performance regressions
• Query Caching: use caching mechanisms to store query for frequently static executed queries APQ (Automatic Persisted Queries)
• Query Complexity Analysis: analyze query complexity to prevent overly complex queries that can degrade performance. Implement limits on query depth and breadth
• Database Indexes: ensure that database queries are optimized with appropriate indexes to speed up data retrieval

Subgraph Caching

Aspect	DataLoader	Redis
Scope	Per-request, in-memory	Cross-request, distributed
Pros	N+1 Query Problem: use DataLoader within resolvers when your subgraph needs to fetch related data that causes multiple roundtrips to backend services or databases due to GraphQL's nested query patterns Optimizing Per-Request Data Fetching: to cache and reuse fetched entities within a single request context Field-Level Data Fetching Efficiency: use when different fields in your schema (resolved separately) require data from the same resource (e.g., batched loading of products, categories, or user profiles), ensuring single batched reads	Cross-Service (Distributed) Caching: cache entities or frequently-requested subgraph query results across all instances and requests in clustered or horizontally scaled environments Pub/Sub for Subscriptions and Realtime Updates: when your subgraph needs to support real-time updates (GraphQL subscriptions) at scale, distributing events among multiple subgraph or server instances so that all clients receive relevant updates, regardless of the processing node Message Brokering Across Microservices: leverage for message passing or notification delivery between distinct microservices or subgraph instances, ensuring that each microservice can communicate asynchronously and efficiently, especially in event-driven architectures
Use Case	Batching and caching per-request data-fetch operations	Cross-service caching, Pub/Sub for subscriptions, message brokering

Common Types

Field	Description
scalar ID	Scalar type used to represent a unique identifier for a resource
enum CountryCode	2 letter ISO 3166 code representing a country
enum LanguageCode	2 letter ISO 639 code representing a language
input PageInput	Input type for pagination parameters
type PageInfo	Contains information about pagination, such as total count and whether there are more pages available

Entity Relationships

Aspect	Definition	Example
Entity Definition and Keys	Entities are the core building blocks of federation. They represent business objects that can span multiple subgraphs	# Primary entity definition (Users subgraph) type User @key(fields: "id") { id: ID! username: String! email: String! createdAt: String! } # Entity with multiple keys (Products subgraph) type Product @key(fields: "id") @key(fields: "sku") { id: ID! sku: String! name: String! price: Float! }
Entity Extensions	Other subgraphs can extend entities to add domain-specific fields	# Orders subgraph extends User extend type User @key(fields: "id") { id: ID! @external orders: [Order!]! totalSpent: Float! loyaltyLevel: LoyaltyLevel! } # Reviews subgraph extends Product extend type Product @key(fields: "id") { id: ID! @external reviews: [Review!]! averageRating: Float! reviewCount: Int! }
Single Subgraph One-to-One	Within a single subgraph, one entity can directly reference another entity	# User Profile (1:1 relationship) type User @key(fields: "id") { id: ID! username: String! profile: UserProfile } type UserProfile { id: ID! user: User! firstName: String lastName: String avatar: String bio: String }
Cross-Subgraph One-to-One	One entity in one subgraph can reference an entity in another subgraph using the @external directive	# User subgraph type User @key(fields: "id") { id: ID! username: String! email: String! } # Profile subgraph extends User extend type User @key(fields: "id") { id: ID! @external profile: UserProfile! } type UserProfile { id: ID! firstName: String lastName: String avatar: String }
Single Subgraph One-to-Many	Within a single subgraph, one entity can have multiple related entities	# User has many posts type User @key(fields: "id") { id: ID! username: String! posts: [Post!]! } type Post @key(fields: "id") { id: ID! title: String! content: String! author: User! createdAt: String! }
Paginated One-to-Many	When one entity has many related entities, pagination is often used to efficiently fetch large sets of data	# User has many orders (paginated) extend type User @key(fields: "id") { id: ID! @external orders( first: Int after: String status: OrderStatus dateRange: DateRangeInput ): OrderConnection! } type OrderConnection { edges: [OrderEdge!]! pageInfo: PageInfo! totalCount: Int! } type OrderEdge { node: Order! cursor: String! } type Order @key(fields: "id") { id: ID! user: User! status: OrderStatus! total: Money! createdAt: String! } input DateRangeInput { from: String! to: String! }
Single Subgraph Many-to-Many	Within a single subgraph, one entity can be related to multiple instances of another entity	# Products and Categories type Product @key(fields: "id") { id: ID! name: String! categories: [Category!]! } type Category @key(fields: "id") { id: ID! name: String! products: [Product!]! }
Many-to-Many with Junction Table	In many-to-many relationships, a junction table is often used to represent the relationship between 2` entities	# Users and Roles with permissions type User @key(fields: "id") { id: ID! username: String! roleAssignments: [UserRoleAssignment!]! roles: [Role!]! } type Role @key(fields: "id") { id: ID! name: String! permissions: [Permission!]! userAssignments: [UserRoleAssignment!]! } type UserRoleAssignment { id: ID! user: User! role: Role! assignedAt: String! assignedBy: User! expiresAt: String } type Permission { id: ID! name: String! resource: String! action: String! }
Cross-Subgraph Entity Extension Pattern	Allows entities to be extended across subgraphs, enabling more flexible and modular architecture	# Users subgraph (primary definition) type User @key(fields: "id") { id: ID! username: String! email: String! } # Orders subgraph (extends User) extend type User @key(fields: "id") { id: ID! @external orders: [Order!]! totalOrderValue: Float! } # Reviews subgraph (extends User) extend type User @key(fields: "id") { id: ID! @external reviews: [Review!]! reviewCount: Int! averageRating: Float! } # Wishlist subgraph (extends User) extend type User @key(fields: "id") { id: ID! @external wishlist: Wishlist! }
Cross-Subgraph Reference Resolution	Enables one subgraph to reference entities from another subgraph using a representation (primary key + typename). The _resolveReference resolver in each subgraph handles this, allowing distributed services to compose a unified API	Entity Definition and Key in the Products Subgraph # products subgraph (schema) type Product @key(fields: "upc") { upc: String! name: String price: Int } Reference Resolver in the Products Subgraph Product: { // this resolver is called when an entity of type Product // is referenced by another subgraph // given only an identifying key (like "upc") __resolveReference(reference: ProductReference) { // Find product by upc return fetchProductByUPC(reference.upc); } } Representing the Reference in the Reviews Subgraph // when the Reviews subgraph needs to provide a Product // (for example, for a Review.product field) // it must issue a representation // this tells the gateway and the entity resolver // that the referenced entity is a Product identified // by its upc Review: { product(review: Review) { return { __typename: "Product", upc: review.upc }; } } End-to-End Query # Router composes these subgraphs, allowing a client to run query { reviews { product { name price } } }
Required Fields Pattern	When an entity is extended across subgraphs, some fields may be required for resolution. The @requires directive specifies which fields must be available from the base entity to resolve the extended fields	# Analytics subgraph extend type User @key(fields: "id") { id: ID! @external username: String! @external email: String! @external # Field that requires external data displayName: String! @requires(fields: "username") emailDomain: String! @requires(fields: "email") userMetrics: UserMetrics! @requires(fields: "username email") } type UserMetrics { username: String! totalLogins: Int! lastLoginAt: String emailDomain: String! }
Interface-Based Polymorphism	Interfaces allow different subgraphs to define types that share a common contract, enabling polymorphic relationships	# Content management system interface Content { id: ID! title: String! author: User! createdAt: String! updatedAt: String! } type Article implements Content @key(fields: "id") { id: ID! title: String! author: User! createdAt: String! updatedAt: String! # Article-specific fields body: String! summary: String! tags: [Tag!]! } type Video implements Content @key(fields: "id") { id: ID! title: String! author: User! createdAt: String! updatedAt: String! # Video-specific fields duration: Int! videoUrl: String! thumbnail: String! } # User can create different types of content extend type User @key(fields: "id") { id: ID! @external content: [Content!]! }
Union-Based Polymorphism	Unions allow a field to return different types, enabling flexible relationships where the type is not known until runtime	# Search results can be different types union SearchResult = Product | Article | User | Category type SearchResponse { query: String! total: Int! results: [SearchResult!]! } type Query { search(query: String!, types: [SearchType!]): SearchResponse! } enum SearchType { PRODUCT ARTICLE USER CATEGORY }
Conditional Access Control	Allows for fine-grained authorization based on user roles and permissions	directive @hasRole(role: String!) on FIELD_DEFINITION type Query { me: User! @hasRole(role: "USER") adminPanel: Admin! @hasRole(role: "ADMIN") }
Dynamic Relationships	Relationships that depend on the current user context or other runtime conditions	# Recommendations based on user behavior extend type Product @key(fields: "id") { id: ID! @external # Dynamic relationship based on current user recommendedProducts: [Product!]! userRecommendationScore: Float }

Best Practices

Aspect	Definition	Example
Entity Keys	Always use stable, immutable identifiers as entity keys	# ✅ Good: Use stable IDs type User @key(fields: "id") { id: ID! username: String! } # ❌ Bad: Avoid mutable fields as keys type User @key(fields: "email") { email: String! username: String! }
Multiple Keys	Provide multiple key options for flexibility	# ✅ Good: Multiple keys for different use cases type Product @key(fields: "id") @key(fields: "sku") { id: ID! sku: String! name: String! }
Design Minimal Entity Representations	Keep entity key fields minimal and avoid large objects	# ✅ Good: Minimal key type User @key(fields: "id") { id: ID! # other fields... } # ❌ Bad: Complex key type User @key(fields: "id profile { firstName lastName }") { id: ID! profile: UserProfile! }
Field's single Source of Truth	Each field should have a clear owner	# Users subgraph owns identity type User @key(fields: "id") { id: ID! username: String! email: String! } # Profile subgraph owns profile data extend type User @key(fields: "id") { id: ID! @external profile: UserProfile! preferences: UserPreferences! } # Orders subgraph owns order data extend type User @key(fields: "id") { id: ID! @external orders: [Order!]! totalSpent: Float! }
Use @shareable Judiciously	Only mark fields as @shareable when they truly can be computed by multiple subgraphs	# ✅ Good: Computed field that both subgraphs can derive type Product @key(fields: "id") { id: ID! name: String! @shareable price: Float! } # ❌ Bad: Database field shared between subgraphs type User @key(fields: "id") { id: ID! email: String! @shareable # This creates data consistency issues }
Schema Evolution: Use Deprecation Before Removal	Always deprecate fields before removing them	type User @key(fields: "id") { id: ID! name: String! @deprecated(reason: "Use firstName and lastName instead") firstName: String! lastName: String! }
Additive Changes Only	Make only additive changes to maintain compatibility	# ✅ Good: Adding new fields type User @key(fields: "id") { id: ID! username: String! email: String! createdAt: String! # New field added lastLoginAt: String # New optional field } # ❌ Bad: Removing or changing existing fields type User @key(fields: "id") { id: ID! # username: String! # Don't remove fields email: Int! # Don't change field types }
Use Relay-Style Connections	Implement consistent pagination	type User @key(fields: "id") { id: ID! orders(input: PageInput): OrderConnection! } input PageInput { first: Int = 10 after: String last: Int before: String } type OrderConnection { edges: [OrderEdge!]! pageInfo: PageInfo! totalCount: Int! } type OrderEdge { node: Order! cursor: String! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String }
Domain-Driven Design Schema	Design your subgraph schemas around business domains, not technical boundaries	# ✅ Good: User domain focuses on identity and profile # Users subgraph type User @key(fields: "id") { id: ID! username: String! email: String! profile: UserProfile! preferences: UserPreferences! } type UserProfile { firstName: String lastName: String avatar: String } type UserPreferences { language: String! timezone: String! notifications: NotificationSettings! }
Single Responsibility Principle	Each subgraph should own a specific set of related types and fields	# ✅ Good: Clear ownership boundaries # Inventory subgraph owns stock-related data extend type Product @key(fields: "id") { id: ID! @external inventory: ProductInventory! availability: AvailabilityStatus! stockLevel: Int! } type ProductInventory { warehouse: String! quantity: Int! reserved: Int! available: Int! } enum AvailabilityStatus { IN_STOCK LOW_STOCK OUT_OF_STOCK DISCONTINUED }

Troubleshooting

Schema Composition Issues

Category	Issue	Solution
Schema Composition	Invalid Federation Directives	# ❌ Problem: Missing @key directive type User { id: ID! username: String! } # ✅ Solution: Add @key directive type User @key(fields: "id") { id: ID! username: String! }
	Inconsistent Entity Definitions	# ❌ Problem: Different key fields across subgraphs # Subgraph A type User @key(fields: "id") { id: ID! } # Subgraph B extend type User @key(fields: "userId") { userId: ID! @external } # ✅ Solution: Use consistent key fields # Both subgraphs type User @key(fields: "id") { id: ID! }
	Missing @external Directive	# ❌ Problem: Extended field not marked as external extend type User @key(fields: "id") { id: ID! # Missing @external orders: [Order!]! } # ✅ Solution: Mark external fields extend type User @key(fields: "id") { id: ID! @external orders: [Order!]! }
	Conflicting Field Definitions	# ❌ Problem: Same field defined differently # Subgraph A type Product @key(fields: "id") { id: ID! name: String! } # Subgraph B type Product @key(fields: "id") { id: ID! name: String # Different nullability } # ✅ Solution: Make fields consistent or use @shareable type Product @key(fields: "id") { id: ID! name: String! @shareable }
Reference Resolution	Missing Reference Resolver	// ❌ Problem: No __resolveReference implementation const resolvers = { User: { // Missing __resolveReference orders: async (user) => { /* ... */ } } }; // ✅ Solution: Implement __resolveReference const resolvers = { User: { __resolveReference: async (user: { id: string }) => { return await UserService.findById(user.id); }, orders: async (user) => { /* ... */ } } };
	Reference Resolver Returns Null	// ❌ Problem: Returns null for valid reference User: { __resolveReference: async (user: { id: string }) => { const userData = await UserService.findById(user.id); return userData; // null if not found } } // ✅ Solution: Handle missing entities appropriately User: { __resolveReference: async (user: { id: string }) => { const userData = await UserService.findById(user.id); if (!userData) { throw new Error(`User with id ${user.id} not found`); } return userData; } }
	Incorrect Key Field Mapping	// ❌ Problem: Wrong key field in reference User: { __resolveReference: async (user: { userId: string }) => { // Entity key is 'id' but resolver expects 'userId' return await UserService.findById(user.userId); } } // ✅ Solution: Use correct key field User: { __resolveReference: async (user: { id: string }) => { return await UserService.findById(user.id); } }