Purging API

Now that our documents are stored in the cache and tagged accordingly let's look at what purging them would look like. Purging is the process of removing items from the cache. This happens automatically based on your maxAge and swr settings. But we also provide you with a GraphQL API, that allows you to remove items exactly when you need to remove them. And you have full control over which items are removed from the cache based on the criteria you define. This allows you to configure higher maxAge and swr values, and rely on manual (or automatic) invalidation of cached responses, instead of time-based expiration.

The Purging API is based on the schema of your application if we have access to that schema. However, some mutations are available in all cases.

❗️

The Purging API for any Stellate service requires users to authorize access via a stellate-token (or graphcdn-token) header. Therefore, you won't be able to run any of the mutations mentioned on this page against the SpaceX demo service we used in the examples. You can, however, run those mutations against any service you operate on Stellate. We would recommend creating a demo service for this.

Purge the complete cache

If you want to invalidate all cached responses from the cache, you can use the _purgeAll mutation, which would invalidate all documents tagged with the internal ID of your service.

In our example, any documents tagged with app:XYZ would get invalidated by the following mutation.

mutation {
    _purgeAll()
}

📘

There is a similar restriction on all other Purging API mutations. They only operate on documents tagged with the internal ID of your Stellate service. This is to make sure that you can not inadvertently modify the cache of a different service.

Purge a specific query by name

If you would rather only remove responses to a specific query, use the _purgeQuery mutation instead.

To remove all responses to the launchesPast queries used above, you would send the following mutation, which would then invalidate all documents tagged with query:launchesPast

mutation {
    _purgeQuery(queries: ["launchesPast"])
}

Purge a specific type

Similarly, if you want to purge any document containing entities of a specific type, you can use the _purgeType mutation.

The following mutation would remove all responses tagged type:Rocket, which would be all documents containing entities of type Rocket:

mutation {
    _purgeType(type: "Rocket")
}

Purge individual instances of a specific type

The Purging API also provides a set of mutations dependent on your GraphQL schema. Their naming follows the purge$TYPENAME convention, with $TYPENAME replaced with the actual types as defined in your schema.

In the case of the SpaceX API and our examples from above, we can e.g., purge all documents that refer to the Launch with ID 108 by calling the following mutation:

mutation {
    purgeLaunch(id: 108)
}

This would then look for any documents tagged with key:Launch:id:108 and remove them from the cache.

If you have multiple key fields defined, you could pass in a parameter other than ID that uniquely identifies a record. For example, to purge the Buttercup Moon launch we used earlier above, we would send the following mutation:

mutation {
    purgeLaunch(launch_name: "Buttercup Moon")
}

The Stellate Edge Cache would then invalidate any responses tagged with key:Launch:launch_name:Buttercup Moon.


What’s Next