Home / Basics / Highnote API
Request Complexity
Request complexity refers to the computational cost and resource usage of executing a GraphQL query. Because GraphQL lets clients request deeply nested and complex data structures in a single query, complexity must be managed to avoid overloading the server.
Common factors that increase complexity are operation, depth, and type. For example:
- Operation: Mutations are often more complex than queries due to data writes and consistency requirements.
- Depth: Deeply nested queries are more complex than shallow ones.
- Type: Objects with multiple fields or relationships to other objects are more complex than primitive types such as scalars.
Highnote manages the complexity of its GraphQL API with complexity scoring, rate limiting, and pagination.
Query operation types are scored as follows:
- Query: Query cost is based on the types and fields requested.
- Mutation: Mutations have a base cost of 10, plus any additional costs based on the types and fields requested.
Other types and patterns are scored as follows:
| Type / Pattern | Description | Cost |
|---|---|---|
| Object | Type with a defined set of fields (e.g., a User with id, name, email fields) | 1 point |
| Interface | Template type that defines required fields other types must implement. Uses maximum type complexity (where only the most expensive type requested is counted). | 1 point |
| Union | Type that can be one of several object types. Uses maximum type complexity. | 1 point |
| Scalar | Primitive type like String, Int, Boolean. Cost is accounted for in the object it belongs to. | 0 points |
| Enum | User-defined type with a fixed set of allowed values. Cost is accounted for in the object it belongs to. | 0 points |
| Connection | Pattern for pagination, typically implemented as an object type with edges and nodes. Defines how different types of data are connected and how they can be queried. | 2 points + number of objects requested |
Note: The fields cursor and pageInfo are intrinsic to the connection pattern and have no separate complexity cost.
The following example demonstrates a simple request complexity calculation:
- Example 1
- Request Calculation
The following example demonstrates a more complex request complexity calculation that includes nested connection objects to illustrate how pagination cost can multiply:
- Example 2
- Request Calculation
Every Highnote GraphQL API response includes the request cost under the extensions field. We recommend that you test the cost of your queries in the API Explorer.
The following example represents a request cost response in an API request that is not rate-limited:
- Query Cost Response