Skip to main content

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​

  1. 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.allocatedWarehouseCount and Customer.totalOrders cost 2 each, and the stock quantity fields cost between 0 and 7.

  2. Objects add 1 + their fields' complexity. Only selected fields and their dependencies are taken into the calculation.

  3. Lists multiply the cost of a list item (object) by the limit. In case there's no limit argument 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 a limit argument at all (like Shipment.lines), a default of 5 is assumed for the sake of complexity calculation.

  4. 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 list
    pageInfo {
    # information needed to fetch the next page
    hasNextPage
    endCursor
    }
    edges {
    # the list of results, one edge per item
    cursor # the position of the item, used for pagination
    node {
    # the item itself, here: a ProductVariant
    id
    name
    }
    }
    }
    }

    edges and node are only wrappers used for pagination, so they don't add any points on their own – only the fields you select inside node count. Apart from that, the connection is calculated like a list: its own cost of 1, plus the cost of everything selected inside it (including pageInfo), is multiplied by the limit from first or last. See the more complex example below.

  5. 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 declared limit. Orders and shipments can also be filtered by number with the same effect. This doesn't apply when the id (or number) filter is negated.

  6. 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:

    • translations on any object, and LanguageTranslation.fields,
    • attributes on any object, attribute elements, attributeTypes and AttributeType.elements,
    • Order.discountsApplied, appliedVouchers on order lines, allocations on 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.
  7. Order.lines is always counted as 5 items, so that orders with thousands of lines don't make the score explode.

  8. userErrors and userWarnings in mutation payloads are free (they add 0 points).

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:

  • states will return up to 10 objects, each object is worth 1 complexity point, because they have only scalars inside;
  • assignedToCountries will 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.
  • markets will 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 attributes and elements are always counted as a single item, so it makes a total of 2.
  • Each ProductVariant node is now worth 5 complexity points, neither edges nor node add complexity, pageInfo adds 1, and the connection object itself adds another 1. Multiplied by the limit from the last argument (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:

FieldDescriptionComplexity
freeToAllocateQuantityFast to compute, ideal for most use cases0 ✅
incomingQuantity, linkedIncomingQuantity, unlinkedIncomingQuantity, onDeliveryQuantityDepends on supplier module data3
physicalQuantity, allocatedQuantity, demandQuantity, availableNowQuantity, unshippedQuantityDepends on live order and shipment data4
availableQuantityComputed as physical + unlinked incoming7 ❗

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.