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.

commitLocalUpdate

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(
      userRecord,
      'CommentsComponent_comments_connection',
    );

    // 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(
      store,
      connectionRecord,
      newCommentRecord,
      '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

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.