Subgraph definition in GraphQL - Mini Project: Build & Apply

Create a GraphQL Subgraph Definition

📖 Scenario: You are building a modular GraphQL API for a bookstore. Each part of the API is a subgraph that handles specific data. Your task is to define a subgraph schema for the Books part of the API.

🎯 Goal: Define a GraphQL subgraph schema for books with types and directives that enable it to work as a subgraph in a federated GraphQL architecture.

📋 What You'll Learn

Create a type Book with fields id (ID!), title (String!), and author (String!)

Add the @key(fields: "id") directive to Book to specify the primary key

Add the @extends directive to Book if extending from another subgraph (optional for this project)

Include the @external directive on fields that are resolved by other subgraphs (optional for this project)

Define the Query type with a field books returning a list of Book

💡 Why This Matters

🌍 Real World

GraphQL subgraphs allow teams to build modular APIs that can be composed into a single federated graph, improving scalability and collaboration.

💼 Career

Understanding subgraph definitions is essential for backend developers working with GraphQL federation in modern microservice architectures.

1

Define the Book type with fields

Create a GraphQL type called Book with fields id of type ID!, title of type String!, and author of type String!.

GraphQL

# Define the Book type with id, title, and author fields
# Your code here

Hint

Use the type keyword to define a GraphQL type. Fields have names and types separated by a colon.

2

Add the @key directive to Book

Add the @key(fields: "id") directive to the Book type to specify that id is the primary key for this subgraph.

GraphQL

type Book @key(fields: "id") {
  id: ID!
  title: String!
  author: String!
}
# Your code here

Hint

The @key directive is used to mark the primary key field(s) for federation.

3

Define the Query type with books field

Create a Query type with a field called books that returns a list of Book objects. Use square brackets [] to indicate a list.

GraphQL

type Book @key(fields: "id") {
  id: ID!
  title: String!
  author: String!
}

# Define the Query type with books field
# Your code here

Hint

The Query type is the entry point for queries. Use square brackets to indicate a list of items.

4

Add the @extends and @external directives (optional)

Add the @extends directive to the Book type and the @external directive to the author field to indicate that author is resolved by another subgraph.

GraphQL

type Book @key(fields: "id") @extends {
  id: ID!
  title: String!
  author: String! @external
}

type Query {
  books: [Book]
}
# Your code here

Hint

The @extends directive marks a type as extending another subgraph's type. The @external directive marks fields resolved elsewhere.

Practice

1. What is the main purpose of defining a subgraph in a GraphQL architecture?

easy

A. To split a large graph into smaller, manageable parts

B. To increase the number of queries sent to the server

C. To combine multiple databases into one

D. To replace the need for a schema in GraphQL

Solution

1. Step 1: Understand the concept of subgraphs

   Subgraphs are used to divide a big graph into smaller parts for clarity and manageability.

2. Step 2: Identify the main purpose

   The main goal is to make data easier to manage and improve collaboration by splitting the graph.

3. Final Answer:

   To split a large graph into smaller, manageable parts -> Option A

4. Quick Check:

   Subgraphs = smaller parts [OK]

Hint: Subgraphs break big graphs into smaller pieces [OK]

Common Mistakes:

• Thinking subgraphs increase query count
• Confusing subgraphs with database merging
• Believing subgraphs replace schemas

2. Which of the following is the correct way to define a unique key for a subgraph entity using the @key directive?

easy

A. type Product @key(fields: id) { id: ID! name: String }

B. type Product @key(id) { id: ID! name: String }

C. type Product @key(fields: "id") { id: ID! name: String }

D. type Product @key("id") { id: ID! name: String }

Solution

1. Step 1: Recall the syntax of the @key directive

   The @key directive requires the fields argument as a string specifying the unique key fields.

2. Step 2: Match the correct syntax

   type Product @key(fields: "id") { id: ID! name: String } correctly uses @key(fields: "id") with quotes around the field name.

3. Final Answer:

   type Product @key(fields: "id") { id: ID! name: String } -> Option C

4. Quick Check:

   @key(fields: "id") = correct syntax [OK]

Hint: Use quotes around fields in @key directive [OK]

Common Mistakes:

• Omitting quotes around field names
• Using @key without 'fields:' keyword
• Passing field name without string quotes

3. Given this subgraph definition:

type User @key(fields: "userID") {
  userID: ID!
  name: String
  email: String
}

What will happen if you query for { user { userID name } } in a federated setup?

medium

A. The query returns userID and name for the User entity correctly

B. The query fails because email is missing in the query

C. The query returns only userID but not name

D. The query returns an error due to missing @key directive

Solution

1. Step 1: Understand the @key directive role

   The @key directive marks userID as the unique identifier for User entities in the subgraph.

2. Step 2: Analyze the query fields

   The query requests userID and name, both defined in the User type, so it will succeed.

3. Final Answer:

   The query returns userID and name for the User entity correctly -> Option A

4. Quick Check:

   Query fields in schema = successful fetch [OK]

Hint: Query only requested fields defined in subgraph [OK]

Common Mistakes:

• Assuming all fields must be queried
• Confusing @key with required query fields
• Expecting error if some fields are omitted

4. Consider this subgraph schema:

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

Which of the following fixes the error in this subgraph definition?

Option A:

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

Option B:

type Product @key(fields: sku) {
  sku: ID!
  name: String
  price: Float
}

Option C:

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

Option D:

type Product {
  sku: ID!
  name: String
  price: Float
}

medium

A. Change @key fields to "id" instead of "sku"

B. No change needed; the original schema is correct

C. Remove quotes around sku in @key directive

D. Remove the @key directive entirely

Solution

1. Step 1: Check the original @key syntax

   The original schema uses @key(fields: "sku") correctly with quotes around the field name.

2. Step 2: Verify field existence

   The field sku exists and matches the @key directive, so no error is present.

3. Final Answer:

   No change needed; the original schema is correct -> Option B

4. Quick Check:

   Correct @key syntax and matching field = no error [OK]

Hint: Quotes around fields in @key are required [OK]

Common Mistakes:

• Removing quotes around fields in @key
• Using a field name not present in the type
• Removing @key directive causing federation errors

5. You want to create a subgraph for an Orders service. Each Order has a unique orderID and a list of items. Which is the best way to define the subgraph schema to support federation and ensure uniqueness?

hard

A. type Order @key(fields: "orderID items") { orderID: ID! items: [String] }

B. type Order { orderID: ID! items: [String] }

C. type Order @key(fields: "items") { orderID: ID! items: [String] }

D. type Order @key(fields: "orderID") { orderID: ID! items: [String] }

Solution

1. Step 1: Identify the unique key for the Order entity

   The unique identifier is orderID, so it should be used in the @key directive.

2. Step 2: Check the correct @key usage

   Using @key(fields: "orderID") correctly marks orderID as the unique key for federation.

3. Final Answer:

   type Order @key(fields: "orderID") { orderID: ID! items: [String] } -> Option D

4. Quick Check:

   Unique key = orderID in @key [OK]

Hint: Use unique ID field in @key directive for subgraph entities [OK]

Common Mistakes:

• Omitting @key directive causing federation issues
• Using non-unique fields like items in @key
• Combining multiple fields incorrectly in @key