Docs
Launch GraphOS Studio

Declarative cache IDs in Apollo Kotlin


When using a normalized cache in , it's recommended that you specify a cache ID for each in your schema. If you don't, objects are assigned a default cache ID, but that ID can lead to undesirable duplication of data.

When specifying cache IDs, it's recommended that you do so declaratively, using the methods described in this article:

extend type Book @typePolicy(keyFields: "id")

For advanced use cases, you can also define cache IDs programmatically.

How they work

With declarative cache IDs, the codegen process adds ID automatically and generates type-safe code that can return a valid cache ID for any object.

To do this, extends your back-end schema. The spec supports object extensions using the extend type keywords. We can use this together with the @typePolicy and @fieldPolicy , along with an extra .graphqls file named extra.graphqls.

Note that you'll need to make sure that the extra.graphqls file is included in your schema configuration

You can obtain a given 's cache ID from one of two sources:

SourceDirectiveDescription
From a response object's fields (e.g., Book.id)@typePolicyThis happens after a network request and is essential to merging a query result with existing cached data. This is the most common case.
From a GraphQL operation's arguments (e.g., author(id: "au456"))@fieldPolicyThis happens before a network request and enables you to avoid a network round trip if all requested data is in the cache already. This is an optional optimization that can avoid some cache misses.

@typePolicy

The @typePolicy enables you to specify an object's cache ID from key fields of the object returned by your . Most commonly, you can use an object's id as its key field.

For example, let's say our app's schema.graphqls file includes the following definition:

schema.graphqls
type Book {
id: String!
author: Author!
title: String!
}

We can add the following definition to an extra.graphqls file in the same directory as our schema:

extra.graphqls
extend type Book @typePolicy(keyFields: "id")

now knows to use the id of a Book type to generate its cache ID.

You can specify multiple key for an object if they're all required to uniquely identify a particular cache entry:

extra.graphqls
extend type Author @typePolicy(keyFields: "firstName lastName")

In this case, the cache ID for an Author object includes the values of both its firstName and lastName .

All of an 's key must return a scalar type.

@fieldPolicy

The @fieldPolicy enables you to specify an object's cache ID from the values of key arguments you provide to a particular . This enables you to identify an object in your cache before sending a network request, potentially enabling you to skip the request entirely.

For example, let's say our app's schema.graphqls file includes the following definition:

schema.graphqls
type Query {
book(id: String!): Book
}

We happen to know that this returns whichever Book object has an id that matches the required . Therefore, we can make the id a key argument for this .

We can add the following definition to an extra.graphqls file in the same directory as our schema:

extra.graphqls
extend type Query @fieldPolicy(forField: "book", keyArgs: "id")

now knows to check the cache for a Book object with the provided id before sending a network request for Query.book.

Note that even though the @fieldPolicy corresponds to a single , you apply the directive to the type definition (Query in this case). This is because doesn't allow extending a single . You specify which the corresponds to with the forField .

You can specify multiple key for a if they're all required to uniquely identify a particular cache entry:

extra.graphqls
extend type Query @fieldPolicy(forField: "author", keyArgs: "firstName lastName")

In this case, the cache ID for an Author object includes the values of both its firstName and lastName , which are both provided as to the Query.author .

If multiple of an have key , you can apply multiple @fieldPolicy to that type.

Previous
Normalized caches
Next
Programmatic cache IDs
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company