GraphQL Federation

The supergraph router (or gateway) is the central component that receives client queries, intelligently routes them to the correct subgraph services, and composes the results. It uses a supergraph schema, a composed schema generated from all subgraph schemas, to understand the complete data graph and execute query planning. This architecture allows clients to query data from multiple services as if they were a single source, abstracting the underlying microservices complexity.

A subgraph is an independently deployable GraphQL service that owns a specific domain of the overall data graph (e.g., a Product service, a User service, or a Knowledge Graph service). Each subgraph:

• Defines its own GraphQL schema with types and fields it is responsible for.
• Implements resolvers to fetch data from its backend (e.g., a database, REST API, or triplestore).
• Can be developed, deployed, and scaled by separate teams. In a federated architecture, a subgraph can extend types defined by other subgraphs, enabling a unified type system across services.

The entity is the core abstraction of federation. An entity is a GraphQL object type that can be resolved across multiple subgraphs. The @key directive defines the primary key fields (e.g., id, sku) that uniquely identify an instance of that entity. For example:

graphqlCopy
type Product @key(fields: "id") {
  id: ID!
  name: String!
  description: String
}

This allows the router to fetch a Product by its id from the subgraph that defines it, and then reference that entity to fetch extended fields (like inventory or reviews) from other subgraphs.

When a client query arrives, the router performs query planning. It:

1. Parses the query against the supergraph schema.
2. Builds a query plan that breaks the query into smaller operations (query fragments) that can be executed by individual subgraphs.
3. Sequences these operations, often requiring multiple round trips where the result from one subgraph provides keys to fetch related data from another (entity reference resolution).
4. Composes the results from all subgraphs into a single response for the client. This process is transparent to the client, which sees only the final, unified result.

Schema composition is the automated process of merging all subgraph schemas into a single, validated supergraph schema. This is typically managed by a schema registry service. The process involves:

• Subgraphs publishing their schemas (with federation directives) to the registry.
• The registry composing them, checking for type conflicts and consistency.
• The router fetching the latest composed supergraph schema to enable accurate query planning. This centralized schema management ensures a contract between all services and the gateway, enabling safe, incremental evolution of the federated graph.

In an enterprise context, a Knowledge Graph backend can be integrated as a specialized subgraph. This subgraph:

• Exposes entity-centric queries (e.g., finding all suppliers for a product) and graph pattern queries (e.g., traversing relationships).
• Uses its resolvers to execute semantic queries (e.g., SPARQL or Cypher) against a triplestore or property graph database.
• Can extend core business entities (like Product or Customer) with rich, inferred relationships and attributes derived from the knowledge graph. This pattern provides a unified query interface, allowing clients to seamlessly combine operational data from microservices with contextual, relationship-rich data from the knowledge graph.

Federation creates a single, cohesive GraphQL schema from multiple independent backend services (subgraphs). This allows frontend clients to query data across product catalogs, user profiles, and order systems in one request, eliminating the need for complex client-side aggregation and reducing network chatter.

• Declarative Composition: Each team owns a subgraph defining its domain (e.g., InventoryService, PaymentService).
• Schema Stitching: A federated gateway (e.g., Apollo Router) automatically merges these into a unified supergraph.
• Example: A dashboard fetches a user's recent orders, the items in each order, and real-time inventory status for those items via one query to the federated endpoint.

Federation acts as an adapter layer for gradually modernizing monolithic applications. Legacy REST APIs or SOAP services can be wrapped as individual subgraphs, allowing them to participate in the modern GraphQL ecosystem without a full rewrite.

• Incremental Migration: New microservices are built as native subgraphs while legacy systems are wrapped, enabling a phased transition.
• Data Transformation: The subgraph for a legacy system handles the translation between its proprietary format and the federated graph's types.
• Use Case: Exposing data from a mainframe-based CRM alongside a modern SaaS marketing automation platform through a single GraphQL interface.

