How to Update Relay Cache

Donghyeon Kim
Jan 31 · 3 min read
Photo by Alina Grubnyak on Unsplash

This article covers how to manipulate records inside Relay cache (a.k.a. Relay store). Although Relay can take care of great amount of state management by itself, sometimes developers have to tell Relay what to do. In order to do that efficiently, we need to know how Relay manages its cache and how we can interact with the cache.

What Relay Cache Looks Like

Relay stores its cache as a graph of records. Each record is identified by its unique ID, and a record can have scalar fields and “links” to other records.

For example, look at this GraphQL schema:

A User record has an id field and an email field which are scalars. Also, it has a list of Post records, and we call these “linked records”.

So for example, if we want to access an Post record inside Relay cache, we have two options:

  1. Access it directly by its ID.

We can freely modify scalar values or links as long as we can access the cached records. I will discuss the API specifics later in this article.

How to Update Relay Cache

There are two ways to update Relay cache.

  1. Fetch the updated record from server.

Approach 1: Fetch the Updated Record

The first approach is easier and cleaner. If server can response with the updated record after mutation, Relay can automatically update the cache accordingly. Look at this GraphQL mutation:

It is a simple mutation that updates the title of a Post. When successful, server will return the updated version of Post. Relay will use this response to update its cache, so there is no extra effort required for us.

Just make sure to request id and title field so that Relay can process the response and update cache.

Approach 2: Updater Function

Receiving the updated value immediately as a response is nice, but sometimes we cannot change APIs to suit our needs. This is where we need to manually modify Relay cache using updater function. I will cover the basics in this article, but you might want to check out Relay’s official documentation on this topic.

Consider this mutation:

deletePostContent mutation does not respond with the updated Post record; therefore, Relay will not update its cache automatically. Although we do not have the updated record, we know that the content field will be null after successful deletePostContent. Here’s how you update cache manually using updater function:

In this case, finding the Post record was easy because we knew its ID. store.get method returns a proxy to the record if it exists. Proxy is how we mainly interact with Relay cache, so it is a good idea to get familiar with its API (Relay Store API). Here are a few useful methods of RecordProxy :

  • getValue : Gets the value of a scalar field.

Alternatives to Cache Update

Maybe your issue can be resolved without updating Relay cache. Consider these alternatives before writing your updater function.

Cache Invalidation

We can invalidate individual records using RecordProxy.invalidateRecord method. Calling this method will mark the Record as “stale” and force Relay not to re-use this cached record. Note that invalidation does not trigger any refetch unless specified inside useSubscribeToInvalidationState hook.

Imperative Refetch

Relay provides for fetchQuery and useQueryLoader for imperative usage. We can trigger imperative re-fetch on mutation completion.


If server can respond to mutation with the updated record, let Relay use server response to update its cache. When server response is insufficient, we can read & write pretty much any value inside Relay cache using updater function as long as we know how to locate the records of our interest.


Open source community

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store