Fluent Commerce Logo
Docs
Sign In

GraphQL Query Limits

Essential knowledge

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 .

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`. Requests over `2MB` will return `HTTP 413 Request Entity Too Large` response.

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` of a String defined, 255 characters is the default.

There's no hard-coded validation on any of the fields (except for `enums`). For example, these include (not a comprehensive list):

  • OrderItemStatus
  • FulfilmentItemStatus
  • CardType
  • LocationType

Data Retrieval

A key benefit of 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 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 API. These checks ensure the API remains stable and maintains speed and efficiency.

GraphQL Query Complexity

For each 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

No alt provided
Complexity Calculation
No alt provided

Complex Query

No alt provided
Complexity Calculation
No alt provided

Query with Weighting

Some queries have an increased complexity weighting, determined by a `@complexityCost` directive in the schema. This directive assigns a weighting factor to specific queries, which multiplies the query's complexity result by the specified value.

The key purpose of complexity weighting is to reduce the risk of an API timing out.

Inventory Quantity Aggregations

The complexity weighting of `10` is used for the Quantity Aggregation queries (`quantitiesAggregate`).

If the Quantity Aggregation is encountered within the supplied query, then the resulting node complexity is multiplied by the weight (x10).

No alt provided
Complexity Calculation
No alt provided

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}
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}
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  }
Fluent Commerce

Fluent Commerce

Contributors:
Kirill Gaiduk