Field-level cost analysis in GraphQL

Introduction

Field-level cost analysis helps you understand how much work each part of a GraphQL query takes. This helps keep your server fast and avoid overload.

When you want to find which fields in a query use the most resources.

When you need to limit expensive queries to protect your server.

When you want to optimize your GraphQL API for better performance.

When you want to give feedback to clients about costly queries.

When you want to monitor and track query costs over time.

Syntax

GraphQL

type Query {
  fieldName: FieldType @cost(complexity: Int, multipliers: [String])
}

The @cost directive is used to assign a cost to a field.

complexity is the base cost number for the field.

Examples

This sets the cost of the books field to 5.

GraphQL

type Query {
  books: [Book] @cost(complexity: 5)
}

The cost depends on the id argument, multiplying the base cost.

GraphQL

type Query {
  author(id: ID!): Author @cost(complexity: 2, multipliers: ["id"])
}

Sample Program

This schema assigns costs to users and posts fields. The posts cost multiplies by the userId argument.

The sample query fetches users and posts for user 123.

GraphQL

type Query {
  users: [User] @cost(complexity: 3)
  posts(userId: ID!): [Post] @cost(complexity: 2, multipliers: ["userId"])
}

# Sample query
{
  users {
    id
    name
  }
  posts(userId: "123") {
    title
  }
}

Important Notes

Costs help prevent very expensive queries from slowing down your server.

Multipliers let you adjust cost based on input values, like list sizes.

Always test your cost settings to balance protection and usability.

Summary

Field-level cost analysis assigns a cost number to each GraphQL field.

This helps track and limit query resource use.

Use @cost directive with complexity and optional multipliers.

Practice

1. What is the main purpose of using the @cost directive in GraphQL field-level cost analysis?

easy

A. To rename a field in the schema

B. To define the data type of a field

C. To specify the default value of a field

D. To assign a numeric cost to each field to track resource usage

Solution

1. Step 1: Understand the purpose of field-level cost analysis

   Field-level cost analysis helps monitor and limit resource use by assigning costs to fields.

2. Step 2: Identify the role of the @cost directive

   The @cost directive assigns a numeric complexity cost to each field to estimate query cost.

3. Final Answer:

   To assign a numeric cost to each field to track resource usage -> Option D

4. Quick Check:

   @cost assigns cost = A [OK]

Hint: Remember: @cost tracks resource use per field [OK]

Common Mistakes:

• Confusing cost with data type definition
• Thinking @cost renames fields
• Assuming it sets default values

2. Which of the following is the correct syntax to add a cost directive with complexity 5 to a GraphQL field named books?

easy

A. books: [Book] @cost(complexity: 5)

B. books: [Book] @cost(5)

C. books: [Book] @cost(complexity=5)

D. books: [Book] @cost { complexity: 5 }

Solution

1. Step 1: Recall the correct directive syntax

   The @cost directive uses parentheses with named arguments, e.g., @cost(complexity: 5).

2. Step 2: Check each option's syntax

   books: [Book] @cost(complexity: 5) uses correct syntax with named argument and colon. The other three options use incorrect syntax forms.

3. Final Answer:

   books: [Book] @cost(complexity: 5) -> Option A

4. Quick Check:

   Correct directive syntax = B [OK]

Hint: Use parentheses and colon for directive args: @cost(complexity: 5) [OK]

Common Mistakes:

• Using equal sign instead of colon
• Omitting parentheses
• Using braces instead of parentheses

3. Given the schema snippet:

type Query {
  users: [User] @cost(complexity: 2, multipliers: ["first"])
}

input UserFilter {
  first: Int
}

And the query:

{ users(first: 3) { id name } }

What is the total cost of this query assuming id and name fields have cost 1 each?

medium

A. 3

B. 6

C. 8

D. 5

Solution

1. Step 1: Calculate base complexity and multipliers

   Base complexity is 2. The multiplier is the argument "first" with value 3, so multiply 2 * 3 = 6.

2. Step 2: Add cost of requested fields

   Fields id and name each cost 1, total 2. Add to 6 gives 8.

3. Final Answer:

   8 -> Option C

4. Quick Check:

   2 * 3 + 1 + 1 = 8 [OK]

Hint: Multiply complexity by argument, then add field costs [OK]

Common Mistakes:

• Ignoring multipliers
• Not adding field costs
• Multiplying fields cost instead of adding

4. Consider this incorrect directive usage:

type Query {
  posts: [Post] @cost(complexity: "high")
}

What is the main error here?

medium

A. The complexity value must be an integer, not a string

B. The field name posts is invalid

C. The directive @cost cannot be used on lists

D. The directive syntax is missing parentheses

Solution

1. Step 1: Check the type of complexity argument

   The complexity argument expects an integer value, but "high" is a string.

2. Step 2: Verify other parts of the directive usage

   The field name and directive usage are valid; parentheses are present.

3. Final Answer:

   The complexity value must be an integer, not a string -> Option A

4. Quick Check:

   Complexity expects integer = D [OK]

Hint: Complexity must be a number, not text [OK]

Common Mistakes:

• Using string instead of integer for complexity
• Thinking directive can't be on lists
• Missing parentheses in directive

5. You have a GraphQL field comments with @cost(complexity: 1, multipliers: ["limit"]). The query requests comments(limit: 4) with subfields text and author, each costing 2. What is the total cost of this query?

hard

A. 12

B. 8

C. 10

D. 6

Solution

1. Step 1: Calculate base complexity with multiplier

   Base complexity is 1. Multiplier is argument "limit" with value 4, so 1 * 4 = 4.

2. Step 2: Add cost of subfields

   Subfields text and author each cost 2, total 4. Add to 4 gives 8.

3. Step 3: Verify the total

   Subfields are added flatly without further multiplication by list size: 4 (base) + 4 (subfields) = 8.

4. Final Answer:

   8 -> Option B

5. Quick Check:

   1*4 + (2+2) = 8 [OK]

Hint: Add base cost times multiplier plus subfields cost [OK]

Common Mistakes:

• Multiplying subfields cost by multiplier (e.g., getting 20)
• Adding costs without multiplier
• Confusing which costs to multiply