GraphQL Query Limits
Authors:
Fluent Commerce, Kirill Gaiduk
Changed on:
25 Sept 2024
Overview
The following guidelines and specifications apply to the entire schema, with any exceptions documented in the schema of the relevant entity.
Key points
- The GraphQL request size is limited to 2MB
- There is no validation on any of the GraphQL fields (except for enums)
- The GraphQL query complexity is limited and checked in accordance with the Query Complexity Calculation Algorithm (11,111 Total Complexity is Max)
General Guidelines
The request size is limited to
`2MB``2MB``HTTP 413 Request Entity Too Large`The number of attributes is not limited; however, it is important to note that storing many attributes is not considered best practice. While the underlying storage capacity of JSON allows for up to 255MB to be allocated, it is recommended to avoid excessive attributes as they can adversely impact performance and potentially result in errors.
Wherever there's no specific
`maxLength`There's no hard-coded validation on any of the GraphQL fields (except for
`enums`- OrderItemStatus
- FulfilmentItemStatus
- CardType
- LocationType
Data Retrieval
A key benefit of GraphQL is that users can send a single request to retrieve data from various sources.
While this is great for developer experience, it does add additional load on the server when an advanced GraphQL query could potentially create tens of thousands of queries to be executed by the backend. Fluent Commerce have therefore added query complexity checks to the GraphQL API. These checks ensure the API remains stable and maintains speed and efficiency.
GraphQL Query Complexity
For each GraphQL query, the platform calculates the complexity of the query based on the number of possible database operations. If the complexity is high, the platform will block the request and advise the user to query again with a lower complexity query. This prevents the server from attempting to execute superfluous requests that will most likely time out.
- Clients can supply a first or last argument on any connection. If the first and last are not provided, the default argument is the first 10.
- Values of first and last should be within 1 - 5,000. If the first or last is greater than 5,000, it will be reset to 5,000. This means that the page size limit has been increased from 100 to 5000.
- Individual requests with a complexity more than 11,111 will result in error code C10001E being displayed.
Query Complexity Calculation Algorithm
The general principle is that Total Complexity equals the number of queries to be executed.
Simple Query
Complexity Calculation
Complex Query
Complexity Calculation
Query with Weighting
Some GraphQL queries have an increased complexity weighting, determined by a
`@complexityCost`The key purpose of complexity weighting is to reduce the risk of an API timing out.
Inventory Quantity Aggregations
The complexity weighting of
`10``quantitiesAggregate`If the Inventory Quantity Aggregation is encountered within the supplied GraphQL query, then the resulting node complexity is multiplied by the weight (x10).
Complexity Calculation
More Examples
Here are several additional examples showing what Queries within the 11,111 Complexity could do:
Query Max number of records in a single request
1{
2 orders(first: 5000) {
3 edges {
4 node {
5 id
6 items {
7 edges {
8 node {
9 id
10 }
11 }
12 }
13 fufilments {
14 edges {
15 node {
16 id
17 }
18 }
19 }
20 }
21 }
22 }
23}Language: graphqlschema
Name: GraphQL Query Example
Description:
Get 5000 records in a single request.
Total Complexity: 10,001
Query with 5 level deep nesting
1{
2 orders(first: 10) {
3 edges {
4 node {
5 id
6 fulfilments {
7 edges {
8 node {
9 id
10 articles {
11 edges {
12 node {
13 id
14 consignmentArticles {
15 edges {
16 node {
17 article {
18 id
19 }
20 }
21 }
22 }
23 }
24 }
25 }
26 }
27 }
28 }
29 }
30 }
31 }
32}Language: graphqlschema
Name: GraphQL Query Example
Description:
Query with 5 level deep nesting.
Total Complexity: 11,111
Query details of an entity
1{
2 orderById(id: 1) {
3 id
4 fulfilmentChoice {
5 id
6 }
7 items {
8 edges {
9 node {
10 id
11 }
12 }
13 }
14 fulfilments {
15 edges {
16 node {
17 id
18 items {
19 edges {
20 node {
21 id
22 orderItem {
23 id
24 }
25 }
26 }
27 }
28 articles {
29 edges {
30 node {
31 id
32 items {
33 edges {
34 node {
35 id
36 }
37 }
38 }
39 consignmentArticles {
40 edges {
41 node {
42 article {
43 id
44 }
45 }
46 }
47 }
48 }
49 }
50 }
51 }
52 }
53 }
54 }
55 }Language: graphqlschema
Name: GraphQL Query Example
Description:
Retrieve details of an entity.
Total Complexity: 1,324
