ElasticGraph Query API: Pagination

$ curl -s https://block.github.io/elasticgraph/dc.yml | docker compose -f - up --pull always

To provide pagination, ElasticGraph implements the Relay GraphQL Cursor Connections Specification. Here’s an example query showing pagination in action:

query PaginationExample($cursor: Cursor) {
  artists(first: 10, after: $cursor) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        name
        albums {
          name
        }
      }
    }
  }
}

This example uses first:, after:, and pageInfo { hasNextPage, endCursor } to implement forward pagination. If pageInfo.hasNextPage indicates there is another page, the client can pass pageInfo.endCursor as the $cursor value on the next request. Relay backwards pagination is also supported using last:, before:, and pageInfo { hasPreviousPage, startCursor }.

In addition, ElasticGraph offers some additional features beyond the Relay spec.

Total Edge Count

As an extension to the Relay spec, ElasticGraph offers a totalEdgeCount field alongside edges and pageInfo. It can be used to get a total count of matching records:

query Count21stCenturyArtists {
  artists(filter: {
    bio: {yearFormed: {gte: 2000}}
  }) {
    totalEdgeCount
  }
}

Note totalEdgeCount is not available under an aggregations field.

Nodes

As an alternative to edges.node, ElasticGraph offers nodes. This is recommended over edges except when you need a per-node cursor (which is available under edges) since it removes an extra layer of nesting, providing a simpler response structure:

query PaginationNodes($cursor: Cursor) {
  artists(first: 10, after: $cursor) {
    pageInfo {
      hasNextPage
      endCursor
    }
    nodes {
      name
      albums {
        name
      }
    }
  }
}