Cache Directives

The stellate_cache directive enables you to define cache rules directly in your GraphQL schema. You can configure the maxAge, SWR and scope for both types and fields. The changes in your GraphQL schema can be automatically applied to your Stellate service by your Continuous Integration/Continuous Deployment (CI/CD) system on your next deployment using the existing stellate push CLI command.

Why Choose Cache Directives Over Stellate Configuration?

Stellate JavaScript-based config allows incredible flexibility in how to configure caching for your GraphQL API. Users can easily define all of their cache rules in a single place and get an overview of how their cache is defined as a whole.

Because the config is Javascript-based, you can even import rules from other parts of your codebase which helps large teams using monorepos collaborate on the caching config.

This approach works well for most organizations, but it doesn’t cater to companies with a federated graph across multiple repositories. The feedback we hear from these organizations is that they want each subgraph team to define their own caching rules in their respective repositories as they are best positioned to know how the data they own should be cached.

For larger organizations or non-monorepo patterns, using the Stellate cache directive simplifies caching configuration and improves the scalability of your cache configuration.

Use in your Schema

GraphQL developers work in the GraphQL schema every day. It would be great they could put their caching config in the schema, where they already work, as close to the source of truth as possible. This is especially beneficial for people using federated graphs across many repositories. Adding directives to a schema is a native feature of GraphQL. By leveraging this capability, Stellate allows you to include caching as a GraphQL schema directive.

Distributed teams benefit from multiple cache rule locations

The stellate_cache directive makes it possible to have Stellate cache rules defined in multiple locations, with some defined in your:

• Subgraph schema
• Supergraph schema
• Stellate config file

Individual teams can add cache rules to their sub-graphs schema, which are then merged into the supergraph. When you use the Stellate CLI utility to push, it gathers all this information and computes the new caching rules. These new rules are then merged with the ones already present in the Stellate config.

Add a Cache Directive to your Schema

Before you begin

Before you start using the Stellate cache directive, you need to have the following in place:

• A Stellate service in front of your GraphQL server.
• Stellate CLI version >=2.7.0 installed.

To add the new cache directive to your GraphQL schema, use the following steps:

Note: You can use the directive in your schema or code. The following steps address adding the directive to your schema.

Configuration

1. Define a directive called stellate_cache.
2. To do this just cut and paste the following lines into your schema.

directive stellate_cache(
  maxAge: Int!
  swr: Int
  scope: String
) on FIELD_DEFINITION | OBJECT

3. Review your schema to locate the items you want to cache. Note: Read GraphQL Metrics for information about how to use Stellate GraphQL Metrics to find out what GraphQL API requests are good candidates for caching.
4. Add the GraphQL directive to the fields and types in your schema that you wish to cache.
5. Save your schema.

Push your GraphQL schema

Once you set up your cache directive and save your schema, the directive in the schema is merged with your supergraph. You can use the Stellate CLI to push these schema changes to deployment. For detailed information, read the Stellate CLI reference documentation. The following example shows the command to just push your GraphQL schema.

# Push schema information only
stellate push schema

When you push the schema, the Stellate directive and cache rules are merged into the Stellate config file. Once saved, the server uses the directive and cache rules for your Stellate caching proxy.

Validate your directive

When changes are pushed to Stellate, a config file is generated automatically. This allows you to continue to centrally define things like scopes, which are typically used organization-wide. It also enables safety guarantees, as collisions and errors are discovered at build-time and can prevent bad deployments.

To validate your changes:

• Run stellate push —-dry to do a local check of your pushed config and to see the impact of inflight changes.
• Check the pushed config in the Stellate UI after your CI has run stellate push.

Add the Stellate CLI to your CI/CD

The next step is to add the CLI command to the CI/CD process for the supergraph or final graph. Integrate this process into your CI infrastructure for seamless and automated inclusion in your release workflow.

Examples

Stellate cache directive in a schema

In the following example, we define our directive @stellate_cache. In this example, we define the type Todo such that Todos will be cached, with a maxAge: 60, swr: 180.

Figure 1: Example showing cache directive added to your schema.

Cache a field

To add the stellate_cache directive on a field, use the following format in your GraphQL schema, where the field is defined as medals and this field is set to not cache.

type Character @stellate_cache(maxAge: 900, swr: 900) {
  name: String
  medals: [string] @stellate_cache(maxAge: 0)
}