GraphQL Pagination

Paging the results of GraphQL queries.

Skedulo GraphQL limits the number of results returned to 200 records per query. You can access additional data by using the pagination support.

It is recommended that you explicitly specify the sorting direction of the orderBy parameter/s by using either ASC for ascending order of results or DESC for descending order, for example: orderBy: Start DESC, UID ASC. To use pagination reliably, you should ensure that your query includes an orderBy: UID parameter so that the result set is stable. In most cases, the sort order direction of the UID is not relevant.

Relay cursor pagination

Skedulo Lens GraphQL pagination support uses the Relay Cursor Connections Specification.

For example, the following query for jobs returns a node for each job consisting of the UID and Name along with an opaque cursor.

{
  jobs(orderBy: "UID") {
      edges {
        cursor
        node {
          UID
          Name
        }
      }
      pageInfo {
        hasNextPage
      }
    }
}

This query would return these results (some data omitted for simplicity):

{
  "data": {
    "jobs": {
      "edges": [
        {
          "cursor": "MQ==",
          "node": {
            "UID": "a0E6F00001dWnbrUAC",
            "Name": "JOB-0033"
          }
        },
        {
          "cursor": "Mg==",
          "node": {
            "UID": "a0E6F00001dWnbhUAC",
            "Name": "JOB-0032"
          }
        }      
      ],
      "pageInfo": {
        "hasNextPage": true
      }
    }
  }
}

Note that this fetches each entry with a cursor. The last entry pageInfo indicates that there is more data to be fetched. This can be done by supplying the cursor of the last item as an argument to the jobs query.

For example:

{
  jobs(after: "Mg==", orderBy: "UID") {
      edges {
        cursor
        node {
          UID
          Name
        }
      }
      pageInfo {
        hasNextPage
      }
    }
}

Would give the result:

{
  "data": {
    "jobs": {
      "edges": [
        {
          "cursor": "Mw==",
          "node": {
            "UID": "a0E6F00001BiaRWUAZ",
            "Name": "JOB-0007"
          }
        },
        {
          "cursor": "NA==",
          "node": {
            "UID": "a0E6F00001BiaRbUAJ",
            "Name": "JOB-0008"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false
      }
    }
  }
}

You can also limit the number of items returned in the query using the first parameter to the “jobs” query.

See the Relay Cursor Connections Specification for full details of the supported operations.

Start and Offset pagination

In addition to the cursor-based paging, Skedulo’s GraphQL implementation also supports using offsets to page results. This can be useful when you want to show pagination controls that allow you to jump ahead in a number of pages, by allowing you to divide into multiples and have the query fetch that many results and render them. To do this we use the offset parameter to indicate which record the pages should be fetched from and the first parameter to indicate the number of records to fetch, for example:

query  {
  jobs(first: 3, offset: 0, orderBy: "UID") {
    edges {
      offset
      node {
        UID
        Name
        Description
        JobStatus
      }
    }
  }
}

Returns the result:

{
  "data": {
    "jobs": {
      "edges": [
        {
          "offset": 0,
          "node": {
            "UID": "0014151a-404c-43bd-ab69-444cf0531e93",
            "Name": "JOB-10",
            "Description": "Stuff 10",
            "JobStatus": "Queued"
          }
        },
        {
          "offset": 1,
          "node": {
            "UID": "0014daaf-ea46-48f3-be2b-13045a953307",
            "Name": "JOB-11",
            "Description": "Stuff 11",
            "JobStatus": "Queued"
          }
        },
        ...
    ]
	}
}