Subgraph Specific Fields

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

1type Query {
2  # ...your field definitions...
3
4  # Added automatically
5  _service: _Service!
6  _entities(representations: [_Any!]!): [_Entity]!
7}

Query._entities

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

Whenever one subgraph references another subgraph'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 fields in the entity's @key.

1_entities(representations: [_Any!]!): [_Entity]!

• The _Any type is a special scalar 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 variable as shown:

1query ($representations: [_Any!]!) {
2  _entities(representations: $representations) {
3    ... on User {
4      id
5      username
6    }
7  }
8}

1{
2  "representations": [
3    {
4      "__typename": "User",
5      "id": "5"
6    }
7  ]
8}

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.

Query._service

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

1query GetSubgraphSchema {
2  _service {
3    sdl
4  }
5}

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

• Unlike introspection, 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 directives like @key.