Limiting page size with first in GraphQL

Limiting page size prevents overwhelming clients or servers when querying large datasets. In GraphQL, Data API builder (DAB) uses the first argument to control how many records are returned in a single response. DAB applies cursor-based pagination internally, but first can be used independently to simply cap result size.

Go to the REST version of this document.

Overview

If first is omitted, the default page size applies automatically.

Usage pattern

query {
  books(first: N) {
    items { id title }
  }
}

Example

Limit the results to five books.

query {
  books(first: 5) {
    items {
      id
      title
    }
  }
}

Conceptual SQL

SELECT TOP (5)
  id,
  sku_title AS title
FROM dbo.books
ORDER BY id ASC;

Sample response

{
  "data": {
    "books": {
      "items": [
        { "id": 1, "title": "Dune" },
        { "id": 2, "title": "Foundation" },
        { "id": 3, "title": "Hyperion" },
        { "id": 4, "title": "I, Robot" },
        { "id": 5, "title": "The Martian" }
      ]
    }
  }
}

Validation rules

Example error message

Invalid number of items requested, first argument must be either -1 or a positive number within the max page size limit of 100000. Actual value: 0

Example configuration

{
  "runtime": {
    "pagination": {
      "default-page-size": 100,
      "max-page-size": 100000
    }
  },
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.books"
      },
      "mappings": {
        "sku_title": "title",
        "sku_price": "price"
      },
      "relationships": {
        "book_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      }
    },
    "Category": {
      "source": {
        "type": "table",
        "object": "dbo.categories"
      },
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

See also