Azure / Azure/data-api-builder

[Enh]: New pagination keywords

Đang mở
#3,198 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
2.2 enhancement graphql mcp-server rest usability
Ngôn ngữ chính
C#
Star
1.5k
Fork
370
Merge trung bình
3 ngày 22 giờ
Pull request đã merge (30 ngày)
9

Mô tả

## Existing, unchanged keywords

* `$first`: return the first N items, similar to SQL `TOP`.
* `$after`: return items after this cursor; not offset-based.

## New keywords

* `$pageSize`: number of records per page
* `$pageNumber`: numeric page index (1-based)

### Default behavior

* `$pageSize` defaults to the configured DAB `page-size` value if not specified.
* `$pageNumber` defaults to `1` if not specified.

### Evaluation precedence

`$after → $pageSize → $pageNumber → $first`

They can all be used together.

## Keywords not being added

I include this section of the specification because these keywords were part of previous conversations and specifications. However, we are not going to add them anymore because they are redundant.

* `$take`: semantically identical to `$first`.
* `$skip`: semantically equivalent to `$pageSize` + `$pageNumber`. For example, `$skip=10` can be expressed as `$pageSize=5` and `$pageNumber=3`. Skip behavior can also be achieved using `$after`, optionally combined with `$first`.

## Examples in TSQL

```sql
-- Example 1: All parameters NULL (no paging applied)

DECLARE @First int = NULL;
DECLARE @After int = NULL;
DECLARE @PageSize int = NULL;
DECLARE @PageNumber int = NULL;

SELECT *
FROM dbo.Actor
ORDER BY Id;
```

```sql
-- Example 2: Page model ($pageSize + $pageNumber)
-- DAB requests PageSize + 1 to determine NextLink

DECLARE @First int = NULL;
DECLARE @After int = NULL;
DECLARE @PageSize int = 5;
DECLARE @PageNumber int = 3;

SELECT *
FROM dbo.Actor
ORDER BY Id
OFFSET (@PageNumber - 1) * @PageSize ROWS
FETCH NEXT (@PageSize + 1) ROWS ONLY;
```

```sql
-- Example 3: $pageSize only (defaults pageNumber = 1)
-- DAB fetches PageSize + 1 for NextLink detection

DECLARE @First int = NULL;
DECLARE @After int = NULL;
DECLARE @PageSize int = 5;
DECLARE @PageNumber int = NULL;

SET @PageNumber = ISNULL(@PageNumber, 1);

SELECT *
FROM dbo.Actor
ORDER BY Id
OFFSET (@PageNumber - 1) * @PageSize ROWS
FETCH NEXT (@PageSize + 1) ROWS ONLY;
```

```sql
-- Example 4: Cursor model ($first only)
-- DAB fetches First + 1 for NextLink detection

DECLARE @First int = 5;
DECLARE @After int = NULL;
DECLARE @PageSize int = NULL;
DECLARE @PageNumber int = NULL;

SELECT TOP (@First + 1) *
FROM dbo.Actor
ORDER BY Id;
```

```sql
-- Example 5: Cursor model ($first + $after)
-- DAB fetches First + 1 for NextLink detection

DECLARE @First int = 5;
DECLARE @After int = 10; -- simplified for this example
DECLARE @PageSize int = NULL;
DECLARE @PageNumber int = NULL;

SELECT TOP (@First + 1) *
FROM dbo.Actor
WHERE Id > @After
ORDER BY Id;
```

```sql
-- Example 6: $after + $pageSize
-- DAB fetches PageSize + 1 for NextLink detection

DECLARE @First int = NULL;
DECLARE @After int = 10; -- simplified for this example
DECLARE @PageSize int = 5;
DECLARE @PageNumber int = NULL;

SELECT TOP (@PageSize + 1) *
FROM dbo.Actor
WHERE Id > @After
ORDER BY Id;
```

```sql
-- Example 7: $first + $pageSize + $pageNumber
-- Page window fetches PageSize + 1
-- Final limiter applies after trimming NextLink row

DECLARE @First int = 2;
DECLARE @After int = NULL;
DECLARE @PageSize int = 5;
DECLARE @PageNumber int = 3;

WITH Paged AS
(
SELECT *
FROM dbo.Actor
ORDER BY Id
OFFSET (@PageNumber - 1) * @PageSize ROWS
FETCH NEXT (@PageSize + 1) ROWS ONLY
)
SELECT TOP (@First)
*
FROM Paged
ORDER BY Id;
```

```sql
-- Example 8: ⛔ Incompatible: $after + $pageNumber

DECLARE @First int = NULL;
DECLARE @After int = 10; -- simplified for this example
DECLARE @PageSize int = NULL;
DECLARE @PageNumber int = 2;

IF @After IS NOT NULL AND @PageNumber IS NOT NULL
THROW 50000, '$after cannot be combined with $pageNumber.', 1;
```

```sql
-- Example 9: ⛔ Invalid: $pageNumber without $pageSize

DECLARE @First int = NULL;
DECLARE @After int = NULL;
DECLARE @PageSize int = NULL;
DECLARE @PageNumber int = 2;

IF @PageNumber IS NOT NULL AND @PageSize IS NULL
THROW 50000, '$pageNumber requires $pageSize.', 1;
```

```sql
-- Example 10: ⛔ Invalid negative values

DECLARE @First int = -5;
DECLARE @After int = NULL;
DECLARE @PageSize int = -10;
DECLARE @PageNumber int = NULL;

IF @First IS NOT NULL AND @First <= 0
THROW 50000, '$first must be greater than zero.', 1;

IF @PageSize IS NOT NULL AND @PageSize <= 0
THROW 50000, '$pageSize must be greater than zero.', 1;
```

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Bắt đầu bằng cách theo dõi cách DAB hiện đánh giá các từ khóa hiện có $first và $after, cũng như cách giá trị kích thước trang được cấu hình được áp dụng. Sử dụng các ví dụ T-SQL làm các trường hợp hành vi, bao gồm thứ tự ưu tiên, giá trị mặc định, các tổ hợp không hợp lệ và các giá trị âm. Được xem là hoàn tất khi $pageSize và $pageNumber hoạt động với các tổ hợp được chỉ định, đồng thời duy trì hành vi hiện có của các từ khóa và việc phát hiện NextLink.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
csharp, sql
Lĩnh vực
api, backend-api-design, databases
Loại issue
Tính năng
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
35/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.