})
#### Autocomplete throughout your GraphQL tagged template literals
})
#### Hover to see type information and documentation about Relay-specific features
})
#### `@deprecated` fields are rendered using ~~strikethrough~~
})
#### Click-to-definition for fragments, fields and types
})
#### Quick fix suggestions for common errors
})
## Language Server
The editor support is implemented using the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) which means it can be used by a variety of editors, but in tandem with this release, [Terence Bezman](https://twitter.com/b_ez_man) from [Coinbase](https://www.coinbase.com/) has contributed an official VS Code extension.
[**Find it here!**](https://marketplace.visualstudio.com/items?itemName=meta.relay)
## Why Have a Relay-Specific Editor Extension?
The GraphQL foundation has an official language server and [VS Code extension](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql) which provides editor support for GraphQL generically. This can provide a good baseline experience, but for Relay users, getting this information directly from the Relay compiler offers a number of benefits:
* Relay compiler errors can surface directly in the editor as “problems”, often with suggested quick fixes
* Hover information is aware of Relay-specific features and directives and can link out to relevant documentation
---
### Home (`website/docs/home.mdx`)
---
id: home
title: Home
slug: /
description: Relay documentation landing page
keywords:
- relay
- graphql
- data
- introduction
- home
---
# Relay Docs
import DocsRating from '@site/src/core/DocsRating';
import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
Relay is a powerful [GraphQL](https://graphql.org/) client for [React](https://react.dev/). It embodies years of learning to give you **outstanding performance by default** while keeping your code **scalable and maintainable**.
Relay brings the composability of React components to data fetching. Each component declares its own data needs, and Relay combines them into efficient pre-loadable queries. Every aspect of its design is to make the natural way of writing components also the most performant.
## Features
* **Declarative**: Just declare what data each component needs and Relay will handle generating [optimal queries](https://relay.dev/blog/2023/10/24/how-relay-enables-optimal-data-fetching/) for each surface.
* **Composable**: Components act like building bricks that can click into place anywhere in your app without needing to manually update queries.
* **Pre-fetchable**: Relay's generated queries allow you to start fetching data for your surface before your code even downloads or runs.
* **Built-in UI patterns**: Relay implements loading states, pagination, refetching, optimistic updates, rollbacks, and other common UI behaviors that are tricky to get right.
* **Consistent state**: Relay maintains a normalized data store, so components that observe the same data stay in sync even if they reach it by different queries.
* **Type safe**: Relay generates TypeScript types for each GraphQL snippet so that errors are caught statically, not at runtime.
* **Streaming/deferred data**: Declaratively defer parts of your query and Relay will progressively re-render your UI as the data streams in.
* **Developer experience**: Relay's [editor support](./editor-support.mdx) provides autocompletion and go-to-definition for your GraphQL schema.
---
### Community Learning Resources (`website/docs/community/learning-resources.mdx`)
---
id: learning-resources
title: Community Learning Resources
slug: /community-learning-resources/
---
import useBaseUrl from '@docusaurus/useBaseUrl';
import DocsRating from '@site/src/core/DocsRating';
import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
## Guides and articles:
- [How to use @argumentsDefinitions to define local variables to your fragments](https://medium.com/entria/relay-modern-argumentdefinitions-d53769dbb95d) (by Entria)
- [Deep Dive of Updater Relay Store function. How to update your store properly after a mutation or subscription](https://medium.com/entria/wrangling-the-client-store-with-the-relay-modern-updater-function-5c32149a71ac) (by Entria)
- [Optimistic Update: how to update your UI before server responds](https://medium.com/entria/relay-modern-optimistic-update-a09ba22d83c9) (by Entria)
- [Relay Network Deep Dive - how to incrementally improve your network layer to manage complex data fetching requirements](https://medium.com/entria/relay-modern-network-deep-dive-ec187629dfd3) (by Entria)
- [Relay Modern with TypeScript - how to configure Relay Modern to make it with TypeScript](https://medium.com/@sibelius/relay-modern-migration-to-typescript-c26ab0ee749c) (by @sibelius)
- [Collection of random thoughts and discoveries around Relay](https://mrtnzlml.com/docs/relay)
Star Wars Films
{films?.map((film) => ({user.name}
}
```
## By Example
For a hands on example, see [this example project](https://github.com/captbaritone/grats-relay-example/pull/1) showing Relay configured to use `@semanticNonNull` and `@throwOnFieldError` alongside [Grats](https://grats.capt.dev/) which [has support](https://grats.capt.dev/docs/guides/strict-semantic-nullability/) for automatically deriving a schema that includes the experimental `@semanticNonNull` directives.
## GraphQL Conf Talk
The Relay team gave a talk at GraphQL Conf 2024 about semantic nullability. You can watch it here:
## Further Reading
- [True Nullability Schema](https://github.com/graphql/graphql-wg/discussions/1394)
- [Strict Semantic Nullability](https://github.com/graphql/graphql-wg/discussions/1410)
- [RFC: SemanticNonNull type (null only on error)](https://github.com/graphql/graphql-spec/pull/1065)
- [Grat's support/documentation for `@SemanticNonNull`](https://grats.capt.dev/docs/guides/strict-semantic-nullability/)
- [Apollo's specification for this directive](https://specs.apollo.dev/nullability/v0.2/)
- [Support for `@SemanticNonNull` in Apollo Kotlin](https://www.apollographql.com/docs/kotlin/v4/advanced/nullability/#handle-semantic-non-null-with-semanticnonnull) added in [4.0.0-beta.3](https://github.com/apollographql/apollo-kotlin/releases/tag/v4.0.0-beta.3)
- [Awesome Semantic Nullability](https://github.com/captbaritone/awesome-semantic-nullability) a list of frameworks and stand alone tools that support semantic nullability
---
### Guides Testing Relay Components (`website/docs/guides/testing-relay-components.mdx`)
---
id: testing-relay-components
title: Testing Relay Components
slug: /guides/testing-relay-components/
description: Relay guide to testing Relay components
keywords:
- testing
- createMockEnvironment
- RelayMockEnvironment
- MockPayloadGenerator
- relay_test_operation
- queuePendingOperation
- resolver
---
import DocsRating from '@site/src/core/DocsRating';
import {FbInternalOnly, OssOnly} from 'docusaurus-plugin-internaldocs-fb/internal';
## Abstract
The purpose of this document is to cover the Relay APIs for testing Relay components.
The content is focused mostly on jest unit-tests (testing individual components) and integration tests (testing a combination of components). But these testing tools may be applied in different cases: screenshot-tests, production smoke-tests, "Redbox" tests, fuzz-tests, e2e test, etc.
What are the benefits of writing jest tests:
* In general, it improves the stability of the system. Flow helps with catching a various set of Javascript errors, but it is still possible to introduce regressions to the components. Unit-tests help find, reproduce, and fix regressions, and prevent them in the future.
* It simplifies the refactoring process: when properly written (testing public interface, not implementation) - tests help with changing the internal implementation of the components.
* It may speed up and improve the development workflow. Some people may call it Test Driven Development (TM). But essentially it's just writing tests for public interfaces of your components, and then writing the components that implement those interfaces. Jest —watch mode really shines in this case.
* It will simplify the on-boarding process for new developers. Having tests helps new developers ramp up on the new code base, allowing them to fix bugs and deliver features.
One thing to notice: while jest unit- and integration tests will help improve the stability of the system, they should be considered one part of a bigger stability infrastructure with multiple layers of automated testing: flow, e2e, screenshot, "Redbox", performance tests.
## Testing with Relay
Testing applications that use Relay may be challenging, because of the additional data fetching layer that wraps the actual product code.
And it's not always easy to understand the mechanics of all processes that are happening behind Relay, and how to properly handle interactions with the framework.
Fortunately, there are tools that aim to simplify the process of writing tests for Relay components, by providing imperative APIs for controlling the request/response flow and additional API for mock data generation.
There are two main Relay modules that you may use in your tests:
* `createMockEnvironment(options): RelayMockEnvironment`
* `MockPayloadGenerator` and the `@relay_test_operation` directive
With `createMockEnvironment,` you will be able to create an instance of `RelayMockEnvironment`, a Relay environment specifically for your tests. The instance created by `createMockEnvironment` implements the Relay Environment Interface and it also has an additional Mock layer, with methods that allow you to resolve/reject and control the flow of operations (queries/mutations/subscriptions).
The main purpose of `MockPayloadGenerator` is to improve the process of creating and maintaining the mock data for tested components.
One of the patterns you may see in the tests for Relay components: 95% of the test code is the test preparation—the gigantic mock object with dummy data, manually created, or just a copy of a sample server response that needs to be passed as the network response. And the remaining 5% is actual test code. As a result, people don't test much. It's hard to create and manage all these dummy payloads for different cases. Hence, writing tests is time-consuming and tests are sometimes painful to maintain.
With the `MockPayloadGenerator` and `@relay_test_operation`, we want to get rid of this pattern and switch the developer's focus from the preparation of the test to the actual testing.
## Testing with React and Relay
**[React Testing Library](https://testing-library.com/react)** is a set of helpers that let you test React components without relying on their implementation details. This approach makes refactoring a breeze and also nudges you towards best practices for accessibility. Although it doesn't provide a way to "shallowly" render a component without its children, a test runner like Jest lets you do this by [mocking](https://reactjs.org/docs/testing-recipes.html#mocking-modules).
{props.artist.name} is great!
```
{props.artist.name} is great!
```
About the artist: {props.artist.biography}
;
}
```
About the artist: {props.artist.biography}
;
}
```
// change-line
{stories.map(story =>
);
}
```
### Step 3 — Add a React key based on the node ID
At this point, you should see multiple stories on the screen! It's beginning to look like a proper newsfeed app.
However, we're also getting a React warning that we're rendering an array of components without [providing a key attribute](https://reactjs.org/docs/lists-and-keys.html).
It's always important to heed this warning, and more specifically to base keys on the identity of the things being displayed, rather than simply their indices in the array. This allows React to handle reordering and deleting items from the list correctly, since it knows which items are which even if their order changes.
Luckily, GraphQL nodes generally have IDs. We can simply select the `id` field of `story` and use it as a key:
```
const NewsfeedQuery = graphql`
query NewsfeedQuery {
topStories {
// change-line
id
...StoryFragment
}
}
`;
...
export default function Newsfeed({}) {
const data = useLazyLoadQuery
{stories.map(story => (
);
}
```
With that, we've got a collection of Stories on the screen. It's worth pointing out that here we're mixing individual fields with fragment spreads in the same place in our query. This means that Newsfeed can read the fields it cares about (directly from `useLazyLoadQuery`) while Story can read the fields it cares about (via `useFragment`). The *same object* both contains Newsfeed's selected field `id` and is also a fragment key for `StoryFragment`.
:::tip
GraphQL Lists are only the most basic way of dealing with collections of things. We’ll build on them to do pagination and infinite scrolling later in the tutorial, using a special system called Connections. You’ll want to use Connections in most situations where you have a collection of items — although you’ll still use GraphQL Lists as a building block.
:::
Onward!
---
### Tutorial Fragments 1 (`website/docs/tutorial/fragments-1.mdx`)
# Fragments
Fragments are one of the distinguishing features of Relay. They let each component declare its own data needs independently, while retaining the efficiency of a single query. In this section, we’ll show how to split a query up into fragments.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
* * *
To start with, let’s say we want our Story component to show the date that the story was posted. To do that, we need some more data from the server, so we’re going to have to add a field to the query.
Go to `Newsfeed.tsx` and find `NewsfeedQuery` so that you can add the new field:
```
const NewsfeedQuery = graphql`
query NewsfeedQuery {
topStory {
title
summary
// change-line
createdAt // Add this line
poster {
name
profilePicture {
url
}
}
thumbnail {
url
}
}
}
`;
```
Now we've updated the query, we need to run the Relay compiler so that it knows about the updated Graphql query by running `npm run relay`.
Next, go to `Story.tsx` and modify it to display the date:
```
// change-line
import Timestamp from './Timestamp';
type Props = {
story: {
// change-line
createdAt: string; // Add this line
...
};
};
export default function Story({story}: Props) {
return (
Deep dive: GraphQL Directives
The syntax for fragment arguments may look rather clumsy. This is because it is based on *directives*, a system for extending the GraphQL language. In GraphQL, any symbol starting with `@` is a directive. Their meaning isn't defined by the GraphQL spec, but is up to the specific client or server implementation. Relay defines [several directives](../../api-reference/graphql-and-directives) to support its features — fragment arguments for one. These directives are not sent to the server, but give instructions to the Relay compiler at build time. The GraphQL spec actually does define the meaning of three directives: * `@deprecated` is used in schema definitions and marks a field as deprecated. * `@include` and `@skip` can be used to make the inclusion of a field conditional. Besides these, GraphQL servers can specify additional directives as part of their schemas. And Relay has its own build-time directives, which allow us to extend the language a bit without changing its grammar.{data.name}
- Joined
- {data.location.name} )} {data.organizationKind != null && (
graphql`` tag. This tag allows the Relay compiler to find and compile the GraphQL within a JavaScript codebase.
* Our GraphQL string consists of a query declaration with the keyword `query` and then a query name. The query name must be globally unique and end with `Query`.
* Inside the query declaration are *fields*, which specify what information to query for*:*
* Some fields are *scalar fields* that retrieve a string, number, or other unit of information.
* Other fields are *edges* that let us traverse from one node in the graph to another. When a field is an edge, it’s followed by another block `{ }` containing fields for the node at the other end of the edge. Here, the `poster` field is an edge that goes from a Story to a Person who posted it. Once we’ve traversed to the Person, we can include fields about the Person such as their `name`.
This illustrates the part of the graph that this query is asking for:
Now that we’ve defined the query, we need to do two things.
1. Run the Relay compiler so that it knows about the new Graphql query. (`npm run relay`)
2. Modify our React component to fetch it and to use the data returned by the server.
If you open `package.json` you will find the script `relay` is hooked up to run the Relay compiler. This is what `npm run relay` does. Once the compiler successfully updates/generated the new compiled query you will be able to find it in the `__generated__` folder under `src/components/` as `NewsfeedQuery.graphql.ts`.
Next, turn back to the `Newsfeed` component and start by deleting the placeholder data. Then, replace it with this:
```
import { useLazyLoadQuery } from "react-relay";
export default function Newsfeed({}) {
const data = useLazyLoadQuery(
// color1
NewsfeedQuery,
// color2
{},
);
const story = data.topStory;
// As before:
return (
Deep dive: Suspense for Data Loading
*Suspense* is a new API in React that lets React wait while data is loaded before it renders components that need that data. When a component needs to load data before rendering, React shows a loading indicator. You control the loading indicator's location and style using a special component called `Suspense`. Right now, there's a `Suspense` component inside `App.tsx`, which is what shows the spinner while `useLazyLoadQuery` is loading data. We'll look at Suspense in more detail in later sections when we add some more interactivity to the app.Deep dive: Queries are Static
All of the GraphQL strings in a Relay app are pre-processed by the Relay compiler and removed from the resulting bundled code. This means you can’t construct GraphQL queries at runtime — they have to be static string literals so that they’re known at compile time. But it comes with major advantages. First, it allows Relay to generate type definitions for the results of the query, making your code more type-safe. Second, Relay replaces the GraphQL string literal with an object that tells Relay what to do. This is much faster than using the GraphQL strings directly at runtime. Also, Relay’s compiler can be configured to [save queries to the server](/docs/guides/persisted-queries/) when you build your app, so that at runtime the client need only send a query ID instead of the query itself. This saves bundle size and network bandwidth, and can prevent attackers from writing malicious queries since only those your app was built with need be available. So when you have a GraphQL tagged string literal in your program... ``` const MyQuery = graphql` query MyQuery { viewer { name } } `; ``` ... the JavaScript variable `MyQuery` is actually assigned to an object that looks something like this: ``` const MyQuery = { kind: "query", selections: [ { name: "viewer", kind: "LinkedField", selections: [ name: "name", kind: "ScalarField", ], } ] }; ``` along with various other properties and information. These data structures are carefully designed to allow the JIT to run Relay’s payload processing code very quickly. If you’re curious, you can use the [Relay Compiler Explorer](/compiler-explorer) to play with it.graphql`` literal. As long as npm run dev is running, the Relay compiler will automatically regenerate these files whenever you save one of your JavaScript source files, so you don’t need to refresh anything to keep them up to date.
Using Relay’s generated types makes your app safer and more maintainable. In addition to TypeScript, Relay supports the Flow type system if you want to use that instead. When using Flow, the extra annotation on `useLazyLoadQuery` is not needed, because Flow directly understands the contents of the graphql`` tagged literal.
We’ll revisit types throughout this tutorial. But next, we'll look at an even more important way that Relay helps us with maintainability.
* * *
## Summary
Queries are the foundation of fetching GraphQL data. We’ve seen:
* How to define a GraphQL query within our app using the graphql`` tagged literal.
* How to use the `useLazyLoadQuery` hook to fetch the results of a query when a component renders.
* How to import Relay's generated types for type safety.
In the next section, we’ll look at Fragments, one of the most core and distinctive aspects of Relay. Fragments let each individual component define its own data requirements, while retaining the performance advantages of issuing a single query to the server.
---
### Tutorial Queries 2 (`website/docs/tutorial/queries-2.mdx`)
# Queries for Interactions
We’ve seen how fragments let us specify data requirements in each component, yet at runtime perform only a single query for an entire screen. Here we’ll look at a situation where we *want* a second query on the same screen. This will also let us explore some more features of GraphQL queries.
* We’ll build a hovercard that shows more details about the poster of a story when you hover over their name.
* The hovercard will use a second query to fetch additional information that’s only needed if the user hovers.
* We’ll use **query variables** to tell the server which person we’d like more details about.
* We’ll see how to improve performance with **preloaded queries**.
After covering these topics, we’ll return to look at some more advanced features of Fragments.
* * *
In this section we’ll add a hovercard to `PosterByline` so that you can see more details about the poster of a story by hovering over their name.
Deep dive: When to use a secondary query
We've mentioned before that Relay is designed to help you fetch all of your data requirements for an entire screen up-front. But we can generalize this and say that it's a *user interaction* that should have at most one query. Navigating to another screen is just one common type of user interaction. Within a screen, some interactions may disclose additional data from what was shown initially. If an interaction is performed relatively rarely, but needs a significant amount of additional data, it can be smart to fetch that additional data in a second query, performed when the interaction happens, rather than up-front when the screen is first loaded. This makes that initial load faster and less expensive. There are also some interactions where the amount of data fetched is indefinite — e.g., a hovercard within a hovercard — and not feasible to know statically. If data is lower-priority and should be loaded after the main data has loaded, but should pop in automatically without further user input, Relay has a feature called a *deferred fragment* for that. We'll cover it later.{data.name}
{data.name}
// change
The node field is a top-level field defined in our schema that lets us fetch any graph node given its unique ID. It takes the ID as an argument, which is currently hard-coded. In this exercise, we’ll be replacing this hard-coded ID with a variable supplied by our UI state.
Deep dive: Caching and the Relay Store
In contrast to most other systems, Relay’s caching is not based on queries, but on graph nodes. Relay maintains a local cache of all the nodes it has fetched called the Relay Store. Each node in the Store is identified and retrieved by its ID. If two queries ask for the same information, as identified by node IDs, then the second query will be fulfilled using the cached information retrieved for the first query, and not be fetched. Make sure to configure [missing field handlers](/docs/guided-tour/reusing-cached-data/filling-in-missing-data/) to take advantage of this caching behavior. Relay will garbage-collect nodes from the Store if they aren’t “reachable” from any queries that are used, or have been recently used, by any mounted components.Deep dive: Why GraphQL Needs a Syntax for Variables
You might be wondering why GraphQL even has the concept of variables, instead of just interpolating the value of the variables into the query string. Well, [as mentioned before](../queries-1), the text of the GraphQL query string isn’t available at runtime, because Relay replaces it with a data structure that is more efficient. You can also configure Relay to use *prepared queries*, where the compiler uploads each query to the server at build time and assigns it an ID — in that case, at runtime, Relay is just telling the server “Give me query #1337”, so string interpolation isn't possible and therefore the variables have to come out of band. Even when the query string is available, passing variable values separately eliminates any issues with serializing arbitrary values and escaping strings, above what is required with any HTTP request.
...
);
}
```
Note that the query variables are now passed in here where we initiate the request.
At this point, you should see the same behavior as before, but now it will be a little bit faster since Relay can get the query started earlier.
:::tip
Although we introduced queries using `useLazyLoadQuery` for simplicity, preloaded queries are always the preferred way to use queries in Relay because they can significantly improve performance in the real world. With the appropriate [integrations with your server and router system](https://github.com/relayjs/relay-examples/tree/main/issue-tracker-next-v13), you can even preload the main query for a webpage on the server side before you’ve even downloaded or run any client code.
:::
* * *
## Summary
* Although all of the data initially shown on a screen should be combined into one query, user interactions needing further information can be handled with secondary queries.
* Query variables let you pass information to the server along with your query.
* Query variables are used by passing them into field arguments.
* Preloaded queries are always the best way to go. For user interaction queries, initiate the fetch in the event handler. For the initial query for your screen, initiate the fetch as early as possible in your specific routing system. Use lazy-loaded queries only for quick prototyping, or not at all.
Next we'll briefly look at a way to enhance the hovercard by handling different types of posters differently. After that, we'll see how to handle situations where information that's part of the initial query also needs to be updated and refetched with different variables.
---
### Tutorial Refetchable Fragments (`website/docs/tutorial/refetchable-fragments.mdx`)
# Refetchable Fragments
In this section, we'll look at how to fetch different data in response to user input.
* We'll build a **filterable friends list**.
* We'll see how to refetch only the necessary data, not an entire query.
* * *
Since Relay encourages you to fetch all of your data in one big query, what happens when you need to refetch some data with different variables?
For example, suppose you were building a filterable list. You would need to fetch new search results when the search input changed.
One way to approach this would be to use a separate, secondary query to fetch the list, much like we did to fetch the hovercard earlier. Then we could change the query variables and refetch the query when the input changed.
However, this isn't optimal, because it needlessly uses a second query to fetch the *initial* list, before any user input occurs. The hovercard only appeared in response to a user interaction, but if the filterable list is visible and ready to be filtered, we might as well get its initial contents as part of our big query.
On the other hand, we don't want to refetch the *entire big query* whenever the input changes. Not only would this mean retrieving a large amount of data unnecessarily, it could disrupt other parts of the UI. If certain data unrelated to the filterable list has changed on the server, it would appear to randomly change when the query was refetched. Besides, this would mean threading the user input up to the top of the React tree where the query lives, which would not scale very well.
To address these issues, Relay provides *refetchable fragments*. These are fragments that can be refetched with new variables, separately from the rest of the query that they get spread into. They allow us to change a fragment’s arguments and fetch new data for the new argument values, just as we can fetch an entire query with new query variables.
But fragments are just that, fragments — they aren’t queries and can’t be fetched without being spread into a query and read out from the query results. So how do refetchable fragments actually work? The answer is that the Relay compiler generates a new, separate query just to refetch the fragment. The data is retrieved *initially* as part of whatever larger query the fragment is spread into, but then when it’s refetched, the new synthetic query is used.
* * *
To try this out, let's add a sidebar to the page with a filterable contacts list. After all, it wouldn't feel like a properly cozy newsfeed app without the ability to contact people.
We've already prepared a `Sidebar` component, you just need to drop it into `App.tsx`:
```
// change-line
import Sidebar from './Sidebar';
export default function App(): React.ReactElement {
return (
Contacts
{data.contacts.map(contact =>Contacts
// changeContacts
Deep dive: What fragments can be refetched?
To refetch fragments, Relay has to know how to generate a query that lets it refetch just the information from the fragment. That’s only possible for fragments that meet certain requirements. You might imagine that we could, if nothing else, re-run the original query that the fragment was spread into. However, GraphQL doesn’t guarantee that the same query will return the same results at different times. For instance, imagine you had a GraphQL field that returned the top trending posts across the site: ``` query MyQuery { topTrendingPosts { title summary date poster { ...PosterFragment } } } ``` If you wanted to refresh just `PosterFragment` from this query, it wouldn’t work to construct a query like this: ``` query MyQuery { topTrendingPosts { poster { ...PosterFragment } } } ``` ... because the top trending post could be a different post by the time you refresh it! Relay needs a way of identifying the specific node in the graph that the fragment ends up on, even if it can no longer be reached by the same path that the original query uses. If the node has a unique and stable ID, then we can just have a convention for querying for “the graph node with some specific ID” like so: ``` query RefetchQuery { node(id: "abcdef") { ...PosterFragment } } ``` In fact, this is exactly the convention that Relay uses. It expects your server to implement a top-level field called `node` that takes an ID and gives you the graph node with that ID. (We saw `node` earlier with the hovercard example — there it was used to fetch a specific person given their ID using a secondary query.) Not every graph node has a stable ID — some are ephemeral. To be used with `node`, your schema has to declare that its type implements an interface called `Node`: ``` type Person implements Node { id: ID! ... } ``` The `Node` interface simply says it has an ID, but more importantly indicates by convention that that ID is stable and unique: ``` interface Node { id: ID! } ``` import {OssOnly, FbInternalOnly} from 'docusaurus-plugin-internaldocs-fb/internal'; Besides fragments on types that implement `Node`, you can also refetch fragments that are on `Viewer` (since the viewer is assumed to be stable throughout a session) and that are at the top level of a query (since there’s no field above them that could change identity).{data.client_field}
);
}
```
### Arguments
* `query`: GraphQL query specified using a `graphql` template literal.
* `variables`: Object containing the variable values to fetch the query. These variables need to match GraphQL variables declared inside the query.
### Return Value
* `data`: Object that contains data which has been read out from the Relay store; the object matches the shape of specified query.
* The Flow type for data will also match this shape, and contain types derived from the GraphQL Schema. For example, the type of `data` above is: `{| user: ?{| name: ?string |} |}`.
### Behavior
* This hooks works as [`useLazyLoadQuery`](../use-lazy-load-query) with `fetchPolicy: store-only`, it does not send the network request.