Skip to main content
Version: v18.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.

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 => {
// Imperatively mutate the store here
});
}

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.
    • Unlike regular and optimistic updaters that are accepted by the mutation and subscription APIs, the updater passed to commitLocalUpdate does not accept a second parameter. This is because there is no associated network response.
  • 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(operationDescriptor, 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 the directive @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.