Subgraph definition in GraphQL - Step-by-Step Execution

Concept Flow - Subgraph definition

Start Subgraph Definition

↓

Define Types and Fields

↓

Add @key Directive for Entity

↓

Add @external Directive for Shared Fields

↓

Add @requires or @provides for Field Dependencies

↓

Export Subgraph Schema

↓

Subgraph Ready for Federation

This flow shows how to define a GraphQL subgraph schema step-by-step for federation.

Execution Sample

GraphQL

type Product @key(fields: "id") {
  id: ID!
  name: String
  price: Float
  weight: Float @external
}

Defines a Product type with a key and marks weight as external to indicate it's owned by another subgraph.

Execution Table

Step	Action	Schema Part	Directive Applied	Effect
1	Define Product type	type Product { id, name, price, weight }	None	Basic type with fields
2	Add @key directive	type Product @key(fields: "id")	@key(fields: "id")	Marks id as entity key
3	Mark weight as external	weight: Float @external	@external	Indicates weight is owned by another subgraph
4	Complete subgraph schema	Full schema with directives	All applied	Subgraph ready for federation

💡 All necessary directives applied, subgraph schema is valid and ready

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
Product Type	undefined	Defined with fields	Added @key directive	Marked weight @external	Final subgraph type definition
Directives	None	None	@key(fields: "id")	@key + @external	All directives applied

Key Moments - 3 Insights

Why do we add the @key directive to a type?

The @key directive marks which field(s) uniquely identify an entity across subgraphs, as shown in execution_table step 2.

What does the @external directive mean on a field?

It means the field is owned by another subgraph and is referenced here, as shown in execution_table step 3.

Can a subgraph define a type without any directives?

Yes, but it won't participate in federation properly. Directives like @key are needed for entity resolution, as shown in steps 2 and 3.

Visual Quiz - 3 Questions

Look at the execution_table, at which step is the @key directive added?

A Step 2

B Step 1

C Step 3

D Step 4

💡 Hint

Refer to the 'Directive Applied' column in execution_table row for Step 2.

According to variable_tracker, what is the state of the Product Type after Step 3?

A Added @key directive only

B Marked weight @external

C Defined with fields only

D No directives applied

💡 Hint

Check the 'Product Type' row under 'After Step 3' in variable_tracker.

If we omit the @external directive on weight, what effect would it have?

A Schema becomes invalid

B Weight is ignored in federation

C Weight is treated as owned by this subgraph

D No effect

💡 Hint

Recall the meaning of @external from key_moments and execution_table step 3.

Concept Snapshot

Subgraph Definition in GraphQL:
- Define types with fields
- Use @key(fields: "id") to mark entity keys
- Use @external on fields owned by other subgraphs
- Optionally use @requires/@provides for dependencies
- Export schema for federation

Full Transcript

Defining a subgraph in GraphQL involves creating types with fields and adding special directives. The @key directive marks the unique identifier for entities, enabling federation to recognize them. The @external directive marks fields that belong to other subgraphs but are referenced here. This process ensures the subgraph schema is ready to be combined with others in a federated graph. The execution table shows each step applying these directives, and the variable tracker shows how the type and directives evolve. Understanding these directives is key to building federated GraphQL services.