Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio


In a federated supergraph

Every federated includes one or more subgraphs. Each is a separate GraphQL service that's responsible for a different portion of your 's available data.

Here's a basic that includes two s (Users and Products):


You can implement different s using completely different programming languages and GraphQL server libraries!

Choosing a subgraph library

Every in your should use a subgraph-compatible GraphQL server library. These are libraries that adhere to the Apollo Federation specification, which ensures that your can take full advantage of federation features like entities.

See federation-compatible subgraph libraries.

After you select a library, consult its documentation to learn how to configure it to run as a subgraph.

If you're using Apollo Server as your subgraph library, see Implementing a subgraph with Apollo Server.

Securing your subgraphs

Implement any necessary firewall rules, access control lists, or other security measures in your environment to ensure that only your supergraph's router can access your individual s.

Clients should never query a subgraph directly! Instead, clients should always query your , which resolves those queries by communicating with your s.

There are many reasons for this:

  • libraries automatically add powerful fields to your that clients should not have access to.
    • The uses these s to cross boundaries while resolving complex s.
  • Providing a single endpoint for your entire reduces its overall attack surface.

In addition to the above security concerns, a significant benefit of any GraphQL API is that clients only need to interact with one endpoint. This definitely holds true for a , especially one with tens or even hundreds of s!

For more information on securing your s with a cloud , see this article.

Disabling CORS

We recommend that s do not enable CORS (or at least, do not use the wildcard access-control-allow-origin: * header). This prevents attackers from exploiting a user's browser to access a directly.

For Apollo Server s, you need to disable the default wildcard CORS policy (this policy is appropriate for many monolithic public API servers, but not for s). For details, see the Apollo Server CORS documentation.

Subgraph-specific fields

-compatible server libraries automatically add some federation-specific definitions to your subgraph . In addition to definitions like @key, the most useful of these definitions for debugging are two s of the Query type: _service and _entities:

type Query {
# ...your field definitions...
# Added automatically
_service: _Service!
_entities(representations: [_Any!]!): [_Entity]!


Learn about entities if you haven't yet.

This takes a list of entity representations and returns a list of corresponding entities.

Whenever one references another 's entity, it uses an entity representation to do so. An entity representation is an object that includes only the entity's __typename and the s in the entity's @key.

_entities(representations: [_Any!]!): [_Entity]!
  • The _Any type is a special that enables you to provide entity representations of any valid shape.
  • The _Entity type is a generated union type that includes every entity defined in your 's .

You can query this like so, providing a value for the $representations as shown:

query ($representations: [_Any!]!) {
_entities(representations: $representations) {
... on User {
"representations": [
"__typename": "User",
"id": "5"

Using in tests and debugging

If you're writing integration tests for your , you can test the return value of the _entities for various entity representations that your other s use.

If you're developing your in your local environment, you can mock the return value of the _entities for your other s so you don't have to connect those subgraphs to their respective data stores.


This returns a _Service object with one of its own: sdl. You can query it like so:

query GetSubgraphSchema {
_service {

The sdl returns your 's as an string. This field has a couple of important differences from a standard introspection query that a tool like Apollo Sandbox uses:

  • Unlike , the sdl is not disabled by default in production environments (this is safe if you properly secure your subgraph).
  • Unlike , the sdl 's returned string includes federation-specific s like @key.
4️⃣ Working with subgraphs
Supported subgraph libraries
Edit on GitHubEditForumsDiscord