June 02, 2017

Relay Modern’s @connection directive

The @connection directive is new to Relay Modern and unfortunately doesn’t have any official documentation. In this article, we want to give a brief overview on how to use it.

If you tried to get started with Relay Modern yourself, chances are you came across the updated Todo Example project on GitHub. If you’ve also studied the mutations in that project, you might have noticed the @connection directive that you need to specify when querying lists of items.

This directive is new to Relay Modern and unfortunately doesn’t have any official documentation yet. In this article, we want to give a brief overview on how to use it.

In Relay, lists are represented through the concept of connections. This facilitates the implementation of a cursor-based pagination approach on the client.

The @connection directive takes two arguments:

  • key: specifies how Relay will refer to this connection in its internal cache
  • filter: represents an array of constraints that are used to filter the items in the connection

Let’s take a look at how the directive is used in the Todo example:


export default createFragmentContainer(TodoList, {
viewer: graphql`
fragment TodoList_viewer on User {
first: 2147483647 # max GraphQLInt
) @connection(key: "TodoList_todos") {
edges {
node {

In TodoList.js, the data dependencies for the TodoList component are declared in the form of a GraphQL fragment. todos refers to a connection that's defined in the GraphQL schema. When requesting the items from this list, the @connection directive is used alongside the todos field. Relay will use the specified key TodoList_todos in its internal cache to refer to that connection.


function sharedUpdater(store, user, newEdge) {
const userProxy = store.get(user.id)
const conn = ConnectionHandler.getConnection(userProxy, 'TodoList_todos')
ConnectionHandler.insertEdgeAfter(conn, newEdge)

The key is used again in AddTodoMutation.js. This time, its purpose is to pull the connection from the internal cache using the ConnectionHandler API. The key is passed to the call to ConnectionHandler.getConnection(...). This allows to retrieve the list from the cache and update it manually with the new todo item that was created through the mutation.

Don’t miss the next post!

Sign up for the Prisma Newsletter

SQLite on the Edge: Prisma Support for Turso is in Early Access

September 28, 2023

Turso is an edge-hosted, distributed database that's based on libSQL, an open-source and open-contribution fork of SQLite, enabling you to bring data closer to your application and minimize query latency.

We’re excited to share that Prisma ORM is adding Early Access support for Turso. Let’s dive in!

Accelerate in Preview: Global Database Cache & Scalable Connection Pool

August 10, 2023

Prisma Accelerate is now available to everyone in Preview! Make your application faster with our powerful global cache and scalable connection pooler. Get started now, and let us know what you think.