The Relay runtime is a full-featured GraphQL client that is designed for high performance even on low-end mobile devices and is capable of scaling to large, complex apps. The runtime API is not intended to be used directly in product code, but rather to provide a foundation for building higher-level product APIs such as React/Relay. This foundation includes:
- A normalized, in-memory object graph/cache.
- An optimized "write" operation for updating the cache with the results of queries/mutations/subscriptions.
- A mechanism for reading data from the cache and subscribing for updates when these results change due to a mutation, subscription update, etc.
- Garbage collection to evict entries from the cache when they can no longer be referenced by any view.
- A generic mechanism for intercepting data prior to publishing it to the cache and either synthesizing new data or merging new and existing data together (which among other things enables the creation of a variety of pagination schemes).
- Mutations with optimistic updates and the ability to update the cache with arbitrary logic.
- Support for live queries where supported by the network/server.
- Core primitives to enable subscriptions.
- Core primitives for building offline/persisted caching.
For users of classic Relay, note that the runtime makes as few assumptions as possible about GraphQL. Compared to earlier versions of Relay there is no concept of routes, there are no limitations on mutation input arguments or side-effects, arbitrary root fields just work, etc. At present, the main restriction from classic Relay that remains is the use of the
Node interface and
id field for object identification. However there is no fundamental reason that this restriction can't be relaxed (there is a single place in the codebase where object identity is determined), and we welcome feedback from the community about ways to support customizable object identity without negatively impacting performance.
(subsequent sections explain how these types are used in practice):
DataID(type): A globally unique or client-generated identifier for a record, stored as a string.
Record(type): A representation of a distinct data entity with an identity, type, and fields. Note that the actual runtime representation is opaque to the system: all accesses to
Recordobjects (including record creation) is mediated through the
RelayModernRecordmodule. This allows the representation itself to be changed in a single place (e.g. to use
Maps or a custom class). It is important that other code does not assume that
Records will always be plain objects.
RecordSource(type): A collection of records keyed by their data ID, used both to represent the cache and updates to it. For example the store's record cache is a
RecordSourceand the results of queries/mutations/subscriptions are normalized into
RecordSources that are published to a store. Sources also define methods for asynchronously loading records in order to (eventually) support offline use-cases. Currently the only implementation of this interface is
RelayInMemoryRecordSource; future implementations may add support for loading records from disk.
Store(type): The source of truth for an instance of
RelayRuntime, holding the canonical set of records in the form of a
RecordSource(though this is not required). Currently the only implementation is
Network(type): Provides methods for fetching query data from and executing mutations against an external data source.
Environment(type): Represents an encapsulated environment combining a
Network, providing a high-level API for interacting with both. This is the main public API of
Types for working with queries and their results include:
Selector(type): A selector defines the starting point for a traversal into the graph for the purposes of targeting a subgraph, combining a GraphQL fragment, variables, and the Data ID for the root object from which traversal should progress. Intuitively, this "selects" a portion of the object graph.
Snapshot(type): The (immutable) results of executing a
Selectorat a given point in time. This includes the selector itself, the results of executing it, and a list of the Data IDs from which data was retrieved (useful in determining when these results might change).
Objects, these units of data are referred to as
Records. Relay represents both its internal cache as well as query/mutation/etc results as a mapping of data IDs to records. The data ID is the unique (with respect to the cache) identifier for a record - it may be the value of an actual
id field or based on the path to the record from the nearest object with an
id (such path-based ids are called client ids). Each
Record stores its data ID, type, and any fields that have been fetched. Multiple records are stored together as a
RecordSource: a mapping of data IDs to
For example, a user and their address might be represented as follows:
 Note that GraphQL itself does not impose this constraint, and Relay Runtime may also be used for schemas that do not conform to it. For example, both systems can be used to query a single denormalized table. However, many of the features that Relay Runtime provides, such as caching and normalization, work best when the data is represented as a normalized graph with stable identities for discrete pieces of information.
Store is the source of truth for application data and provides the following core operations.
lookup(selector: Selector): Snapshot: Reads the results of a selector from the store, returning the value given the data currently in the store.
subscribe(snapshot: Snapshot, callback: (snapshot: Snapshot) => void): Disposable: Subscribe to changes to the results of a selector. The callback is called when data has been published to the store that would cause the results of the snapshot's selector to change.
publish(source: RecordSource): void: Update the store with new information. All updates to the store are expressed in this form, including the results of queries/mutation/subscriptions as well as optimistic mutation updates. All of those operations internally create a new
RecordSourceinstance and ultimately publish it to the store. Note that
publish()does not immediately update any
subscribe()-ers. Internally, the store compares the new
RecordSourcewith its internal source, updating it as necessary:
- Records that exist only in the published source are added to the store.
- Records that exist in both are merged into a new record (inputs unchanged), with the result added to the store.
- Records that are null in the published source are deleted (set to null) in the store.
- Records with a special sentinel value are removed from the store. This supports un-publishing optimistically created records.
notify(): void: Calls any
subscribe()-ers whose results have changed due to intervening
notify()allows for multiple payloads to be published before performing any downstream update logic (such as rendering).
retain(selector: Selector): Disposable: Ensure that all the records necessary to fulfill the given selector are retained in-memory. The records will not be eligible for garbage collection until the returned reference is disposed.
- The query is fetched from the network.
- The query and response are traversed together, extracting the results into
Recordobjects which are added to a fresh
RecordSource would then be published to the store:
Publishing the results updates the store but does not immediately notify any subscribers. This is accomplished by calling
...which calls the callbacks for any
subscribe()-ers whose results have changed. Each subscription is checked as follows:
- First, the list of data IDs that have changed since the last
notify()is compared against data IDs listed in the subscription's latest
Snapshot. If there is no overlap, the subscription's results cannot possibly have changed (if you imagine the graph visually, there is no overlap between the part of the graph that changed and the part that is selected). In this case the subscription is ignored, otherwise processing continues.
- Second, any subscriptions that do have overlapping data IDs are re-read, and the new/previous results are compared. If the result has not changed, the subscription is ignored (this can occur if a field of a record changed that is not relevant to the subscription's selector), otherwise processing continues.
- Finally, subscriptions whose data actually changed are notified via their callback.
Products access the store primarily via
subscribe(). Lookup reads the initial results of a fragment, and subscribe observes that result for any changes. Note that the output of
lookup() - a
Snapshot - is the input to
subscribe(). This is important because the snapshot contains important information that can be used to optimize the subscription - if
subscribe() accepted only a
Selector, it would have to re-read the results in order to know what to subscribe to, which is less efficient.
Therefore a typical data flow is as follows - note that this flow is managed automatically by higher-level APIs such as React/Relay. First a component will lookup the results of a selector against a record source (e.g. the store's canonical source):
Next, it will
subscribe() using this snapshot in order to be notified of any changes - see the above diagram for