<NME> local-data-updates.md
<BEF> ---
id: local-data-updates
title: Local Data Updates
slug: /guided-tour/updating-data/local-data-updates/
description: Other APIs for modifying store data
keywords:
- client-only
- commitLocalUpdate
- commitPayload
---

import DocsRating from '@site/src/core/DocsRating';
import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
import FbLocalDataUpdatesFlow from './fb/FbLocalDataUpdatesFlow.md';

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](../client-only-data/), or on regular data that was fetched from the server via an operation.

## commitLocalUpdate

To make updates using an [`updater`](../imperatively-modifying-store-data/) function, you can use the `commitLocalUpdate` API:

```js
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`](../../../api-reference/store/);  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.

```js
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 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.

<FbLocalDataUpdatesFlow />

<DocsRating />
```

* 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.

<FbLocalDataUpdatesFlow />

<MSG> Easy content changes to relay mutation docs

Summary:
* Add documentation about second parameter to upater in various places
* Add recommendation that the like_count is read out in advance

Reviewed By: josephsavona

Differential Revision: D33857256

fbshipit-source-id: 8b4db428a45554432f15ae9fa0ae5f4dd190f2bf

<DFF> @@ -84,7 +84,7 @@ 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.
+* 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.
 
 <FbLocalDataUpdatesFlow />

{'addition_count': 1, 'commit_subject': 'Easy content changes to relay mutation docs', 'deletion_count': 1, 'file_extension': '.md', 'lang': 'md', 'license': 'mit', 'repo_name': 'facebook/relay'}