Query complexity calculation
Query complexity calculation
The Integration API calculates query complexity to prevent system abuse. The score is based on the number and type of requested fields and their associated costs. This complexity score helps enforce rate limits.
The algorithm is based on a GitHub document, with some modifications.
Checking the complexity of your query
Every response contains the complexity score of the executed operation in the extensions section:
"extensions": {
"complexity": 1550
}
Use it to audit your most frequent and most complex queries, and to spot opportunities to optimize them.
Details
-
Scalars usually don't add any complexity score. Some of them are marked as expensive, because they require additional computation on the backend, and then they add their own cost. For example,
Order.allocatedWarehouseCountandCustomer.totalOrderscost2each, and the stock quantity fields cost between0and7. -
Objects add
1+ their fields' complexity. Only selected fields and their dependencies are taken into the calculation. -
Lists multiply the cost of a list item (object) by the
limit. In case there's nolimitargument passed, the default value of the argument from the schema is used. If the field doesn't have a default limit, or doesn't accept alimitargument at all (likeShipment.lines), a default of5is assumed for the sake of complexity calculation. -
Connections are lists that support cursor-based pagination, for example
productVariantConnection. Instead of returning the items directly, a connection wraps them in a few extra layers:{productVariantConnection(first: 100) {# the connection, the limit is set by `first` or `last`totalCount # information about the whole listpageInfo {# information needed to fetch the next pagehasNextPageendCursor}edges {# the list of results, one edge per itemcursor # the position of the item, used for paginationnode {# the item itself, here: a ProductVariantidname}}}}edgesandnodeare only wrappers used for pagination, so they don't add any points on their own – only the fields you select insidenodecount. Apart from that, the connection is calculated like a list: its own cost of1, plus the cost of everything selected inside it (includingpageInfo), is multiplied by the limit fromfirstorlast. See the more complex example below. -
Lists and connections filtered by a list of specific IDs, for example
deliveryWindows(limit: 200, where: { id: [86, 99, 120, 99] }), are multiplied by the number of unique IDs (here:3), not by the declaredlimit. Orders and shipments can also be filtered bynumberwith the same effect. This doesn't apply when theid(ornumber) filter is negated. -
Some lists, which are fetched from the database in one go, or which usually contain just one or zero items, are always counted as a single item, regardless of their actual size:
translationson any object, andLanguageTranslation.fields,attributeson any object, attributeelements,attributeTypesandAttributeType.elements,Order.discountsApplied,appliedVoucherson order lines,allocationson order and shipment lines,ShipmentLine.invoiceLines,- tax breakdowns and applied tax rules on orders, lines and totals,
TaxRule.taxClasses, - size chart and measurement chart labels and values,
Customer.newsletterSubscriptions.
-
Order.linesis always counted as5items, so that orders with thousands of lines don't make the score explode. -
userErrorsanduserWarningsin mutation payloads are free (they add0points).
Simple example
Let's say we have a query like this:
{
markets(limit: 50) {
# 50 * (1 + 110)
id
name
assignedToCountries(limit: 10) {
# 10 * (1 + 10)
code
continent
name
states(limit: 10) {
# 10 * 1
id
}
}
}
}
Up to 50 markets can be returned, each one with a list of countries (limited to 10), each potential country with up to 10 states.
Now, counting from the deepest level:
stateswill return up to 10 objects, each object is worth 1 complexity point, because they have only scalars inside;assignedToCountrieswill return up to 10 countries, each country object worth 1 point for being an object, plus the child complexity of 10, for a total of 110 points.marketswill now be worth 1 + 110 per object, which multiplied by the limit makes a total of 5550 points.
More complex example
{
productVariantConnection(last: 100) {
# 100 * (1 + 1 + 5)
totalCount
pageInfo {
# 1
hasPreviousPage
startCursor
}
edges {
# no additional cost, it's part of the connection
cursor
node {
# no additional cost, only its fields count: 3 + 2
id
...cost # 3
...attributes @include(if: true) # 2
}
}
}
}
fragment cost on ProductVariant {
unitCost {
# 1 + 1 + 1
currency {
# 1
code
}
formattedValue
converted {
# 1
formattedValue
}
conversionDate
conversionRate
}
}
fragment attributes on ObjectWithAttributes {
attributes {
# 1 * (1 + 1), always counted as a single item
description
... on MappedAttribute {
id
}
elements {
# 1 * 1, always counted as a single item
key
description
... on AttributeStringElement {
value
}
}
}
}
Now the calculations starting from the fragments:
- The cost fragment consists of one object with another two objects nested in it, so its complexity score is 3.
- The attributes fragment returns a list with a list embedded in it. Both
attributesandelementsare always counted as a single item, so it makes a total of 2. - Each
ProductVariantnode is now worth 5 complexity points, neitheredgesnornodeadd complexity,pageInfoadds 1, and the connection object itself adds another 1. Multiplied by the limit from thelastargument (100), the total complexity becomes 700.
Expensive scalar example
{
orders(limit: 100) {
# 100 * (1 + 2 + 3)
number
allocatedWarehouseCount # expensive = 2
customer {
# 1 + 2
email
totalOrders # expensive = 2
}
}
}
Both allocatedWarehouseCount and totalOrders are marked as "expensive", because they are calculated from other data on every request. Other than that, the calculation is pretty basic: each customer object gets a score of 1 + 2, and each order object gets 1 + 2, plus the customer's 3. There are up to 100 orders returned, for a total of 600.
Stock field costs
The stock quantity fields (on both Stock and StockTotals) have costs reflecting how expensive they are to compute on the backend:
| Field | Description | Complexity |
|---|---|---|
freeToAllocateQuantity | Fast to compute, ideal for most use cases | 0 ✅ |
incomingQuantity, linkedIncomingQuantity, unlinkedIncomingQuantity, onDeliveryQuantity | Depends on supplier module data | 3 |
physicalQuantity, allocatedQuantity, demandQuantity, availableNowQuantity, unshippedQuantity | Depends on live order and shipment data | 4 |
availableQuantity | Computed as physical + unlinked incoming | 7 ❗ |
See the documentation for details on how these fields are calculated.
For most integrations, you only need freeToAllocateQuantity – it's free in terms of complexity and reflects what's available to sell. Use higher-cost fields only when necessary, and be aware they contribute significantly more to your query budget. See Optimising stock queries.
Individual query complexity limit
The maximum complexity of any individual query to the Integration API is limited to 150 000 complexity points. A query exceeding it is rejected with an error like Max query complexity should be 150000 but got 163200.
This limit applies on top of the query complexity rate limits, which cap the aggregated complexity of all queries in a time period.
History of changes
The current rules for interface lists, stock fields, the lists counted as a single item, ID filters and the default limit of 5 were introduced in Integration API v1.54.0, together with raising the individual query limit from 100 000 to 150 000 points. See the changelog for details.