A central enterprise knowledge graph can be exposed as a federated subgraph, providing deterministic, entity-centric data to other services. This turns the knowledge graph into a reusable semantic layer for facts, relationships, and business logic.

• Entity Resolution & Context: Other services can extend core entities (e.g., a Customer or Product defined in the KG) with their own domain-specific fields.
• Cross-Referencing: A Product subgraph can reference authoritative data (supplier, compliance info) from the knowledge graph subgraph.
• Example: An e-commerce service federates with a knowledge graph subgraph to enrich product listings with unified taxonomy categories and sustainability attributes.

Federation provides a technical implementation pattern that maps directly to bounded contexts in Domain-Driven Design (DDD). Each subgraph represents a clear business domain, enforcing separation of concerns and autonomy for development teams.

• Ownership Boundaries: The team owning the Shipping domain has full control over its subgraph's schema, resolvers, and database.
• Shared Kernel: Common entities (like User) can be partially defined by one subgraph and extended by others, avoiding a single, monolithic definition.
• Benefit: Prevents the "big ball of mud" schema and aligns software architecture with business organization.

A federated gateway performs query planning to decompose a single client query into efficient sub-queries, which are executed in parallel against the relevant subgraphs. This optimizes data fetching and minimizes latency.

• Intelligent Routing: The gateway analyzes the query, determines which subgraphs hold the required fields, and sends optimized requests.
• Batching & Caching: Requests to the same subgraph can be batched, and subgraph-level caching strategies can be implemented.
• Example: A query for a user's name (from UserService) and their last invoice amount (from BillingService) is split and executed concurrently, not sequentially.

Federation supports a decentralized but governed approach to schema management. Teams can evolve their subgraphs independently while a central contract (the supergraph) provides coordination and prevents breaking changes.

• Schema Checks: CI/CD pipelines can run composition checks to validate that a subgraph update integrates safely with the supergraph.
• Contract First: The federated graph's unified schema acts as a published contract for all clients.
• Tooling: Platforms like Apollo Studio provide visibility into schema changes, query usage, and performance across all federated services.

An alternative, lower-level pattern for merging multiple GraphQL schemas into a single unified API. Unlike Federation's declarative entity-based model, schema stitching involves programmatically merging type definitions and delegating resolvers. It offers more granular control but requires manual resolution of conflicts and a deeper understanding of the underlying GraphQL execution engine. Federation is generally preferred for its stronger conventions and tooling in large-scale microservices.

The composed, unified GraphQL schema and its associated routing logic that represents the entire federated API. It is the product of combining all subgraph schemas. The supergraph schema is consumed by the gateway/router, which uses it to validate incoming client queries and create an execution plan. Managing the supergraph's lifecycle—composition, validation, and deployment—is a central concern, often handled by tools like Apollo Rover or a schema registry.

An independent GraphQL service that defines a portion of the overall federated graph. Each subgraph:

• Manages a distinct domain or data source (e.g., a Users service, a Products service, a Knowledge Graph backend).
• Uses the Federation spec to declare entities it can resolve using the @key directive.
• Can extend types defined by other subgraphs.
• Runs its own business logic and connects to its own databases. The federation gateway calls these services to resolve parts of a client's query.

The process performed by the federation gateway/router to decompose a single client GraphQL query into a series of sub-queries (or query shapes) destined for specific subgraphs. The planner must:

• Respect data dependencies and the @requires directive.
• Minimize the number of subgraph calls (e.g., via batching).
• Handle error boundaries for partial failures.
• Optimize the order of execution. This is a complex optimization problem critical to the performance of a federated architecture.

The runtime component that sits between clients and the federated subgraphs. Its primary responsibilities are:

• Schema Composition: Building the supergraph from subgraph schemas.
• Query Planning & Execution: Parsing client queries, creating an execution plan, calling subgraphs, and stitching results.
• Caching: Implementing query and response caching to improve performance.
• Observability: Collecting metrics and traces for all graph operations. Examples include the Apollo Router, Netflix's DGS Federation Gateway, and Wundergraph.