Docs
Launch GraphOS Studio

Advanced topics on federated entities


This article describes complex behaviors of federated entities beyond those covered in entity basics.

Advanced @keys

A single entity can have multiple @keys. Additionally, a @key can include multiple fields, and even arbitrarily nested fields.

Multiple @keys

You can define more than one @key for an entity, when applicable.

In this example, a Product entity can be uniquely identified by either its id or its sku:

Products subgraph
type Product @key(fields: "id") @key(fields: "sku") {
id: ID!
sku: String!
name: String!
price: Int
}

This pattern is helpful when different subgraphs interact with different fields of an entity. For example, a Reviews subgraph might refer to products by their ID, whereas an Inventory subgraph might use SKUs.

A subgraph that references an entity without contributing any fields can include the fields of any @key in its stub definition:

Reviews subgraph
# Either:
type Product @key(fields: "id", resolvable: false) {
id: ID!
}
# Or:
type Product @key(fields: "sku", resolvable: false) {
sku: String!
}

Compound @keys

A single @key can consist of multiple fields, and even nested fields.

In this example, the User entity's primary key consists of both a user's id and the id of that user's associated Organization:

Users subgraph
type User @key(fields: "id organization { id }") {
id: ID!
organization: Organization!
}
type Organization {
id: ID!
}

Migrating entities and fields

As your supergraph grows, you might want to move parts of an entity to a different subgraph. This section describes how to perform these migrations safely.

Incremental migration with @override

Let's say our Payments subgraph defines a Bill entity:

Payments subgraph
type Bill @key(fields: "id") {
id: ID!
amount: Int!
payment: Payment
}
type Payment {
# ...
}

Then, we add a dedicated Billing subgraph to our supergraph. It now makes sense to move billing functionality there. When we're done migrating, we want our deployed subgraph schemas to look like this:

Payments subgraph
type Bill @key(fields: "id") {
id: ID!
payment: Payment
}
type Payment {
# ...
}
Billing subgraph
type Bill @key(fields: "id") {
id: ID!
amount: Int!
}

The @override directive enables us to perform this migration incrementally with no downtime.

First, we deploy a new version of the Billing subgraph that defines and resolves the Bill fields we want to move:

Payments subgraph
type Bill @key(fields: "id") {
id: ID!
amount: Int!
payment: Payment
}
type Payment {
# ...
}
Billing subgraph
type Bill @key(fields: "id") {
id: ID!
amount: Int! @override(from: "Payments")
}

The @override directive says, "Resolve this field in this subgraph instead of in the Payments subgraph."

In any subgraph where you use @override, make sure to include it in your schema's @link imports (code-first subgraph libraries usually do this for you):

Billing subgraph
extend schema
@link(url: "https://specs.apollo.dev/federation/v2.3",
import: ["@key", "@shareable", "@override"])

Next, we update our router's supergraph schema to include the updated Billing subgraph. If you're using managed federation, you do this by publishing the Billing subgraph's schema to GraphOS with rover subgraph publish.

When the router receives its updated supergraph schema, it immediately starts resolving the Bill.amount field from the Billing subgraph while continuing to resolve Bill.payment from the Payments subgraph.

We can migrate as many entity fields as we want in a single change. To do so, we apply @override to every entity field we want to move. We can even migrate entire entities this way!

Now that Bill.amount is resolved in the Billing subgraph, we can safely remove that field (and its resolver) from the Payments subgraph:

Payments subgraph
type Bill @key(fields: "id") {
id: ID!
payment: Payment
}
type Payment {
# ...
}
Billing subgraph
type Bill @key(fields: "id") {
id: ID!
amount: Int! @override(from: "Payments")
}

After making this change, we deploy our updated Payments subgraph and again update our router's supergraph schema.

Because the router is already ignoring Bill.amount in the Payments subgraph thanks to @override, we can safely publish our updated schema and deploy the subgraph in any order!

Finally, we can remove the @override directive from the Billing subgraph, because it no longer has any effect:

Payments subgraph
type Bill @key(fields: "id") {
id: ID!
payment: Payment
}
type Payment {
# ...
}
Billing subgraph
type Bill @key(fields: "id") {
id: ID!
amount: Int!
}

After we deploy the Billing subgraph and publish this final schema change, we're done! We've migrated Bill.amount to the Billing subgraph with zero downtime.

Optimizing for fewer deploys with manual composition

⚠️ This method requires careful coordination between subgraph and router updates. Without strict control over the order of deployments and schema updates, you might cause an outage. For most use cases, we recommend using the @override method above.

