Azure / Azure/data-api-builder
[Enh]: New pagination keywords
- 主要言語
- C#
- スター
- 1.5k
- フォーク
- 370
- 平均マージ
- 3日 22時間
- マージ済み PR(30日)
- 9
説明
## 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;
```
コントリビューションガイド
調査の方向性
まず、DAB が現在、既存のキーワード $first と $after をどのように評価しているか、また設定されたページサイズの値がどのように適用されているかを追跡します。T-SQL の例を、優先順位、デフォルト、無効な組み合わせ、負の値を含む動作ケースとして使用します。$pageSize と $pageNumber が指定された組み合わせで機能し、既存のキーワードの動作と NextLink の検出を維持できれば完了です。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- csharp, sql
- 領域
- api, backend-api-design, databases
- issue の種類
- 機能追加
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 停滞
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 35/100