Azure / Azure/data-api-builder

[Enh]: Pagination metadata in response results

Aperta
#2,459 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub
2.2 enhancement graphql mcp-server rest
Lingua principale
C#
Stelle
1.5k
Fork
370
Merge medio
3g 22h
PR unite (30g)
9

Descrizione

## What?

```json
{
"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

```json
{
"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

```graphql
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

```json
{
"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

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

Result

```json
{
"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
}
}
```

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Inizia tracciando i percorsi delle richieste read_records REST, GraphQL e MCP descritti nell’issue. Determina come ciascuna superficie applica la paginazione e i filtri, quindi implementa metadati di paginazione coerenti e verifica le strutture delle risposte documentate, inclusi i metadati null per l’esempio GraphQL quando i totali non sono disponibili.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
csharp, graphql
Ambito
api, backend-api-design, databases
Tipo di issue
Funzionalità
Difficoltà
5/5
Tempo stimato
Più di una settimana
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.