)<\/strong>: This represents the specific node (e.g., a post) that was resolved in the query. Changes to this node will invalidate the cache for this query.<\/li>\n<\/ul>\n\n\n\nIf a purge event for one of those tags is triggered, the document will be tagged with these keys and purged (deleted) from the cache.<\/p>\n\n\n\n
Understanding Cache Invalidation with WPGraphQL Smart Cache<\/h2>\n\n\n\n WPGraphQL Smart Cache optimizes caching by sending the keys in the headers, but the caching client (e.g., Varnish or Litespeed) needs to use those keys to tag the cache. WPGraphQL Smart Cache itself does not tag the cached document; it provides the caching client info (the keys) to tag the cached document with. A supported host like WP engine works with WPGraphQL Smart Cache out of the box.<\/p>\n\n\n\n
Let\u2019s discuss how invalidation works:<\/p>\n\n\n\n
WPGraphQL Smart Cache listens to various events in WordPress, such as publishing, updating, or deleting content, and triggers cache invalidation (or “purge”) based on these events.<\/p>\n\n\n\n
Detailed Key Breakdown:<\/p>\n\n\n\n
Publish Events (purge('list:$type_name'))<\/code>: When a new post or content type is published, the cache for the entire list associated with that content type (e.g., all posts) is purged. This ensures that any queries fetching this list will be up-to-date.<\/p>\n\n\n\n Update Events (purge('$nodeId'))<\/code>: When an existing post or content type is updated, the cache for that specific node (e.g., a single post) is purged. This allows the updated content to be fetched without affecting the entire list.<\/p>\n\n\n\n Delete Events (purge('$nodeId'))<\/code>: Similarly, when a post or content type is deleted, the cache for that specific node is purged, ensuring that the deleted content is no longer served from the cache.<\/p>\n\n\n\nWhy This Matters:<\/p>\n\n\n\n
These targeted cache invalidations help maintain the balance between performance and data freshness. By only purging the cache when necessary and only for the relevant data, WPGraphQL Smart Cache ensures that users receive up-to-date content without unnecessary cache purges, which can negatively impact performance.<\/p>\n\n\n\n
This invalidation strategy is crucial for optimizing the performance of headless WordPress setups using WPGraphQL, especially in dynamic environments where content changes frequently.<\/p>\n\n\n\n
Now that we’ve explored how cached documents are tagged and how cache invalidation works in WPGraphQL Smart Cache, let’s see how these concepts interact.<\/p>\n\n\n\n
When a GraphQL query is executed, specific cache keys (tags) are associated with the cached response. These tags correspond to the data queried, such as posts, categories, or specific node IDs. The cache invalidation strategy then ensures that when relevant data changes occur in WordPress, the associated cached documents are purged based on these tags.<\/p>\n\n\n\n
Example: Invalidation Scenarios for a GetPosts Query<\/p>\n\n\n\n
\nPublishing a New Post (purge('list:post'))<\/code><\/strong>:\n\nWhen a new post is published, the entire list of posts in the cache (tagged with list:post) is invalidated. This ensures that the new post will appear in any subsequent queries that fetch this list.<\/li>\n<\/ul>\n<\/li>\n\n\n\n Updating or Deleting a Specific Node (purge('$nodeId'))<\/code><\/strong>:\n\nIf the “Hello World” post (with the ID cG9zdDox) is updated or deleted, the cache for that specific node is purged. This allows the updated or deleted content to be accurately reflected in any future queries.<\/li>\n<\/ul>\n<\/li>\n\n\n\n Manually Purging Cache (purge('graphql:Query'))<\/code><\/strong>:\n\nClicking “Purge Cache” in GraphQL > Settings > Cache<\/strong> page triggers a manual cache purge for all queries. This can be useful when you want to ensure that all cached data is refreshed, regardless of specific events.<\/li>\n<\/ul>\n<\/li>\n\n\n\nOperation Name or Query Hash-Based Purge<\/strong>:\n\nCustom purge events can be manually triggered based on the operation name (e.g., GetPosts<\/code>) or the hash of the query. This level of control allows you to finely tune when and how caches are invalidated.<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\nThese strategies work together to ensure that the cache is only invalidated when necessary, providing up-to-date data without unnecessary performance overhead. For instance, when the “Hello World”<\/em> post is updated, it’s reasonable to expect that the cache for the GetPosts query should be purged so that any queries return the most current data. This fine-grained control over cache invalidation ensures that your headless WordPress site remains performant while delivering fresh content.<\/p>\n\n\n\nWhy Would You Need to Customize WPGraphQL Cache Keys?<\/h2>\n\n\n\n In some scenarios, the default caching behavior might be too broad, leading to frequent cache invalidations. This is especially true for more complex queries. <\/p>\n\n\n\n
For instance, if your query includes categories and tags, any update to these taxonomies will invalidate the cache, even if those changes don’t affect the specific posts you’re querying. Customizing cache keys allows you to fine-tune this behavior, ensuring that only relevant updates trigger cache invalidation, thereby improving performance.<\/p>\n\n\n\n
For example, consider the following query:<\/p>\n\n\n
{\n<\/span><\/span> posts {\n<\/span><\/span> nodes {\n<\/span><\/span> id\n<\/span><\/span> title\n<\/span><\/span> tags {\n<\/span><\/span> nodes {\n<\/span><\/span> id\n<\/span><\/span> name\n<\/span><\/span> }\n<\/span><\/span> }\n<\/span><\/span> }\n<\/span><\/span> }\n<\/span><\/span> categories {\n<\/span><\/span> nodes {\n<\/span><\/span> id\n<\/span><\/span> name\n<\/span><\/span> }\n<\/span><\/span> }\n<\/span><\/span> tags {\n<\/span><\/span> nodes {\n<\/span><\/span> id\n<\/span><\/span> name\n<\/span><\/span> }\n<\/span><\/span> }\n<\/span><\/span>}\n<\/span><\/span><\/code><\/span><\/pre>\n\n\nThis query retrieves a list of posts, along with all categories and tags. When this query is executed, the response includes the posts, categories, and tags that match the query as shown here:<\/p>\n\n\n\nThe X-GraphQL-Keys header shows that the cached document is tagged with list:post<\/code>, list:category<\/code>, and list:tag<\/code>. This tagging means that the cache will be invalidated whenever there\u2019s a change in any of these entities\u2014whether it’s a new post, category, or tag.<\/p>\n\n\n\nWhile this behavior ensures that your cache is up-to-date, it can lead to excessive cache invalidation. For instance, if a new tag is created and assigned to a post not included in this query, it will still trigger a purge('list:tag'<\/code>), invalidating the cache for this query. <\/p>\n\n\n\nThis means the cache could be cleared more often than you want for your specific use case, which could negatively impact performance.<\/p>\n\n\n\n
Just A Note<\/h3>\n\n\n\n Just a note, consider this query from the original article<\/a> on this subject:<\/p>\n\n\nquery GetPostsWithCategoriesAndTags {\n<\/span><\/span> posts {\n<\/span><\/span> nodes {\n<\/span><\/span> id\n<\/span><\/span> title\n<\/span><\/span> categories {\n<\/span><\/span> nodes {\n<\/span><\/span> id\n<\/span><\/span> name\n<\/span><\/span> }\n<\/span><\/span> }\n<\/span><\/span> tags {\n<\/span><\/span> nodes {\n<\/span><\/span> id\n<\/span><\/span> name\n<\/span><\/span> }\n<\/span><\/span> }\n<\/span><\/span> }\n<\/span><\/span> }\n<\/span><\/span>}\n<\/span><\/span>\n<\/span><\/span><\/code><\/span><\/pre>\n\n\nThe WPGraphQL team changed things to only track list: types<\/code> from the root. So, if you run this query, your list of categories won\u2019t be tracked because it is not at the root.<\/p>\n\n\n\nThe Problem<\/h3>\n\n\n\n The problem is that the list:category<\/code> and list:tag<\/code> keys could cause this document to be purged more frequently than you might like. WPGraphQL tracks precisely, but it doesn’t know your specific intention and what you care about.<\/p>\n\n\n\nFor example, you might simply not care if this particular query is “fresh” when terms change. OR you might ONLY care for this query to be fresh when terms change. <\/p>\n\n\n\n
WPGraphQL doesn’t know the intent of the query, only what the query is.<\/p>\n\n\n\n
Fortunately, you can customize the cache keys to better suit your specific needs, reducing unnecessary cache invalidations and improving performance.<\/p>\n\n\n\n
Customizing Cache Keys<\/h2>\n\n\n\n By customizing the cache keys, you can ensure that the cache is only invalidated when changes you believe are relevant to your use case occur. This involves fine-tuning the tags associated with your queries, allowing you to maintain optimal performance without sacrificing data accuracy.<\/p>\n\n\n\n
Let\u2019s do this by navigating to our WP admin and modifying the functions.php<\/code> file. Go to Appearance> Theme File Editor<\/strong>. Select the functions.php<\/code> file from your active theme.<\/p>\n\n\n\nInsert this code snippet at the bottom of your