Content Delivery API > Complexity

Each query hitting our Content Delivery API has a complexity cost based on

• which type of field is present

• how many fields are present

• how many filters are present

• how many sorting parameters are present

• the page size

Limits

Each DatoCMS plan comes with a maximum allowed complexity cost which is 10,000,000 by default. Take a look at the "Plan and usage" section of your project in the Account dashboard to understand which is your complexity limit.

The Content Delivery API sets the X-Complexity header in the response to let you know the calculated complexity cost for your submitted query and the X-Max-Complexity header containing your current plan complexity limit.

If the query complexity cost above your plan limit you'll get an error from the Content Delivery API:

{
  "errors": [
    {
      "message": "Query has complexity of xxx, which exceeds max complexity of yyy"
    }
  ]
}

Base costs

Unless specified otherwise, each requested GraphQL field has a cost of 1.

Each filter argument has a cost of 250, except for deep filtering arguments.

Each sorting parameter has a cost of 250.

To calculate the pagination cost, multiply the page size by the inner fields' cost. By default, the page size is 20 but you can override it using the first argument.

Model root fields

Collection field

Root fields like allArtists have a base cost of 100. To this, the cost of filters, the cost of sorting, and the cost of pagination must be added.

The following query has a cost of 140: 100 (base) + 20 (implicit page size) x 2 (inner fields' cost)

query { # it returns at max 20 records by default
  allArtists { # 100
    id # 1
    name # 1
  }
}

The following query has a cost of 1,175: 100 (base) + 750 (filtering) + 250 (sorting) + 25 (page size) x 3 (inner fields' cost)

1
query {
2
  allArtists( # 100
3
    filter: {
4
      birth: {gt: "1990-01-01", lt: "2010-01-01"}, # 250 x 2 => 500
5
      country: {eq: "DE"} # 250
6
    },
7
    orderBy: [name_ASC], # 250
8
    first: 25 # explicit page size
9
  ) {
10
    id # 1
11
    name # 1
12
    age # 1
13
  }
14
}

Collection meta field

Root fields like _allArtistsMeta have a base cost of 1,000. To this, the cost of filters and the inner field's cost must be added.

The following query has a cost of 1,251: 1,000 (base) + 250 (filtering) + 1 (inner fields' cost)

query {
  _allArtistsMeta( # 1,000
    filter: { country: {eq: "NL"} } # 250
  ) {
    count # 1
  }
}

Single record field

Root fields like artist have a base cost of 50. To this, the cost of filters, the cost of sorting, and the inner fields' cost must be added.

The following query has a complexity cost of 301: 50 (base) + 250 (filtering) + 1 (inner fields' cost)

query {
  artist( # 50
    filter: { id: {eq: "123"} } # 250
  ) {
    name # 1
  }
}

Single instance record field

Root fields about single-instance records have a base cost of 25. To this, the inner field's cost must be added.

The following query has a cost of 27: 25 (base) + 2 (inner fields' cost)

query {
  contactPage { # 25
    phoneNumber # 1
    emailAddress # 1
  }
}

Inverse relationships fields

Fields like _allReferencingMovies can be used once activated the inverse relationships feature for the model. They have a base cost of 100. To this, the cost of filters, the cost of sorting, and the cost of pagination must be added.

The following section has a cost of 1,110: 100 (base) + 500 (filtering) + 500 (sorting) + 5 (page size) x 2 (inner fields' cost)

1
...
2
    _allReferencingMovies( # 100
3
      through: {
4
        fields: {anyIn: [movie_artist]}, # 250
5
        locales: {anyIn: en} # 250
6
      },
7
      orderBy: [title_ASC, _createdAt_DESC], # 500,
8
      first: 5 # explicit page size
9
    ) {
10
      id  # 1
11
      title # 1
12
    }
13
...

Fields like _allReferencingMoviesMeta have a base cost of 1,000. To this, the cost of filters and the inner fields' cost must be added.

The following section has a cost of 1,001.

...
    _allReferencingMoviesMeta { # 1,000
      count # 1
    }
...

Model fields

The following GraphQL fields differ from the base cost (1):

• Single asset field: 5

• Asset gallery field: 5 x inner fields' cost

• Multiple-paragraph text, when rendering Markdown in HTML: 5

• JSON field: 5

• Single link field: 10

• Multiple links field: 5 x inner fields' cost

• Modular content field: 5 x inner fields' cost

• Structured text field

  • value: 10

  • blocks: 5 x inner fields' cost

  • links: 5 x inner fields' cost

• children field (available in tree collections): 5 x inner fields' cost

• parent field (available in tree collections): 25

• Localized field

  • value: number of environment's locales x inner fields' cost

• SEO field

  • image: 5

• _seoMetaTags: 5

The following query has a cost of 351, composed by:

• 50 (base cost of single record field)

• 250 (filtering)

• 5 + 1 + 5 (photo field)

• 10 + 5 x 1 + 5 x 2 (content field)

• 5 x 3 (movies field)

1
query {
2
  artist( # 50
3
    filter: { id: {eq: "123"} } # 250
4
  ) {
5
    photo { #single asset field: 5
6
      url # 1
7
      blurUpThumb # 5
8
    }
9
    content { # structured text field
10
      value # 10
11
      links { # 5 x inner fields' cost
12
        id # 1
13
      }
14
      blocks { # 5 x inner fields' cost
15
        id # 1
16
        text # 1
17
      }
18
    }
19
    movies { # multiple links field: 5 x inner fields' cost
20
      id # 1
21
      title # 1
22
      releaseDate # 1
23
    }
24
  }

Unions

A GraphQL union complexity is the max complexity between all of the possible types.

The modular content field content has a complexity cost of 10: 5 x 2

1
query {
2
  artist(filter: { id: { eq: "123" }}) {
3
    name
4
    content { # 5 x max possible union's cost
5
      ... on MovieRecord {
6
        title # 1
7
      }
8
      ... on TvSerieRecord {
9
        title # 1
10
        channel # 1
11
      }
12
    }
13
  }
14
}

Deep Filtering

Normally, each filter argument has a cost of 250, but when using deep filtering an additional cost of 1,000,000 is added for each type of block model defined in the filter.

The following query has a cost of 2,000,890: 100 (base) + 2,000,750 (filtering) + 20 (implicit page size) x 2 (inner fields' cost)

1
query {
2
  allBlogPosts( # 100
3
    filter: {
4
      content: {
5
        any: {
6
          product: { # 1,000,000
7
            name: {
8
              eq: "T-Shirt" # 250
9
            },
10
            price: {
11
              gt: 30 # 250
12
            }
13
          }
14
          cta: { # 1,000,000
15
            title: {
16
              isPresent: true # 250
17
            }
18
          }
19
        }
20
      }
21
    }
22
  ) {
23
    id # 1
24
    title # 1
25
  }
26
}

Upload root fields

Collection field

Root field allUploads has a base cost of 100. To this, the cost of filters, the cost of sorting, and the cost of pagination must be added.

The following query has a cost of 801: 100 (base) + 250 (filtering) + 250 (sorting) + 30 (page size) x 7 (inner fields' cost)

1
query {
2
  allUploads( # 100
3
    filter: {format: {eq: "jpg"}}, # 250
4
    orderBy: [size_DESC], # 250
5
    first: 30 # explicit page size
6
  ) {
7
    id # 1
8
    url # 1
9
    blurUpThumb # 5
10
  }
11
}

Collection meta field

Root field _allUploadsMeta has a base cost of 1,000. To this, the cost of filters and the inner fields' cost must be added.

The following query has a cost of 1,251: 1,000 (base) + 250 (filtering) + 1 (inner fields' cost)

query {
  _allUploadsMeta( # 1,000
    filter: {format: {eq: "jpg"}} # 250
  ) {
    count # 1
  }
}

Single upload field

Root field upload has a base cost of 50. To this, the cost of filters, the cost of sorting, and the inner fields' cost must be added.

The following query has a complexity cost of 308: 50 (base) + 250 (filtering) + 8 (inner fields' cost)

1
query {
2
  upload( # 50
3
    filter: {id: {eq: "123"}} # 250
4
  ) {
5
    url #1
6
    title #1
7
    blurUpThumb # 5
8
    blurhash #1
9
  }
10
}

Upload fields

The following GraphQL fields differ from the base cost (1):

• blurUpThumb: 5

Site field

Root field _site has a base cost of 10. To this, the inner fields' cost must be added.

The following query has a cost of 13.

query {
  _site { # 10
    globalSeo { # 1
      siteName # 1
      titleSuffix # 1
    }
  }
}