Skip to content

Invalidation Overview

When the underlying data for your service changes there are a number of ways to ensure stale caches are removed from the edge servers. The key difference from traditional CDNs is that you do not invalidate specific API calls or URLs, you invalidate objects by their id or an aliased query tree.

Invalidating Objects

When an object in the underlying data is updated, FastQL can automatically find all caches where that object was used, as long as the results included the id and __typename fields.

There are two ways to invalidate objects when they're changed.

Mutations

If the mutation is sent through FastQL, FastQL can look at the id and __typename returned in the result of the mutation. This will cause all instances of that object to be automatically purged from the caches.

Example: Author Display Name Changes

See an example of how you might use automatic mutation invalidation when an author changes their display name that appears in many places in your app. Go to Example

Invalidate Object API

You can use the invalidate object API endpoint to invalidate all queries that return an object with a specified id and type.

Invalidating by Alias

GraphQL allows for a query operation to include multiple query trees that pull different datasets. These can be thought of as batched queries. An example of a query that pulls data for 3 separate sections of an article page:

query ArticlePage($articleID: ID!) {
  article: Article(id: $articleID) {
    ...
  }
  latestArticles: allArticles(orderBy: createdAt_DESC) {
    ...
  }
  featuredCategories: allCategories(filter {type: 'featured'}) {
    ...
  }
}

When sending queries, each tree in the top level of the query can be aliased like in the example above, with aliasName: before the query tree. These aliases can be used to invalidate the query across many requests. In the sample above, you could invalidate the latestArticles alias each time a new article is added to your site.

This invalidation can happen by adding a special header on the mutation sent through FastQL, or manually with the API.

Custom Header on Mutation

When creating a new object via a mutation you can tell FastQL to invalidate queries that contain specific aliases. The invalidation will only occur if the mutation is completed successfully.

To use this feature:

  • Add a custom header Cache-purge with a value of comma separated alias names
  • Add an alias to any query you'd like to invalidate

Example: Update Website when New Article is Added

See an example of how you might invalidate the homepage and "latest articles" widgets when a new article is added to your website or app. Go to Example

Invalidate Alias API

You can use the FastQL API with your API key to perform manual invalidations.

You can use the invalidate alias API endpoint to invalidate all queries that use the alias at the top level in the query.