Using @override to migrate entity fields enables us to migrate fields incrementally with zero downtime. However, doing so requires three separate schema publishes. If you're using manual composition, each schema change requires redeploying your router. With careful coordination, we can perform the same migration with only a single router redeploy.

  1. In the Billing subgraph, define the Bill entity, along with its corresponding resolvers. These new resolvers should behave identically to the Payment subgraph resolvers they're replacing.

    Payments subgraph
    type Bill @key(fields: "id") {
    id: ID!
    amount: Int!
    payment: Payment
    }
    type Payment {
    # ...
    }
    Billing subgraph
    type Bill @key(fields: "id") {
    id: ID!
    amount: Int!
    }
  2. Deploy the updated Billing subgraph to your environment, but do not publish the updated schema yet.

    • At this point, the Billing subgraph can successfully resolve Bill objects, but the router doesn't know this yet because its supergraph schema hasn't been updated. Publishing the schema would cause a composition error.
  3. In the Payments subgraph, remove the migrated fields from the Bill entity and their associated resolvers (do not deploy this change yet):

    Payments subgraph
    type Bill @key(fields: "id") {
    id: ID!
    payment: Payment
    }
    type Payment {
    # ...
    }
    Billing subgraph
    type Bill @key(fields: "id") {
    id: ID!
    amount: Int!
    }
  4. Compose an updated supergraph schema with your usual configuration using rover supergraph compose.

    • This updated supergraph schema indicates that the Billing subgraph resolves Bill.amount, and the Payments subgraph doesn't.
  5. Assuming CI completes successfully, deploy an updated version of your router with the new supergraph schema.

    • When this deployment completes, the router begins resolving Bill fields in the Billing subgraph instead of the Payments subgraph.

    ⚠️ While your new router instances are deploying, you will probably have active router instances resolving the Bill.amount field in two different ways (with older instances still resolving it from Payments). It's important that the two subgraphs resolve the field in exactly the same way, or your clients might see inconsistent data during this rollover.

  6. Deploy the updated version of your Payments subgraph without the migrated field.

    • At this point it's safe to remove this definition, because your router instances are using the Billing subgraph exclusively.

We're done! The migrated fields have been moved to a new subgraph, and we only redeployed our router once.

Contributing computed entity fields

You can define fields of an entity that are computed based on the values of other entity fields that are resolved by a different subgraph.

For example, this Shipping subgraph adds a shippingEstimate field to the Product entity. This field is calculated based on the product's size and weight, which are defined in the Products subgraph:

Shipping subgraph
type Product @key(fields: "id") {
id: ID!
size: Int @external
weight: Int @external
shippingEstimate: String @requires(fields: "size weight")
}

As shown, you use the @requires directive to indicate which fields (and subfields) from other subgraphs are required. You also need to define the required fields and apply the @external directive to them. This directive tells the router, "This subgraph knows that these fields exist, but it can't resolve them itself."

In the above example, if a query requests a product's shippingEstimate, the router does the following, in order:

  1. It queries the Products subgraph for the product's size and weight.
  2. It queries the Shipping subgraph for the product's shippingEstimate. The size and weight are included in the Product object passed to the resolver for shippingEstimate:
{
Product: {
shippingEstimate(product) {
return computeShippingEstimate(product.id, product.size, product.weight);
}
}
}

Using @requires with object subfields

If a computed field @requires a field that returns an object type, you also specify which subfields of that object are required. You list those subfields with the following syntax:

Shipping subgraph
type Product @key(fields: "id") {
id: ID!
dimensions: ProductDimensions @external
shippingEstimate: String @requires(fields: "dimensions { size weight }")
}

In this modification of the previous example, size and weight are now subfields of a ProductDimensions object. Note that the ProductDimensions type must be defined in both the Products and Shipping subgraphs for this to be valid.

Using @requires with fields that take arguments

This functionality was introduced in Federation v2.1.2.

The @requires directive can include fields that take arguments, like so:

Shipping subgraph
type Product @key(fields: "id") {
id: ID!
weight(units: String): Int @external
shippingEstimate: String @requires(fields: "weight(units:\"KILOGRAMS\")")
}
  • The router provides the specified values in its query to whichever subgraph defines the required field.
  • Each specified argument value is static (i.e., the router always provides the same value).
  • You can omit values for nullable arguments. You must provide values for non-nullable arguments.
  • If you define your subgraph schema in an SDL file (instead of programmatically), you must escape quotes for string and enum values with backslashes (as shown above).

Resolving another subgraph's field

By default, exactly one subgraph is responsible for resolving each field in your supergraph schema (with important exceptions, like entity @key fields). But sometimes, multiple subgraphs are able to resolve a particular entity field, because all of those subgraphs have access to a particular data store. For example, an Inventory subgraph and a Products subgraph might both have access to the database that stores all product-related data.

You can enable multiple subgraphs to resolve a particular entity field. This is a completely optional optimization. When the router plans a query's execution, it looks at which fields are available from each subgraph. It can then attempt to optimize performance by executing the query across the fewest subgraphs needed to access all required fields.

