GraphQL Complexity Limit

Important Starting from the June 2025 release, the public API is upgraded to HotChocolate v15.
This version introduces breaking changes in how query complexity is calculated and how the @cost directive is defined.
Make sure to review your custom queries, tools, or schema extensions that rely on previous directive arguments or complexity behavior.

Context
GraphQL queries offer flexibility and customization to users, allowing them to define their own queries.
However, this advantage can also be a potential drawback, as users may execute queries that consume significant resources.

Limit Enforcement
To prevent overloading the GraphQL engine with excessively complex and resource-intensive queries, a complexity limit is enforced on the public GraphQL API.
This limit defines the maximum allowed complexity for a query.

Result when Limit is Reached
If a query exceeds the complexity limit, the API response will contain an error message indicating that the maximum allowed operation complexity has been exceeded.
The response may include additional information such as the actual complexity of the query and the allowed complexity.

{
  "errors": [
    {
      "message": "The maximum allowed operation complexity was exceeded.",
      "extensions": {
        "complexity": 900000,
        "allowedComplexity": 100000,
        "code": "HC0047"
        }
    }
  ]
}

Maximum Complexity Limit

100000

In order to ensure optimal performance and prevent potential overload situations, a maximum complexity limit of 100,000 has been chosen for Sage Active Public API V2 queries.

This value is defined to allow a wide range of queries to be executed within the GraphQL API while still maintaining a manageable level of complexity.
This recommended value helps strike a balance between query flexibility and system resource utilization.

  • If it happens that the complexity limit is reached and you encounter any issues, it is advisable to contact Sage to explain the context and discuss the possibility of increasing the current limit.
  • By providing the necessary information about your specific use case and requirements, Sage can assess the situation and determine if an adjustment to the complexity limit is warranted.
  • This proactive approach ensures that the GraphQL API operates smoothly and efficiently, meeting your application’s needs while maintaining optimal performance.

Default Complexity Calculation

The default calculation algorithm in HotChocolate considers the complexity of the query fields and their child fields.
Each field has a default complexity, and the total cost is the sum of the individual field complexities.

Changes in Complexity Calculation with HotChocolate v15

Starting from HotChocolate v15, the complexity system has been simplified.
The directive @cost now only uses a single weight argument to indicate the cost of resolving a field.
The previous arguments (complexity, defaultMultiplier, and multipliers) have been removed from the framework and are no longer supported.
This change makes cost management more predictable and easier to configure.

Important change due to HotChocolate v15 upgrade
If you have extended the schema or used the @cost directive manually, be aware that:

  • complexity, defaultMultiplier, and multipliers were removed
  • A single weight argument is now used

Queries or tooling depending on the old directive shape will break and must be updated.

Example of GraphQL query complexity calculation:

query {
    paymentTerms (
        first: 2
        after: null
        ){
        edges {
            node {
                id
                name
                lines {
                    day
                    order
                }
            }
        }
    }
}

Let’s break down the complexity calculation for this query:

Field Name Field Type Complexity Child Complexity Sum
day Int! 1 0 1
edges [PaymentTermsEdge!] 1 6 (node) 7
id UUID 1 0 1
lines [PaymentTermLineGLDto!] 1 2 (day + order) 3
name String 1 0 1
node PaymentTermGLDto! 1 5 (id + name + lines) 6
order Int! 1 0 1
         
paymentTerms PaymentTermsConnection 5 7 (edges) 12

The total complexity of this query is 12.

HotChocolate Official Documentation

For more detailed information on operation complexity and its configuration, refer to the official HotChocolate documentation: HotChocolate Operation Complexity