Pagination

Overview

The Finale GraphQL API uses cursor-based pagination following the Relay connection specification. This provides efficient navigation through large datasets.

Pagination Arguments

All ViewConnection queries support these arguments:

first: Int - Return the first N items
last: Int - Return the last N items
after: String - Return items after this cursor
before: String - Return items before this cursor

PageInfo Object

Every ViewConnection returns a pageInfo object with:

pageInfo {
  hasNextPage      # Boolean: Are there more items after this page?
  hasPreviousPage  # Boolean: Are there items before this page?
  startCursor      # String: Cursor for first item in results
  endCursor        # String: Cursor for last item in results
}

Forward Pagination Pattern

To paginate forward through results:

# Page 1
query {
  orderViewConnection(first: 50) {
    edges {
      node {
        orderId
        orderDate
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Page 2 - Use endCursor from previous page
query {
  orderViewConnection(first: 50, after: "cursor-value-from-page-1") {
    edges {
      node {
        orderId
        orderDate
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Backward Pagination Pattern

To paginate backward:

query {
  orderViewConnection(last: 50, before: "cursor-value") {
    edges {
      node {
        orderId
        orderDate
      }
    }
    pageInfo {
      hasPreviousPage
      startCursor
    }
  }
}

Cursor Format

Cursors are opaque strings that encode pagination position. They are:

Base64-encoded JSON objects
Should be treated as opaque by clients
Valid only within the same query context
Not guaranteed to be stable across different queries

Example cursor value: eyJpZHgiOjEwfQ==

Best Practices

Always check hasNextPage before requesting more pages
Store cursors from pageInfo to navigate between pages
Use consistent page size for predictable performance
Don't decode cursors - treat them as opaque strings
Combine with sorting for predictable pagination order

Complete Example

query GetProducts($cursor: String) {
  productViewConnection(
    first: 100
    after: $cursor
    sort: [{ field: "productId", mode: "asc" }]
  ) {
    edges {
      node {
        productId
        sku
        description
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}