You achieve this with one of the following directives:

Which directive you use depends on the following logic:

Always
Only certain query paths
Can my subgraph always resolve this field,
or only from certain query paths?
@shareable
@provides

If you aren't sure whether your subgraph can always resolve a field, see Using @provides for an example of a subgraph that can't.

Ensure resolver consistency

If multiple subgraphs can resolve a field, make sure each subgraph's resolver for that field behaves identically. Otherwise, queries might return inconsistent results to clients depending on which subgraph resolves the field.

This is especially important to keep in mind when making changes to an existing resolver. If you don't make the resolver changes to each subgraph simultaneously, clients might observe inconsistent results.

Common inconsistent resolver behaviors to look out for include:

  • Returning a different default value
  • Throwing different errors in the same scenario

Using @shareable

⚠️ Before using @shareable, see Ensure resolver consistency.

The @shareable directive indicates that a particular field can be resolved by more than one subgraph:

Products subgraph
type Product @key(fields: "id") {
id: ID!
name: String! @shareable
price: Int
}
Inventory subgraph
type Product @key(fields: "id") {
id: ID!
name: String! @shareable
inStock: Boolean!
}

In this example, both the Products and Inventory subgraphs can resolve Product.name. This means that a query that includes Product.name might be resolvable by fetching from fewer total subgraphs.

If a field is marked @shareable in any subgraph, it must be marked @shareable or @external in every subgraph that defines it. Otherwise, composition fails.

Using @provides

⚠️ Before using @provides, see Ensure resolver consistency.

The @provides directive indicates that a particular field can be resolved by a subgraph at a particular query path. Let's look at an example.

Here, our Products subgraph defines a Product.name field and marks it @shareable (this means other subgraphs are allowed to resolve it):

Products subgraph
type Product @key(fields: "id") {
id: ID!
name: String! @shareable
price: Int
}

Meanwhile, our Inventory subgraph can also resolve a product's name, but only when that product is part of an InStockCount:

Inventory subgraph
type InStockCount {
product: Product! @provides(fields: "name")
quantity: Int!
}
type Product @key(fields: "id") {
id: ID!
name: String! @external
inStock: Boolean!
}

Here we're using two directives in combination: @provides and @external.

  • The @provides directive tells the router, "This subgraph can resolve the name of any Product object returned by InStockCount.product."
  • The @external directive tells the router, "This subgraph can't resolve the name of a Product object, except wherever indicated by @provides."

Rules for using @provides

  • If a subgraph @provides a field that it can't always resolve, the subgraph must mark that field as @external and must not mark it as @shareable.
    • Remember, a @shareable field can always be resolved by a particular subgraph, which removes the need for @provides.
  • To include a field in a @provides directive, that field must be marked as @shareable or @external in every subgraph that defines it.

Violating any of these rules causes composition to fail.

Handling the N+1 problem

Most subgraph implementations use reference resolvers (sometimes known as entity resolvers) to handle the Query._entities field ergonomically. A reference resolver is passed a single key and returns the entity object that corresponds to that key.

Although this pattern is straightforward, it can diminish performance when a client operation requests fields from many entities. To illustrate this, let's revisit an earlier example:

query GetReviewsWithProducts {
latestReviews { # Defined in Reviews
score
product {
id
price # ⚠️ NOT defined in Reviews!
}
}
}

As mentioned in The query plan, the router executes two queries on its subgraphs to resolve the above operation:

  1. It queries the Reviews subgraph to fetch all fields except Product.price.
  2. It queries the Products subgraph to fetch the price of each Product entity.

In the Products subgraph, the reference resolver for Product doesn't take a list of keys, but rather a single key. Therefore, the subgraph library calls the reference resolver once for each key:

resolvers.js
// Products subgraph
const resolvers = {
Product: {
__resolveReference(productRepresentation) {
return fetchProductByID(productRepresentation.id);
}
},
// ...other resolvers...
}

A basic implementation of the fetchProductByID function might make a database call each time it's called. If we need to resolve Product.price for N different products, this results in N database calls. These calls are made in addition to the call made by the Reviews subgraph to fetch the initial list of reviews (and the id of each product). This is where the "N+1" problem gets its name. If not prevented, this problem can cause performance problems or even enable denial-of-service attacks.

This problem is not limited to reference resolvers! In fact, it can occur with any resolver that fetches from a data store. To handle this problem, we strongly recommend using the dataloader pattern. Nearly every GraphQL server library provides a dataloader implementation, and you should use it in every resolver. This is true even for resolvers that aren't for entities and that don't return a list. These resolvers can still cause N+1 issues via batched requests.

Previous
Entities (basics)
Next
Entity interfaces
Edit on GitHubEditForumsDiscord