Skip to main content
Version: v13.0.0

Local Data Updates

There are a couple of APIs that Relay provides in order to make purely local updates to the Relay store (i.e. updates not tied to a server operation).

Note that local data updates can be made both on client-only data, or on regular data that was fetched from the server via an operation.


To make updates using an updater function, you can use the commitLocalUpdate API:

import type {Environment} from 'react-relay';

const {commitLocalUpdate, graphql} = require('react-relay');

function commitCommentCreateLocally(
environment: Environment,
feedbackID: string,
) {
return commitLocalUpdate(environment, store => {
const feedbackRecord = store.get(feedbackID);
const connectionRecord = ConnectionHandler.getConnection(

// Create a new local Comment from scratch
const id = `client:new_comment:${randomID()}`;
const newCommentRecord = store.create(id, 'Comment');

// ... update new comment with content

// Create new edge from scratch
const newEdge = ConnectionHandler.createEdge(
'CommentEdge' /* GraphQl Type for edge */,

// Add edge to the end of the connection
ConnectionHandler.insertEdgeAfter(connectionRecord, newEdge);

module.exports = {commit: commitCommentCreateLocally};
  • commitLocalUpdate update simply takes an environment and an updater function.
    • updater takes a store argument, which is an instance of a RecordSourceSelectorProxy; this interface allows you to imperatively write and read data directly to and from the Relay store. This means that you have full control over how to update the store: you can create entirely new records, or update or delete existing ones.
  • In our specific example, we're adding a new comment to our local store when. Specifically, we're adding a new item to a connection; for more details on the specifics of how that works, check out our Updating Connections section.
  • Note that any local data updates will automatically cause components subscribed to the data to be notified of the change and re-render.


commitPayload takes an OperationDescriptor and the payload for the query, and writes it to the Relay Store. The payload will be resolved like a normal server response for a query, and will also resolve Data Driven Dependencies that are passed as JSResource, requireDefer, etc.

import type {FooQueryRawResponse} from 'FooQuery.graphql'

const {createOperationDescriptor} = require('relay-runtime');

const operationDescriptor = createOperationDescriptor(FooQuery, {
id: 'an-id',
otherVariable: 'value',

const payload: FooQueryRawResponse = {...};

environment.commitPayload(operation, payload);
  • An OperationDescriptor can be created by createOperationDescriptor; it takes the query and the query variables.
  • The payload can be typed using the Flow type generated by adding @raw_response_type to the query.
  • Note that any local data updates will automatically cause components subscribed to the data to be notified of the change and re-render.

Is this page useful?

Help us make the site even better by answering a few quick questions.