在 GraphQL 中限制頁面大小first

限制頁面大小可防止在查詢大型資料集時導致用戶端或伺服器不堪重負。 在 GraphQL 中，資料 API 產生器 （DAB） 會使用 first 引數來控制單一回應中傳回的記錄數目。 DAB 會在內部套用游標型分頁，但 first 可以獨立使用，以簡單地限制結果大小。

備註

first 限制傳回的記錄數目，但本身不會處理接續。 對於多個頁面，請使用 after。

轉到 本文檔的REST版本。

概觀

概念	Description
默認頁面大小	runtime.pagination.default-page-size （預設為 100）
頁面大小上限	runtime.pagination.max-page-size （預設為 100000）
用戶端覆寫	first
請求最大值	傳遞 -1 以要求設定的頁面大小上限

如果省略，則 first 預設頁面大小會自動套用。

使用模式

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

Example

將結果限制為五本書。

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

概念性 SQL

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

範例回應

{
  "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" }
      ]
    }
  }
}

驗證規則

Input	Result
省略	用途 default-page-size
正整數≤最大值	已接受
-1	擴展至 max-page-size
0	錯誤 （無效）
< -1	錯誤
> max-page-size	錯誤

錯誤訊息範例

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

範例設定

{
  "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" ]
        }
      }
    }
  }
}

另請參閱

概念	REST	GraphQL	目標
Projection	$select	項目	選擇要傳回的欄位
篩選	$filter	篩選	依條件限制資料列
排序	$orderby	orderBy	定義排序順序
頁面大小	$first	first	限制每頁的項目數
繼續	$after	後	使用游標從最後一頁繼續

備註

REST 關鍵字會遵循 OData 慣例，以 開 $頭。