GraphQL Federation

A subgraph is an independently deployable GraphQL service that defines a portion of the overall domain. It exposes its own GraphQL schema and is responsible for resolving the data for the types and fields it owns. Key characteristics include:

• Ownership: A subgraph owns specific types (e.g., a Product subgraph owns the Product type).
• Schema Definition: It uses special federation directives (like @key) to declare how its types can be referenced and extended by other subgraphs.
• Resolver Implementation: Contains the business logic and data-fetching code for its portion of the graph.

The supergraph schema is the unified, composed GraphQL API schema that clients interact with. It is generated by a federation gateway by intelligently merging all subgraph schemas. Its composition involves:

• Schema Stitching: The gateway combines type definitions, merges duplicate types, and connects them via @key references.
• Query Planning: The gateway analyzes incoming client queries and generates an execution plan that determines which subgraphs to call and in what order.
• Single Endpoint: Clients send queries to a single supergraph endpoint, unaware of the underlying service decomposition.

The gateway (or router) is the runtime component that sits between clients and the subgraphs. It is responsible for query execution, routing, and composition. Its core duties are:

• Query Parsing & Validation: Accepts and validates incoming GraphQL operations against the supergraph schema.
• Query Planning: Creates an optimized execution plan, breaking a single client query into multiple sub-queries for different subgraphs.
• Request Routing: Delegates these sub-queries to the correct subgraph services.
• Response Composition: Aggregates the results from all subgraphs and returns a single, unified response to the client. Apollo Router and WunderGraph are common implementations.

Federation directives are custom GraphQL schema directives used within subgraph schemas to provide metadata for composition. They are the declarative language of federation.

• @key: Defines the primary key fields for an entity, enabling other subgraphs to reference it. Example: type Product @key(fields: "id") { id: ID! name: String }
• @extends: Used to indicate that a type is defined in another subgraph but is being extended with new fields in the current subgraph.
• @external: Marks a field as being defined in another subgraph; it's used in conjunction with @requires and @provides.
• @requires: Specifies that a field in this subgraph requires data from another subgraph to resolve.
• @provides: Specifies that a subgraph, while resolving a field, can guarantee to return certain fields defined in another subgraph.

An entity is a GraphQL object type that can be resolved across multiple subgraphs. It is the central concept for sharing and extending types in federation.

• Definition: Any type annotated with the @key directive is an entity.
• Reference Resolution: When a subgraph returns a reference to an entity (e.g., { __typename: "Product", id: "prod_1" }), the gateway uses this representation to fetch the remaining fields from the subgraph that owns that entity.
• Distributed Ownership: Different subgraphs can contribute different fields to the same entity. For example, the Product entity might have id and name from a Catalog subgraph, and inventoryCount from an Inventory subgraph.

A query plan is the internal execution blueprint created by the federation gateway. It is the result of query planning and dictates how a client's single query is decomposed.

• Operation: The gateway parses the client query and matches each field against the supergraph schema to see which subgraph can resolve it.
• Decomposition: The query is split into a series of dependent fetch nodes.
• Optimization: The plan minimizes sequential calls and batches requests where possible.
• Execution: The gateway executes the fetch nodes in order, passing data from one subgraph's response as variables to the next, finally composing the final result. This process is transparent to the client.

The supergraph is the unified, composed GraphQL API schema exposed to clients. It is not manually written but is automatically generated by a federation gateway (like Apollo Router) by merging the schemas from all registered subgraphs. The supergraph intelligently routes incoming queries to the appropriate subgraph services, presenting a single, cohesive API endpoint.

• Composition: The process of merging subgraph schemas and their federation directives into one executable supergraph schema.
• Gateway/Router: The runtime component that executes the supergraph, handling query planning, routing, and response merging.

A subgraph is an independent GraphQL service that defines a portion of the overall domain model. Each subgraph is responsible for a specific set of types and fields, which it owns. Subgraphs use federation-specific schema directives (like @key, @shareable, @requires) to declare how their portion of the data graph connects to others.

• Ownership: A subgraph is the single source of truth for the types and fields it defines.
• Autonomy: Subgraphs can be developed, deployed, and scaled independently by separate teams.
• Example: An Orders subgraph might own the Order type, while a Products subgraph owns the Product type.

Schema stitching is an alternative, older technique for combining multiple GraphQL schemas into a single gateway schema. Unlike federation, which relies on subgraphs declaring their relationships via directives, stitching typically involves a centralized gateway manually wiring together schemas and writing resolver logic to merge types and fields.

• Key Difference: Federation is a declarative architecture, while stitching is often more imperative and procedural.
• Complexity: Stitching can become complex to maintain as the number of services grows, whereas federation's declarative nature offers more robust tooling for schema composition and conflict resolution.

Query planning is the process performed by the federation gateway to decompose a client's GraphQL query into a series of sub-queries (query plans) that can be executed against the relevant subgraphs. The planner must optimize for:

• Correctness: Ensuring all required data is fetched.
• Efficiency: Minimizing the number of subgraph calls and avoiding redundant data fetching (the N+1 problem).
• Ordering: Managing dependencies between subgraphs (e.g., fetching an entity's @key fields before using them in a @requires field).

Advanced gateways perform query plan caching to avoid re-planning identical queries.

An entity is a GraphQL object type that can be resolved across multiple subgraphs. It is the fundamental unit of federation. An entity is defined using the @key directive in a subgraph schema, which specifies the primary key fields needed to uniquely fetch an instance of that type.

Example:

graphqlCopy
# In Products subgraph
type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Float
}

# In Reviews subgraph
type Review {
  product: Product @provides(fields: "name")
}
extend type Product @key(fields: "id") {
  id: ID! @external
  name: String! @external
  reviews: [Review]
}

The @key(fields: "id") declares Product as an entity. The Reviews subgraph extends this entity by providing the reviews field, using the id to fetch the correct product.