[Enh]: Pagination metadata in response results

[JerryNixon]

What?

{
  "paging": {
    "page_number": 2,
    "page_size": 5,
    "page_count": 6,
    "element_count": 30,
    "is_first": false,
    "is_last": false
  }
}

Element	Type	Description
page_number	integer	The current page index, 1-based.
page_size	integer	The number of records requested per page. Reflects the effective page size after defaults or limits are applied.
page_count	integer	Total number of pages available for the query. Calculated as element_count / page_size, rounded up.
element_count	integer	Total number of records matching the query filter. Determined using a COUNT(*) over the same filtered dataset.
is_first	boolean	Indicates whether the current page is the first page. true when page_number = 1.
is_last	boolean	Indicates whether the current page is the final page. true when page_number = page_count.

Why?

To help app developers who are building interactive user interfaces.

REST example

New query string keyword $page-metadata=true

Request

GET /api/books?$pageSize=5&$pageNumber=2&$page-metadata=true

Response

{
  "value": [
    { "id": 6, "title": "Dune Messiah", "author": "Frank Herbert", "year": 1969 },
    { "id": 7, "title": "Children of Dune", "author": "Frank Herbert", "year": 1976 },
    { "id": 8, "title": "God Emperor of Dune", "author": "Frank Herbert", "year": 1981 },
    { "id": 9, "title": "Heretics of Dune", "author": "Frank Herbert", "year": 1984 },
    { "id": 10, "title": "Chapterhouse: Dune", "author": "Frank Herbert", "year": 1985 }
  ],
  "paging": {
    "page_number": 2,
    "page_size": 5,
    "page_count": 6,
    "element_count": 30,
    "is_first": false,
    "is_last": false
  }
}

GraphQL example

New built-in type pagingMetadata

Query

query {
  books(first: 5, after: 10) {
    items {
      id
      title
      author
      year
    }
    pagingMetadata {
      page_number
      page_size
      page_count
      element_count
      is_first
      is_last
    }
  }
}

Response

{
  "data": {
    "books": {
      "items": [
        { "id": 11, "title": "Foundation", "author": "Isaac Asimov", "year": 1951 },
        { "id": 12, "title": "Foundation and Empire", "author": "Isaac Asimov", "year": 1952 },
        { "id": 13, "title": "Second Foundation", "author": "Isaac Asimov", "year": 1953 },
        { "id": 14, "title": "Foundation's Edge", "author": "Isaac Asimov", "year": 1982 },
        { "id": 15, "title": "Foundation and Earth", "author": "Isaac Asimov", "year": 1986 }
      ],
      "paging": {
        "page_number": null,
        "page_size": 5,
        "page_count": null,
        "element_count": null,
        "is_first": null,
        "is_last": null
      }
    }
  }
}

MCP read_records example

New method parameter includePageMetadata

Tool call

{
  "tool": "read_records",
  "arguments": {
    "table": "books",
    "pageSize": 5,
    "pageNumber": 2,
    "includePageMetadata": true
  }
}

Result

{
  "records": [
    { "id": 6, "title": "Dune Messiah", "author": "Frank Herbert", "year": 1969 },
    { "id": 7, "title": "Children of Dune", "author": "Frank Herbert", "year": 1976 },
    { "id": 8, "title": "God Emperor of Dune", "author": "Frank Herbert", "year": 1981 },
    { "id": 9, "title": "Heretics of Dune", "author": "Frank Herbert", "year": 1984 },
    { "id": 10, "title": "Chapterhouse: Dune", "author": "Frank Herbert", "year": 1985 }
  ],
  "paging": {
    "page_number": 2,
    "page_size": 5,
    "page_count": 6,
    "element_count": 30,
    "is_first": false,
    "is_last": false
  }
}

[002127-lucianopena]

Hi Jerry, This improvement hasn't been made yet, right?

[talynone]

I could really use this enhancement, ran into this issue today. My dataset has no numerical columns so even the groupby work-around wouldn't work.