id | title | sidebar_label |
---|---|---|
tutorial-todo-gql-paginate |
Relay Cursor Connections (Pagination) |
Relay Cursor Connections |
In this section, we continue the GraphQL example by explaining how to implement the Relay Cursor Connections Spec. If you're not familiar with the Cursor Connections interface, read the following paragraphs that were taken from relay.dev:
In the query, the connection model provides a standard mechanism for slicing and paginating the result set.
In the response, the connection model provides a standard way of providing cursors, and a way of telling the client when more results are available.
An example of all four of those is the following query:
{ user { id name friends(first: 10, after: "opaqueCursor") { edges { cursor node { id name } } pageInfo { hasNextPage } } } }
The code for this tutorial is available under github.com/a8m/ent-graphql-example, and tagged (using Git) in each step. If you want to skip the basic setup and start with the initial version of the GraphQL server, you can clone the repository as follows:
git clone git@github.com:a8m/ent-graphql-example.git
cd ent-graphql-example
go run ./cmd/todo/
Ordering can be defined on any comparable field of Ent by annotating it with entgql.Annotation
.
Note that the given OrderField
name must be uppercase and match its enum value in the GraphQL schema.
func (Todo) Fields() []ent.Field {
return []ent.Field{
field.Text("text").
NotEmpty().
Annotations(
entgql.OrderField("TEXT"),
),
field.Time("created_at").
Default(time.Now).
Immutable().
Annotations(
entgql.OrderField("CREATED_AT"),
),
field.Enum("status").
NamedValues(
"InProgress", "IN_PROGRESS",
"Completed", "COMPLETED",
).
Default("IN_PROGRESS").
Annotations(
entgql.OrderField("STATUS"),
),
field.Int("priority").
Default(0).
Annotations(
entgql.OrderField("PRIORITY"),
),
}
}
1. The next step for enabling pagination is to tell Ent that the Todo
type is a Relay Connection.
func (Todo) Annotations() []schema.Annotation {
return []schema.Annotation{
//highlight-next-line
entgql.RelayConnection(),
entgql.QueryField(),
entgql.Mutations(entgql.MutationCreate()),
}
}
2. Then, run go generate .
and you'll notice that ent.resolvers.go
was changed. Head over to the Todos
resolver
and update it to pass pagination arguments to .Paginate()
:
func (r *queryResolver) Todos(ctx context.Context, after *ent.Cursor, first *int, before *ent.Cursor, last *int, orderBy *ent.TodoOrder) (*ent.TodoConnection, error) {
return r.client.Todo.Query().
Paginate(ctx, after, first, before, last,
ent.WithTodoOrder(orderBy),
)
}
:::info Relay Connection Configuration
The entgql.RelayConnection()
function indicates that the node or edge should support pagination.
Hence,the returned result is a Relay connection rather than a list of nodes ([T!]!
=> <T>Connection!
).
Setting this annotation on schema T
(reside in ent/schema), enables pagination for this node and therefore, Ent will
generate all Relay types for this schema, such as: <T>Edge
, <T>Connection
, and PageInfo
. For example:
func (Todo) Annotations() []schema.Annotation {
return []schema.Annotation{
entgql.RelayConnection(),
entgql.QueryField(),
}
}
Setting this annotation on an edge indicates that the GraphQL field for this edge should support nested pagination and the returned type is a Relay connection. For example:
func (Todo) Edges() []ent.Edge {
return []ent.Edge{
edge.To("parent", Todo.Type).
Unique().
From("children").
Annotation(entgql.RelayConnection()),
}
}
The generated GraphQL schema will be:
-children: [Todo!]!
+children(first: Int, last: Int, after: Cursor, before: Cursor): TodoConnection!
:::
Now, we're ready to test our new GraphQL resolvers. Let's start with creating a few todo items by running this query multiple times (changing variables is optional):
mutation CreateTodo($todo: TodoInput!) {
createTodo(todo: $todo) {
id
text
createdAt
priority
parent {
id
}
}
}
# Query Variables: { "todo": { "text": "Create GraphQL Example", "status": "IN_PROGRESS", "priority": 1 } }
# Output: { "data": { "createTodo": { "id": "2", "text": "Create GraphQL Example", "createdAt": "2021-03-10T15:02:18+02:00", "priority": 1, "parent": null } } }
Then, we can query our todo list using the pagination API:
query {
todos(first: 3, orderBy: {direction: DESC, field: TEXT}) {
edges {
node {
id
text
}
cursor
}
}
}
# Output: { "data": { "todos": { "edges": [ { "node": { "id": "16", "text": "Create GraphQL Example" }, "cursor": "gqFpEKF2tkNyZWF0ZSBHcmFwaFFMIEV4YW1wbGU" }, { "node": { "id": "15", "text": "Create GraphQL Example" }, "cursor": "gqFpD6F2tkNyZWF0ZSBHcmFwaFFMIEV4YW1wbGU" }, { "node": { "id": "14", "text": "Create GraphQL Example" }, "cursor": "gqFpDqF2tkNyZWF0ZSBHcmFwaFFMIEV4YW1wbGU" } ] } } }
We can also use the cursor we got in the query above to get all items that come after it.
query {
todos(first: 3, after:"gqFpEKF2tkNyZWF0ZSBHcmFwaFFMIEV4YW1wbGU", orderBy: {direction: DESC, field: TEXT}) {
edges {
node {
id
text
}
cursor
}
}
}
# Output: { "data": { "todos": { "edges": [ { "node": { "id": "15", "text": "Create GraphQL Example" }, "cursor": "gqFpD6F2tkNyZWF0ZSBHcmFwaFFMIEV4YW1wbGU" }, { "node": { "id": "14", "text": "Create GraphQL Example" }, "cursor": "gqFpDqF2tkNyZWF0ZSBHcmFwaFFMIEV4YW1wbGU" }, { "node": { "id": "13", "text": "Create GraphQL Example" }, "cursor": "gqFpDaF2tkNyZWF0ZSBHcmFwaFFMIEV4YW1wbGU" } ] } } }
Great! With a few simple changes, our application now supports pagination. Please continue to the next section where we explain how to implement GraphQL field collections and learn how Ent solves the "N+1 problem" in GraphQL resolvers.