mirror of
https://github.com/ent/ent.git
synced 2026-04-28 13:40:56 +03:00
217 lines
6.6 KiB
Markdown
Executable File
217 lines
6.6 KiB
Markdown
Executable File
---
|
|
id: tutorial-todo-gql-paginate
|
|
title: Relay Cursor Connections (Pagination)
|
|
sidebar_label: Relay Cursor Connections
|
|
---
|
|
|
|
In this section, we continue the [GraphQL example](tutorial-todo-gql.md) by explaining how to implement the
|
|
[Relay Cursor Connections Spec](https://relay.dev/graphql/connections.htm). If you're not familiar with the
|
|
Cursor Connections interface, read the following paragraphs that were taken from [relay.dev](https://relay.dev/graphql/connections.htm#sel-DABDDDAADFA0E3kM):
|
|
|
|
> 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:
|
|
> ```graphql
|
|
> {
|
|
> user {
|
|
> id
|
|
> name
|
|
> friends(first: 10, after: "opaqueCursor") {
|
|
> edges {
|
|
> cursor
|
|
> node {
|
|
> id
|
|
> name
|
|
> }
|
|
> }
|
|
> pageInfo {
|
|
> hasNextPage
|
|
> }
|
|
> }
|
|
> }
|
|
> }
|
|
> ```
|
|
|
|
#### Clone the code (optional)
|
|
|
|
The code for this tutorial is available under [github.com/a8m/ent-graphql-example](https://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:
|
|
|
|
```console
|
|
git clone git@github.com:a8m/ent-graphql-example.git
|
|
cd ent-graphql-example
|
|
go run ./cmd/todo/
|
|
```
|
|
|
|
|
|
## Add Annotations To Schema
|
|
|
|
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.
|
|
|
|
```go title="ent/schema/todo.go"
|
|
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"),
|
|
),
|
|
}
|
|
}
|
|
```
|
|
|
|
## Add Pagination Support For Query
|
|
|
|
1\. The next step for enabling pagination is to tell Ent that the `Todo` type is a Relay Connection.
|
|
|
|
```go title="ent/schema/todo.go"
|
|
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()`:
|
|
|
|
```go title="ent.resolvers.go" {2-5}
|
|
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:
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
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:
|
|
|
|
```diff
|
|
-children: [Todo!]!
|
|
+children(first: Int, last: Int, after: Cursor, before: Cursor): TodoConnection!
|
|
```
|
|
|
|
:::
|
|
|
|
## Pagination Usage
|
|
|
|
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):
|
|
|
|
```graphql
|
|
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:
|
|
|
|
```graphql
|
|
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.
|
|
|
|
```graphql
|
|
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.
|