Launch GraphOS Studio

Updating your graph safely

Upgrade your components in the recommended order to avoid errors

Your consists of multiple components that are each versioned independently:

Your infrastructure
Subgraph A
Subgraph B

  • The router is powered by a particular version of the Apollo Router.
  • The GraphOS build pipeline uses a particular version of to compose your 's .
    • If you use the Rover CLI to compose your , this is true for as well. In this case, you effectively maintain your own build pipeline.
  • Your subgraph schemas might each use special that were first introduced in a particular version of .

These components each target support for a particular version of Apollo Federation, the architecture that underpins every . Because of this, it's important to make sure these various Federation versions remain compatible with each other as you make updates to individual components.

To avoid runtime or composition errors, your 's components should always maintain the following relationship between their targeted versions:


(Router fed. version) ≥ (Build Pipeline fed. version) ≥ (Subgraph fed. version)

To maintain this relationship, always update these components in order from left to right:

1. Router
2. Build Pipeline
3. Subgraph Schemas

1. Update your router

The method you use to update your depends on which type of you have:

For details on each version's corresponding version, see this article.

2. Update your build pipeline

Whenever you make an operational change to your (such as publishing changes to a subgraph schema), initiates a build that composes your 's new . From GraphOS Studio, you can configure which version of the build pipeline uses to perform this .


enables you to choose between minor versions of Federation (such as 2.1). Each option automatically uses the latest supported patch release of that minor version (such as 2.1.4).

Although patch release updates are automatic, you must manually move a 's build pipeline to a different minor release.

  1. Go to your 's Settings page, then find the General > Build Configuration section.

    Build configuration settings in Studio
  2. Click Edit Configuration. The following dialog appears:

    Build configuration dialog in Studio
  3. Select a Federation version from the Supergraph Pipeline Track dropdown and click Save.

immediately initiates a new build using the selected Federation version, and all future builds also use the selected version.

Composing with the Rover CLI

If you host your own instance, you can use the Rover CLI to compose its via the rover supergraph compose command.


Performing composition with Rover is not recommended. Instead, perform via the GraphOS build pipeline to help ensure a consistent process across all your 's environments.

If you do perform with rover supergraph compose, the command uses the exact version of you specify via the federation_version key in the YAML configuration file you pass:

rover supergraph compose --config ./supergraph.yaml
federation_version: =2.3.2
# ...

This value must target a specific patch release (2.3.1, 2.3.2, etc.), and it must start with an equals sign (=).


If you don't provide a value for federation_version, prints a warning and chooses a version according to this logic. This could potentially cause failures. might use a newer version than what your supports, resulting in a that causes the router to fail on startup.

Learn more about setting a Rover composition version.

3. Update subgraph schemas (as needed)

After both your router and your build pipeline support a particular minimum version of , your can use features that were first introduced in that version.


You don't need to update any that doesn't use newly introduced features. Different subgraph schemas can target different Federation versions as needed. Ultimately, your build pipeline determines which version of is actually used to create the .

As an example, the @interfaceObject directive was first introduced in Federation 2.3. To start using this in a , do the following:

  1. Make sure your chosen library has added support for the @interfaceObject by consulting this table.

    • If your library doesn't yet support the , reach out to its maintainers about adding support.
  2. Upgrade to the latest version of your library to make sure you're using a version that supports @interfaceObject.

  3. Modify the following @link in your (or add it if it isn't present yet):

    extend schema
    url: ""
    import: ["@key", "@shareable", "@interfaceObject"]

    Notice that the url targets v2.3 of the spec, and @interfaceObject is included in the import list.

  4. Apply the @interfaceObject to relevant locations in your .

Because you've already updated your router and build pipeline, the next time you deploy your and publish its schema to , every component in your will be prepared to interact with a schema that includes the @interfaceObject you've added.

Why is this update order necessary?

use the Apollo Federation 2 architecture. Federation 2 is itself a versioned technology (2.2, 2.3, etc.), and each version introduces changes and additions to the set of supported subgraph directives.

  • Each version of the is compiled against a particular version of Federation 2 (for details, see this table). Any given version is backward compatible with previous versions of Federation. However, it isn't compatible with newer versions.

    Therefore, it's important to update your first, before any other component begins using a later Federation 2 version. Otherwise, you might cause your router to break by providing it a that it doesn't support.

  • Your 's Supergraph Pipeline Track setting in determines which version of Federation 2 is used to compose your . This process fails if one of your uses a that was introduced in a Federation version later than your chosen pipeline track.

    • In the case of a failed build, continues to provide your with the from the most recent successful build.
  • Finally, are where you actually apply new Federation 2 . You need to update your subgraph library to a version that recognizes all directives that you use in your schema.

    You perform this update last to make sure that every other component of your is prepared to interact with any newly introduced .

Local development
Managing graphs in Studio
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy