protocol RecordSourceSelectorProxy: RecordSourceProxy

A RecordSourceSelectorProxy provides API for reading from and updating the Relay store in response to a mutation. This proxy is passed to updater and optimisticUpdater functions you provide with your mutations. It allows you to update the client-side store to reflect the new state after the mutation has been performed.

Relay automatically uses the responses to your mutations to update records in the store with matching IDs, but there are other kinds of state changes that you'd like to reflect in your UI that Relay can't figure out automatically. For example:

• Adding a new record to a list
• Deleting a record
• Moving a record within a list
• Moving a record between different lists

One way to handle these would be to refetch any affected queries. But doing so would make your app less responsive by needing to wait for at least one extra network call, and it may get complicated keeping track of which queries will be affected. Updaters are fast, because they don't perform any extra network calls (you can even do them optimistically before the mutation has responded), and they keep the logic for how to update the state in one place with the mutation itself.

If you're using @connection fields for pagination, see ConnectionHandler for some convenient methods for manipulating those fields.

Getting records from the store

var root: RecordProxy { get }

The root property gives you a RecordProxy for the root type in your schema (usually Query or Root). You can use the record proxy to traverse to the parts of your schema that you want to update.

subscript(_ dataID: DataID) -> RecordProxy? { get }

You can provide a specific ID of a record as a subscript to the record source proxy to get a RecordProxy for that record. If the record is not in the store, this will be nil.

func getRootField(_ fieldName: String) -> RecordProxy?

getRootField lets you access a singular field from the root of the mutation response.

For example, if I execute this mutation:

mutation ChangeTodoStatusMutation($input: ChangeTodoStatusInput!) {
	changeTodoStatus(input: $input) {
		todo {
			id
			complete
		}
	}
}