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.

Diagram presenting gradual adoption path for GraphQL Caching

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 cms field is encountered
  • An operationName has a SEGMENTATION value 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.

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 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:

  1. Navigate to Stellate documentation > Retries > Client-side retries
  2. Copy the code under Apollo Client.
  3. 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.

Discover more

About GraphQL Metrics

Build a Metrics Logging Call

Metrics Plugins

Use the Edge Proxy for GraphQL Metrics