Configure Partial Query Caching

Stellate Partial Query Caching is a new and innovative implementation of optimally caching GraphQL queries. It does this by splitting any given query into separate cache entries, each with its own caching characteristics (maxAge, swr, and scopes). Adopting Stellate Partial Query Caching helps you increase your cache hit rate, and improve the performance and stability of your GraphQL APIs. For more details about these advantages, read the Partial Query Caching topic.

Before you begin

Before you start using the Stellate Partial Query Caching, you need to:

• Have a Stellate service or create one that uses GraphQL Edge Caching. Read the “GraphQL Edge Cache Quickstart” for more guidance.
• Be familiar with the Partial Query Caching concepts. Read “What is Partial Query Caching” before you begin.
• Push your GraphQL schema to Stellate. While you can enable Partial Query Caching without pushing your schema, no query splits can occur without schema information. To push your schema, either make sure to enable introspection in your origin server or define the schema property in your Stellate configuration file. For information on the latter, see “Stellate Configuration”.
• Make sure any querys returning lists include ID attributes. Stellate recognizes id and _id by default, but you can configure additional fields via Key Fields. IDs are required to properly recombine lists from different queries. If IDs are not present when querying a list, Stellate will fall back to document caching for this specific query.

1. Enable Partial Query Caching in the config

To enable Partial Query Caching in your environment:

1. Login to your Stellate account.
2. Navigate to and select your Service.
3. Click the Services > Config tab to go to the Config editor.
4. In the Stellate Config File editor, add the partialQueryCaching property. (Do not yet submit the config change!)

import { Config } from 'stellate'
 
const config: Config = {
  config: {
    partialQueryCaching: { enabled: true },
  },
}
export default config

2. Review the impact of enabling Partial Query Caching

After altering the config file in the previous step, click the ”Review” button. After that, click the ”Review Cache Rules” button in the modal that opened. You will see the following screen that shows you which queries are affected by enabling Partial Query Caching.

In particular you can gather the following information from the different sections:

• Newly Cacheable - These queries have not been cached until now, most likely because they contain fields that are declared as being non-cacheable. By enabling Partial Query Caching, the parts of these queries that contain cacheable data will now be cached.
• No Longer Cacheable - These queries have been cached previously, but will no longer be cached when applying the config changes. Note that this section will be empty if the only config change is enabling Partial Query Caching, since every query that is cacheable with Document Caching will also be cacheable with Partial Query Caching.
• Updated Cache Configuration - These queries have already been cached before, however, by enabling Partial Query Caching these queries are now split into multiple cache entries, where each entry is cached optimally.

You can click on each of the queries in this screen, which will show you a preview of how the query will be split up into cache entries when Partial Query Caching is enabled.

3. Adjust your Cache Rules

While reviewing the changes induced by enabling Partial Query Caching in the previous step, you might find changes that are undesired. Common scenarios and their solutions are:

• A type or field would now be cached that is non-cacheable. This can be solved by adding the type or field to the nonCacheable config property.
• A type or field is missing a scope. This can be solved by either adapting existing cache rules or adding new ones that apply the scope to the type or field.

In case you spot any problems in the review phase, go back to the config editor and apply the necessary changes. Then go back to Step 2.

4. Apply Config Changes

If you reviewed all changes that will happen to your cache and there are no issues, click the ”Apply Config” button on the review modal. This will push a new config version which enabled Partial Query Caching for all requests sent to your Stellate service.

Alternative Option to Enable Partial Query Caching

You have the option of using a slightly different method for enabling Partial Query Caching if you prefer to selectively enable the feature for some requests rather than having it enabled for all requests.

Instead of adding the partialQueryCaching config property, you can add the following HTTP header to enable Partial Query Caching for an individual request.

Example: HTTP header value set to true

stellate-partial-query-caching: true

5. Validate your caching config using GraphQL Metrics

After enabling Partial Query Caching, you can use the Stellate GraphQL metrics to gain insights in the performance of your cache. You have multiple options to validate that your Partial Query Cache configuration is successful and correct.

Validate an individual request

To validate that your Partial Query Cache configuration is successful, you can run a single request:

1. Navigate to the Service that you configured with Partial Query Caching.
2. Click on API Playground and send a query request to the origin server. After the response comes back, the API Playground shows a button Cache Entries on the bottom right.
3. In the Cache Entries window check the details on how your query is split into different cache entries:
   • Click the Full Query tab to see the full query that was that was sent to your Stellate service.
   • Check the Cache Entries tab to see how the full query was split up into different cache entries.. The UI shows how long the queries were cached and whether the Cache Entry was a HIT, MISS, or PASS.
   • Click the Sent Query tab to see the query that was sent to the origin server. (Note that this tab will not exist when all cache entries have been a HIT, as no query needed to be sent to the origin in that case.)

Validate from the Request List

An alternate way to validate that your Partial Query Cache configuration is successful, is to look up details for a single request that was sent to your Stellate service:

1. Navigate to the Service that you configured with Partial Query Caching.
2. Click Requests, to see a list of requests that were sent to your Stellate service. Look out in particular for requests with a HIT or PARTIAL cache state.
3. Click on one of the request entries to open a detail page that includes a UI showing the Cache Entries on the right side of the view.
   • Note that this UI only shows the Cache Entries if the query has been split into more than one entry, otherwise it will just show the full query.

Check the Operations Page

A third method for validating your Partial Query Cache configuration is to check the Operations page:

1. Navigate to the Service that you configured with Partial Query Caching.
2. Navigate to the Metrics > Operations` page.
3. Click on one of the queries to open a detail page that includes a UI for Cache Entries on the right side of the view. This UI displays the Cache Entries as they are produced by Partial Query Caching given the latest cache config.
   • Note that this UI only shows the Cache Entries if the query is split into more than one entry, otherwise it will just show the full query.

Considerations

If you encounter any issues with your Partial Query Caching set up, we are dedicated to helping you be successful. You can contact customer success at support@stellate.co.