Subgraph Specific Fields
Learn fields automatically added to subgraph schemas
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
.