Pagination Cursors on Connections (Relay Specification)

[litewarp]

Description

UPDATE This PR only contains the first part of the Relay implementation, the pagination cursors. For the node resolution part, see #285.

Added a bunch of features to make the library fully-compatible with Relay. That is:

• Connections now return totalCount, edges, and pageInfo

• Connections now accept pagination arguments using Relay's cursor-based approach while still allowing for limit/offset calculations.

• A Node interface is added which ensures that all types implementing the interface have an id field that is unique

• A root Query field "node" is added allowing users to query a node by its ID and resolve the correct type based on the labels of the node.

Input

type Actor implements Node {
  id: ID! @id
  name: String
  movies: [Movie!]! @relationship(type: "ACTED_IN", properties: "ActedIn", direction: OUT)
}

type Movie implements Node {
  id: ID! @id
  title: String
  actors: [Actor!]! @relationship(type: "ACTED_IN", properties: "ActedIn", direction: IN)
}

interface ActedIn {
  screenTime: Int!
}

Output

# only relevant types shown
# ...

type ActorMoviesConnection {
  edges: [ActorMoviesRelationship!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

input ActorMoviesConnectionOptions {
  sort: [ActorMoviesConnectionSort!]
  first: Int
  after: Cursor
}

"""Opaque cursor used for pagination (Relay)"""
scalar Cursor

type MovieActorsConnection {
  edges: [MovieActorsRelationship!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

input MovieActorsConnectionOptions {
  sort: [MovieActorsConnectionSort!]
  first: Int
  after: Cursor
}

type MovieActorsRelationship implements ActedIn {
  cursor: Cursor!
  node: Actor!
  screenTime: Int!
}

"""Pagination information (Relay)"""
type PageInfo {
    hasNextPage: Boolean!
    hasPreviousPage: Boolean!
    startCursor: Cursor
    endCursor: Cursor
}

"""Globally-identifiable node (Relay)"""
interface Node {
  id: ID!
}

type Query {
  actors(where: ActorWhere, options: ActorOptions): [Actor!]!
  movies(where: MovieWhere, options: MovieOptions): [Movie!]!
  node(id: ID!): Node!
}
# ...

Checklist

The following requirements should have been met (depending on the changes in the branch):

• Documentation has been updated
• TCK tests have been updated
• Integration tests have been updated
• Example applications have been updated
• New files have copyright header
• CLA (https://neo4j.com/developer/cla/) has been signed

[darrellwarde]

First comment is, can you please complete the CLA (https://neo4j.com/developer/cla/) so that we can get the pipeline running and see where we stand? Thanks.

[darrellwarde]

This seems like really great work, thanks for the submission. Honestly, this looks like it should work in practice, but there are a couple of things I would like to see clarified/fixed:

• I believe all node types should implement the Node interface, but this introduces a lot of problems with enforcing the id field, and migrating existing datasets. This was always one of our blockers for doing this now.
• How are cursors calculated? Trying to figure this out as it's not overly clear, and I want to make sure there are no downsides to this approach. We were considering actually storing cursors on relationships as properties.

[litewarp]

• How are cursors calculated? Trying to figure this out as it's not overly clear, and I want to make sure there are no downsides to this approach. We were considering actually storing cursors on relationships as properties.

So the cursors are created based on a base64 transform exported as the helpers below by the graphql-relay-js package:

const PREFIX = 'arrayconnection:';

/**
 * Creates the cursor string from an offset.
 */
export function offsetToCursor(offset: number): ConnectionCursor {
  return base64(PREFIX + offset.toString());
}

/**
 * Extracts the offset from the cursor string.
 */
export function cursorToOffset(cursor: ConnectionCursor): number {
  return parseInt(unbase64(cursor).substring(PREFIX.length), 10);
}

However, this is only one method of generating cursors, although most of the implementations I've seen seem to use base64:

• graphql-compose-connection.
• graphql-relay-go
• nexus relay connection plugin

The key thing is that cursors should be translatable in some way to the offset so that the database call doesn't have to traverse the entire collection to find the subsequent starting point when the user calls for the next group of data.

[darrellwarde]

The key thing is that cursors should be translatable in some way to the offset so that the database call doesn't have to traverse the entire collection to find the subsequent starting point when the user calls for the next group of data.

Thanks for the explanation and references. This makes sense, however one thing I can't quite work out is how this works when data changes between queries. Say you had a query for the first 5 comments of all posts, ordered by their creation timestamp descending:

query {
  posts {
    commentsConnection(options: { first: 5, sort: { node: { createdAt: DESC } } }) {
      edges {
        cursor
        node {
          ...commentFields
        }
      }
    }
  }
}

Say this returns the following 5 posts in descending order the first time around:

1. Post 5 (cursor: "a")
2. Post 4 (cursor: "b")
3. Post 3 (cursor: "c")
4. Post 2 (cursor: "d")
5. Post 1 (cursor: "e")

Now let's say a 6th post is created, and it is at the top of the list because it is the most recently created, I imagine your list would now look like:

1. Post 6 (cursor: "a")
2. Post 5 (cursor: "b")
3. Post 4 (cursor: "c")
4. Post 3 (cursor: "d")
5. Post 2 (cursor: "e")

I might be completely misunderstanding - I only come to this conclusion because if cursors are calculated based on offset, rather than being "saved" on particular relationships (which is what we thought would have to be done), this is how I imagine it will work. If that is the case, would this not be a problem in that the starting point can change in between queries?

[darrellwarde]

First comment is, can you please complete the CLA (https://neo4j.com/developer/cla/) so that we can get the pipeline running and see where we stand? Thanks.

Great, thanks for doing that! Looks like there is just one test failure because of some more recent changes on the 2.0.0 branch - can you please merge those changes from the 2.0.0 into your branch?

[darrellwarde]

Right, I have a bit of a painful request for you, which I hope you won't mind doing.

Would you mind pulling out anything to do with the Node interface and the node query into a different branch and raise a separate PR for that? I think we can all agree that is where the complexity lies here. If we can get that set up, I think we will be able to get the cursor-based pagination side of things reviewed and merged pretty quickly, and we can better focus on how to add support for the node IDs, etc. 🙂

[litewarp]

The key thing is that cursors should be translatable in some way to the offset so that the database call doesn't have to traverse the entire collection to find the subsequent starting point when the user calls for the next group of data.

Thanks for the explanation and references. This makes sense, however one thing I can't quite work out is how this works when data changes between queries. Say you had a query for the first 5 comments of all posts, ordered by their creation timestamp descending:

query {
  posts {
    commentsConnection(options: { first: 5, sort: { node: { createdAt: DESC } } }) {
      edges {
        cursor
        node {
          ...commentFields
        }
      }
    }
  }
}

Say this returns the following 5 posts in descending order the first time around:

1. Post 5 (cursor: "a")
2. Post 4 (cursor: "b")
3. Post 3 (cursor: "c")
4. Post 2 (cursor: "d")
5. Post 1 (cursor: "e")

Now let's say a 6th post is created, and it is at the top of the list because it is the most recently created, I imagine your list would now look like:

1. Post 6 (cursor: "a")
2. Post 5 (cursor: "b")
3. Post 4 (cursor: "c")
4. Post 3 (cursor: "d")
5. Post 2 (cursor: "e")

I might be completely misunderstanding - I only come to this conclusion because if cursors are calculated based on offset, rather than being "saved" on particular relationships (which is what we thought would have to be done), this is how I imagine it will work. If that is the case, would this not be a problem in that the starting point can change in between queries?

So it depends on how your querying is done. Every time there's a change in the query (i.e., sort, or new filters, or new args), cursors will be recalculated on the server and the client will update with those new cursors. In the world where there are no changes, relay knows the order of the list and the number of items so recalculating the position on the client side is doable.

So in terms of "the starting point changing", this would only be an issue on the client when they have not refetched new data (causing recalculation of the cursors). In that case, if you don't want to cause a refetch after a mutation, you can actually manually add the new item to the cache while keeping the cursors consistent by using the Relay connection handler.

If you're using Apollo, they have a field policy helper specifically for relay pagination. I believe urql has similar functionality.

I suppose I don't really understand how storing "cursors" on the relationship lets you do pagination. If a user resorts, you'd have to recreate the entire list of cursors in the order they wanted. And then when you want to start off after a certain cursor, you'd need to traverse through the entire list to find the starting point.

[darrellwarde]

I feel like we're close on this one now that this PR just focuses on pagination. A few points for review, would especially like to see some integration testing for the pagination functionality. Thanks again for the work on this, really great to see! 🙂

[darrellwarde]

The key thing is that cursors should be translatable in some way to the offset so that the database call doesn't have to traverse the entire collection to find the subsequent starting point when the user calls for the next group of data.

Thanks for the explanation and references. This makes sense, however one thing I can't quite work out is how this works when data changes between queries. Say you had a query for the first 5 comments of all posts, ordered by their creation timestamp descending:

query {
  posts {
    commentsConnection(options: { first: 5, sort: { node: { createdAt: DESC } } }) {
      edges {
        cursor
        node {
          ...commentFields
        }
      }
    }
  }
}

Say this returns the following 5 posts in descending order the first time around:

1. Post 5 (cursor: "a")
2. Post 4 (cursor: "b")
3. Post 3 (cursor: "c")
4. Post 2 (cursor: "d")
5. Post 1 (cursor: "e")

Now let's say a 6th post is created, and it is at the top of the list because it is the most recently created, I imagine your list would now look like:

1. Post 6 (cursor: "a")
2. Post 5 (cursor: "b")
3. Post 4 (cursor: "c")
4. Post 3 (cursor: "d")
5. Post 2 (cursor: "e")

I might be completely misunderstanding - I only come to this conclusion because if cursors are calculated based on offset, rather than being "saved" on particular relationships (which is what we thought would have to be done), this is how I imagine it will work. If that is the case, would this not be a problem in that the starting point can change in between queries?

So it depends on how your querying is done. Every time there's a change in the query (i.e., sort, or new filters, or new args), cursors will be recalculated on the server and the client will update with those new cursors. In the world where there are no changes, relay knows the order of the list and the number of items so recalculating the position on the client side is doable.

So in terms of "the starting point changing", this would only be an issue on the client when they have not refetched new data (causing recalculation of the cursors). In that case, if you don't want to cause a refetch after a mutation, you can actually manually add the new item to the cache while keeping the cursors consistent by using the Relay connection handler.

If you're using Apollo, they have a field policy helper specifically for relay pagination. I believe urql has similar functionality.

I suppose I don't really understand how storing "cursors" on the relationship lets you do pagination. If a user resorts, you'd have to recreate the entire list of cursors in the order they wanted. And then when you want to start off after a certain cursor, you'd need to traverse through the entire list to find the starting point.

I guess I'm less thinking about examples where a user is querying the data that they're mutating themselves, but where data has been mutated by another user (another client, so cache wouldn't have updated unless subscriptions are being used, etc.). In this case, the offset could be "changed" between queries by another user inserting data, so when our user resumes pagination from a known cursor, with the same filters, the node that this cursor relates to has now been shifted to the right.

I might be misunderstanding and it's very hard to express my thoughts through text - you seem to have significantly more knowledge of Relay than I do! 🤯

The thinking of having cursors as properties on relationships was in very early stages, so it might have been completely off the mark. But it was less thinking that cursors were related to offsets, so that if more data was inserted at the start of the list, you still get the same node back with the cursor, compared to a particular position in a list with this approach. Yes, you would have to fetch the entire list matching the filter and then slice it down based on the first and after arguments, but this could all easily be done in Cypher which means the Cypher planner should have been able to deal with it quite well.

[litewarp]

Just an FYI. There was a bug with the skipLimitStr function. The correct syntax (as I learned on the discord today) for pagination is [offset..sliceEnd] rather than [offset..limit]. So you need to add the offset to the limit to get the sliceEnd. But some of the input values are Integers so you need to convert them before adding them together.

Also since the offsets start at 0 but the cypher string should start with 1, (e.g., [1..11]) you need to make sure the create-connection-and-params translation increments it by one.

I ended up writing some unit tests for the pagination utilities to help me debug and ensure consistency in the output.

[darrellwarde]

This is really starting to look good now, the only comment that I really have is regarding moving and renaming a test file! I've also asked @danstarns to review this, but it feels to me like we're pretty close here. 🙂

[darrellwarde]

Only one small comment from me now, but this is easily fixed at any point, and everything else looks good to me!

Thanks for your work on this @litewarp, saved us a lot of time and implemented a much requested feature. Will wait for a review from @danstarns before merging.

[darrellwarde]

This should probably be in the translate directory, but we can easily shuffle things around when merged, so not a blocker.

[danstarns]

Hey @litewarp, Am I doing something wrong?

Schema:

type Person {
    name: String
    actedIn: [Movie] @relationship(type: "ACTED_IN", direction: OUT)
}

type Movie {
    title: String
}

Query:

 {
  people {
    name
    actedInConnection {
      edges {
        cursor
        node {
          title
        }
      }
    }
  }
}

Error:

{
  "errors": [
    {
      "message": "Cannot read property 'cursor' of undefined",
      "locations": [
        {
          "line": 4,
          "column": 5
        }
      ],
      "path": [
        "people",
        4,
        "actedInConnection"
      ],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR",
        "exception": {
          "stacktrace": [
            "TypeError: Cannot read property 'cursor' of undefined",
            "    at Object.createConnectionWithEdgeProperties (C:\\code\\neo4j\\graphql\\packages\\graphql\\src\\schema\\pagination.ts:57:36)",
            "    at resolve (C:\\code\\neo4j\\graphql\\packages\\graphql\\src\\schema\\make-augmented-schema.ts:997:32)",
            "    at field.resolve (C:\\code\\neo4j\\graphql\\node_modules\\apollo-server-core\\src\\utils\\schemaInstrumentation.ts:103:18)",
            "    at resolveField (C:\\code\\neo4j\\graphql\\node_modules\\graphql\\execution\\execute.js:464:18)",
            "    at executeFields (C:\\code\\neo4j\\graphql\\node_modules\\graphql\\execution\\execute.js:292:18)",
            "    at collectAndExecuteSubfields (C:\\code\\neo4j\\graphql\\node_modules\\graphql\\execution\\execute.js:748:10)",
            "    at completeObjectValue (C:\\code\\neo4j\\graphql\\node_modules\\graphql\\execution\\execute.js:738:10)",
            "    at completeValue (C:\\code\\neo4j\\graphql\\node_modules\\graphql\\execution\\execute.js:590:12)",
            "    at completeValue (C:\\code\\neo4j\\graphql\\node_modules\\graphql\\execution\\execute.js:556:21)",
            "    at C:\\code\\neo4j\\graphql\\node_modules\\graphql\\execution\\execute.js:620:25"
          ]
        }
      }
    }
  ],
  "data": null
}

[litewarp]

You need to add properties to the relationship. I was actually going to raise this in another PR but the library doesn't create a connection unless there are properties on the relationship.

[danstarns]

You need to add properties to the relationship. I was actually going to raise this in another PR but the library doesn't create a connection unless there are properties on the relationship.

I'm not sure about this, seeming that most of our users are currently not using relationship properties this would mean they couldn't use the cursor. Is this something that can be resolved ? and if so what do you propose?

[darrellwarde]

You need to add properties to the relationship. I was actually going to raise this in another PR but the library doesn't create a connection unless there are properties on the relationship.

I think this was done to minimise the size of the schema, because before this PR there was literally zero value in having the connection types unless relationship properties were defined, but that's obviously all changed now! So we can either do that here, or do it afterwards - my gut says afterwards so that we can get this merged.

[danstarns]

Nice contribution 🍺