GraphQL Cost Directives Specification


GraphQL cost analysis is crucial to enabling your server to enforce threat protection, rate limiting and monetization. If you spend a lot of your time on GraphQL then you already know that cost analysis is important. If you’re used to REST and you don’t understand why cost analysis is essential for GraphQL, then you’re not alone and hopefully this short video can help.

To proper analyze a request, its definition is not enough. The provider needs to supply some guidance on top of the GraphQL schema to better assess the cost of the query. We propose the use of directives to decorate the schema. This specification defines a set of GraphQL Specification and Description Language (SDL) directives that advertise enough information to calculate the cost of executing GraphQL queries.


Here is a draft of the specification itself.

Related Videos

This 3 minute video introduces the three methods of GraphQL cost analysis that are explained in section 6.1.

If a picture is worth a thousand words, then how about a 4-minute step-by-step walkthrough of GraphQL Static Query Analysis as explained in section 6.1.1.

This is a longer presentation from API Days Interface 2021 explaining why we need the spec, and how it works.


This specification is implemented in IBM API Connect v10.