You're viewing documentation for a version of this software that is in development. Switch to the latest stable version
Launch Apollo Studio

Federated schemas

Overview


A federated graph uses multiple "types" of GraphQL schemas:

(Composition succeeds)
(Remove routing machinery)
Subgraph
schema
A
Subgraph
schema
B
Subgraph
schema
C
🛠
Composition
Supergraph schema
(A + B + C + routing machinery)
API schema
(A + B + C)
  • Subgraph schemas. Each subgraph has a distinct schema that indicates which types and fields of your composed supergraph it can resolve.
    • These are the only schemas that your teams define manually.
  • Supergraph schema. This schema combines all of the types and fields from your subgraph schemas, plus some Federation-specific information that tells your gateway which subgraphs can resolve which fields.
    • This schema is the result of performing composition on your collection of subgraph schemas.
  • API schema. This schema is like the supergraph schema, but it omits types, fields, and directives that are considered "machinery" and are not part of your public API (this includes Federation-specific information).
    • This is the schema that your gateway exposes to clients, who don't need to know internal implementation details about your graph.

Let's look at an example!

Subgraph schemas

Below are the schemas for three subgraphs in a basic e-commerce application. Each subgraph is implemented as a separate GraphQL API:

# Users subgraph
type Query {
  me: User
}

type User @key(fields: "id") {
  id: ID!
  username: String!
}
# Products subgraph
type Query {
  topProducts(first: Int = 5): [Product]
}

type Product @key(fields: "upc") {
  upc: String!
  name: String!
  price: Int
}
# Reviews subgraph
type Review {
  body: String
  author: User @provides(fields: "username")
  product: Product
}

extend type User @key(fields: "id") {
  id: ID! @external
  username: String! @external
  reviews: [Review]
}

extend type Product @key(fields: "upc") {
  upc: String! @external
  reviews: [Review]
}

As these schemas show, a subgraph can define and even extend types that are defined in other subgraphs. For example, the Reviews subgraph extends the User type (from the Users subgraph) and adds a reviews field to it.

Supergraph schema

The supergraph schema is the output of schema composition. It serves the following purposes:

  • It provides your gateway with the name and endpoint URL for each of your subgraphs.
  • It includes all types and fields defined by all of your subgraphs.
  • It tells your gateway which of your subgraphs can resolve which GraphQL fields.

Here's the supergraph schema composed with the subgraph schemas above:

As you can see, the supergraph schema includes a lot of Federation-specific additions! These additions are used only by the gateway, and you'll never need to add them manually.

API schema

The gateway uses its supergraph schema to produce an API schema, which it exposes to clients as your actual GraphQL API. This schema cleanly and logically represents the combination of your subgraph schemas:

type Product {
  name: String!
  price: Int
  reviews: [Review]
  upc: String!
}

type Query {
  me: User
  topProducts(first: Int = 5): [Product]
}

type Review {
  author: User
  body: String
  product: Product
}

type User {
  id: ID!
  reviews: [Review]
  username: String!
}

Unlike the supergraph schema, this schema hides the fact that your GraphQL API is composed of multiple distinct GraphQL APIs.

Edit on GitHub