Cache configuration

GraphCDN gives you fine-grained per-type or even per-field control over your cache behaviour for every single query that is sent through your service with cache rules.

Basics

A basic rule to cache all queries that contain any Users could look like this:

rules:
	- description: "Cache users"
		maxAge: 900
		swr: 900
		scope: AUTHENTICATED
		types:
			User: true

A rule applies to all queries that contain the rule's types or fields. If multiple rules apply to the same query, GraphCDN will use the minimum maxAge, the minimum swr and combine all scopes to cache the query result.

types (required)

The rule will apply its cache configuration to any query that contains the types or fields mentioned in the types property.

You can target both types as well as specific fields of types:

		types:
			# The rule will apply to any query that contains any User
			User: true
			# The rule will apply to any query that contains Post.comments
			Post:
				comments: true
			# The rule will apply to any { drafts } query (assuming the "Query" type is the root schema query type)
			Query:
				drafts: true

maxAge (seconds, optional)

The maxAge parameter configures how long query results that match the rule types should be cached, in seconds. If multiple rules apply to the same query, the minimum maxAge will be used for the entire query result.

swr (stale-while-revalidate, seconds, optional)

The "swr" (stale-while-revalidate) property configures how long stale query results that match the rule types should be served while fresh data is already being refetched in the background. We recommend always setting swr as it makes for a nicer user experience.

For example, if you set the maxAge of a query to 60s and swr to 300s, the cached results will be served for 60 seconds.

The first request that arrives after 60s (but before 60 + 300 = 360s) will trigger a refetch ("revalidate") of the request in the background. However, the stale data from the cache will still be served to all other users until the data has finished refetching for up to 300s.

scope (string, optional)

Which scope to apply to query results that match the rule types. See the ‣ documentation for more information on setting up scopes

description (string, optional)

Describe the purpose of the rule in plain english.

FAQ

How do I cache everything?

To apply a rule to everything, target the root Query type:

rules:
	- description: "Cache everything"
		maxAge: 900
		swr: 900
		types:
			Query: true

Since the Query type is included in every single query, this rule will apply to all queries. Note that creating a rule that targets the Query type sets a maximum maxAge and swr for all rules! Since GraphCDN always uses the minimum maxAge and swr of all the rules that apply to a single query, and this rule applies to all queries, you can never increase the maxAge and swr of any cached query result to more than 900 (in this example).

What happens when multiple rules apply to the same query?

GraphCDN will use the minimum maxAge, the minimum swr and combine all scopes to cache the query result.

For example, imagine you have these two rules defined:

rules:
	- description: "Cache posts publicly"
		maxAge: 900
		swr: 900
		types:
			Posts: true
  - description: "Cache user data privately"
		maxAge: 450
		swr: 1000
    scope: AUTHENTICATED
		types:
			User: true

And send a query that contains a User and a Post, which means both rules apply:

{
  user(id: "...") {
		id
    posts(first: 10) {
      id
    }
  }
}

Then the query result would be cached with a 450s maxAge (the minimum of both rules), a 900s swr (the minimum of both rules) as well as with a scope of AUTHENTICATED.