Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free


Learn about subgraphs in a federated supergraph

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

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


You can implement different subgraphs using completely different programming languages and libraries.

Choosing a subgraph library

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

See federation-compatible subgraph libraries.

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


If you're using 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 can access your individual subgraphs.

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

There are many reasons for this:

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 supergraph, especially one with tens or even hundreds of subgraphs.

For more information on securing your subgraphs with a supergraph, see this article.

Disabling CORS

We recommend that subgraphs 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 subgraph directly.

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

Subgraph-specific fields

Subgraph-compatible server libraries automatically add some federation-specific definitions to your . In addition to definitions like @key, the most useful of these definitions for debugging are two fields 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 subgraph references another subgraph's , it uses an entity representation to do so. An entity representation is an object that includes only the entity's __typename and the fields 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 subgraph's schema.

You can query this field 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 subgraph, you can test the return value of the _entities field for various entity representations that your other subgraphs use.

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


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

query GetSubgraphSchema {
_service {

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

  • Unlike , the sdl field is not disabled by default in production environments (this is safe if you properly secure your subgraph).
  • Unlike introspection, the sdl field's returned string includes federation-specific like @key.
Supported Subgraph Libraries
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy