Membatasi ukuran halaman dengan first di GraphQL

Membatasi ukuran halaman mencegah klien atau server yang luar biasa saat mengkueri himpunan data besar. Di GraphQL, Penyusun API Data (DAB) menggunakan first argumen untuk mengontrol berapa banyak rekaman yang dikembalikan dalam satu respons. DAB menerapkan paginasi berbasis kursor secara internal, tetapi first dapat digunakan secara independen untuk hanya menutup ukuran hasil.

Nota

first membatasi jumlah rekaman yang dikembalikan tetapi tidak menangani kelanjutan. Untuk beberapa halaman, gunakan after.

Buka versi REST dokumen ini.

Gambaran Umum

Konsep	Description
Ukuran halaman bawaan	runtime.pagination.default-page-size (default ke 100)
Ukuran halaman maks	runtime.pagination.max-page-size (default ke 100000)
Penimpaan klien	first
Meminta maks	Teruskan -1 untuk meminta ukuran halaman maks yang dikonfigurasi

Jika first dihilangkan, ukuran halaman default berlaku secara otomatis.

Pola penggunaan

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

Example

Batasi hasilnya hingga lima buku.

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

SQL Konseptual

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

Contoh tanggapan

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

Aturan validasi

Masukan	Result
Dihilangkan	Menggunakan default-page-size
Bilangan bulat positif ≤ maks	Diterima
-1	Diperluas ke max-page-size
0	Kesalahan (tidak valid)
< -1	Kesalahan
> max-page-size	Kesalahan

Contoh pesan kesalahan

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

Konfigurasi contoh

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

Lihat juga

Konsep	REST	GraphQL	Tujuan
Projection	$select	items	Pilih bidang mana yang akan dikembalikan
Penyaringan	$filter	saringan	Membatasi baris menurut kondisi
Pengurutan	$orderby	orderBy	Tentukan urutan pengurutan
Ukuran halaman	$first	first	Membatasi jumlah item per halaman
Kelanjutan	$after	sesudah	Lanjutkan dari halaman terakhir menggunakan kursor

Nota

Kata kunci REST dimulai dengan $, mengikuti konvensi OData.