Enable Stellate Caching Gradually
If you are interested in implementing Stellate GraphQL Edge Caching in your production environment, it may be beneficial to take an incremental approach. This allows you to gradually adopt Stellate Edge Caching as needed.
The following graphic illustrates, at a high-level, a gradual adoption path for the GraphQL caching services provided by Stellate. Each step in the path is described in further detail in the following sections and topics.
Set up Request Logging
Stellate offers different options for metrics logging. You can use one of the Stellate GraphQL plugins, use our fetch call example or set up Edge Caching. Edge Caching includes automatic metrics logging even if you have caching disabled. You can use one of these options to get started understanding whether Stellate GraphQL Edge Caching is beneficial for your company. To learn about getting started with Stellate metrics logging, read Get Started with Metrics.
Cache a single operation
If, after analyzing your metrics, you think that edge caching is the right path for your environment, you have the option of starting gradual adoption by caching a single operation.
The simplest way to send certain operations to Stellate is to check the operation name, and then switching the URL your GraphQL Client sends requests to depending on the operation. This might be also useful if you want to run an A/B test.
The following example shows how to route traffic to Stellate’s Edge Cache if either of the following two conditions are met:
- A
cmsfield is encountered - An
operationNamehas aSEGMENTATIONvalue of 10, where we only route 10% of our traffic to Stellate, and incrementally increase this value.
Under either condition, the traffic is routed to the Stellate edge cache. This example targets the Query.cms operation and has a 10% chance of sending it to Stellate.
Only sending certain operations via Stellate might have unintended side effects.
For example, Automatic Mutation Invalidation might not work as expected because certain mutations aren't passed through Stellate and adding types or fields to your caching rules might not enable caching because the queries you're trying to target aren't passed through Stellate.
import { HttpLink, split } from '@apollo/client'
import { visit, Kind } from 'graphql'
// The percentage of traffic we want to route to stellate when
// we only see a products field or a certain operationName
const SEGMENTATION = 10
const stellateUri = process.env.STELLATE_CDN_ENDPOINT
const originUri = process.env.ORIGIN_ENDPOINT // your non stellate API endpoint
const link = split(
(operation) => {
// We can base it on operationName
const operationName = getOperationName(operation.query)
let shouldCache = true
// Or we can just check whether the selection fully has .products
visit(operation.query, {
OperationDefinition: (node) => {
const hasNonCacheableEntry = node.selectionSet.selections.some(
(x) => x.kind === Kind.FIELD && x.name.value !== "cms"
)
if (hasNonCacheableEntry && shouldCache) {
shouldCache = false
}
},
})
if (!shouldCache) return false
const generated = Math.floor(Math.random() * 100)
const inSegmentation = generated <= SEGMENTATION
return inSegmentation
},
new HttpLink({ uri: stellateUri }), // if the above function returns true, this link is used
new HttpLink({ uri: originUri }), // if the above function returns false, this link is used
)
const client = new ApolloClient({
link, // pass the link instead of the uri field
// ... other options
})
Add client-side retries
Stellate has historically had 99.99% uptime but even so it’s important to plan for all eventualities. We suggest setting up client-side retries to your old URL as a fallback if Stellate caching fails. This essentially provides an alternative solution if Stellate caching fails. To implement client-side retries in this scenario, you can use the Apollo client. To do this:
- Navigate to Stellate documentation > Retries > Client-side retries
- Copy the code under Apollo Client.
- Integrate the code into your GraphQL project or environment.
Next Steps
Once you have achieved success with individual operations and you are prepared to fully adopt the Stellate Edge Caching proxy, you can learn more by reading either our Getting Started topics or diving into the Stellate GraphQL Edge Cache Quickstart guide. Remember, our customer success team is always available to support you throughout your journey.