Memfilter data di GraphQL (filter)

Pemfilteran mempersempit himpunan data besar hanya ke rekaman yang Anda butuhkan. Di GraphQL, penyusun API Data (DAB) mendukung argumen terstruktur filter pada kueri entitas. Setiap filter dikompilasi ke SQL berparameter untuk keamanan dan konsistensi.

Nota

Pemfilteran GraphQL mendukung perbandingan, logis, pola string, keanggotaan, dan operator null. Filter GraphQL menggunakan objek input terstruktur: { fieldName: { operator: value } }. Tanggal harus berupa string UTC ISO 8601 yang valid. Pemeriksaan null menggunakan isNull alih-alih eq null.

Sekilas

Operator Meaning
eq sama
neq Tidak setara
gt lebih dari
gte lebih dari atau sama
lt kurang dari
lte kurang dari atau sama
and logis AND
or logis OR
contains kecocokan substring
notContains tidak kecocokan substring
startsWith kecocokan awalan
endsWith kecocokan akhiran
in keanggotaan
isNull pemeriksaan null

eq

Sama dengan. Mengembalikan rekaman di mana nilai bidang sama persis dengan harfiah yang disediakan atau null jika menggunakan isNull.

Nota

Saat memfilter bidang tanggal atau tanggalwaktu, gunakan format UTC ISO 8601 yang tidak dikutip (yyyy-MM-ddTHH:mm:ssZ). Format gaya kutipan atau OData tidak valid.

  • Salah: $filter=Date ge '2025-01-01'
  • Salah: $filter=Date ge datetime'2025-01-01'
  • Benar: $filter=Date ge 2025-01-01T00:00:00Z

Dalam contoh ini, kita mendapatkan buku dengan judul 'Dune', bendera yang tersedia benar, harganya adalah 20, tanggal yang diterbitkan adalah 1 Januari 2024, dan peringkatnya null.

query {
  books(filter: {
    and: [
      { title: { eq: "Dune" } }
      { available: { eq: true } }
      { price: { eq: 20 } }
      { publishedOn: { eq: "2024-01-01T00:00:00Z" } }
      { rating: { isNull: true } }
    ]
  }) {
    items { id title available price publishedOn rating }
  }
}

SQL Konseptual

SELECT id, title, available, price, publishedOn, rating
FROM Books
WHERE title = 'Dune'
  AND available = 1
  AND price = 20
  AND publishedOn = '2024-01-01T00:00:00Z'
  AND rating IS NULL;

neq

Tidak sama dengan. Mengembalikan rekaman di mana nilai bidang tidak cocok dengan harfiah atau tidak null saat dikombinasikan dengan isNull: false.

Dalam contoh ini, kami mendapatkan buku yang judulnya tidak 'Foundation', bendera yang tersedia tidak salah, harganya bukan nol, tanggal yang diterbitkan bukan 31 Desember 2023, dan peringkatnya tidak null.

query {
  books(filter: {
    and: [
      { title: { neq: "Foundation" } }
      { available: { neq: false } }
      { price: { neq: 0 } }
      { publishedOn: { neq: "2023-12-31T00:00:00Z" } }
      { rating: { isNull: false } }
    ]
  }) {
    items { id title available price publishedOn rating }
  }
}

SQL Konseptual

SELECT id, title, available, price, publishedOn, rating
FROM Books
WHERE title <> 'Foundation'
  AND available <> 0
  AND price <> 0
  AND publishedOn <> '2023-12-31T00:00:00Z'
  AND rating IS NOT NULL;

gt

Lebih besar dari. Mengembalikan rekaman di mana nilai bidang secara ketat lebih tinggi dari harfiah yang disediakan.

Dalam contoh ini, kita mendapatkan buku yang judulnya diurutkan menurut abjad setelah 'A', bendera yang tersedia benar, harganya lebih besar dari 10, dan tanggal yang diterbitkan setelah 1 Januari 2020.

query {
  books(filter: {
    and: [
      { title: { gt: "A" } }
      { available: { gt: false } }
      { price: { gt: 10 } }
      { publishedOn: { gt: "2020-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL Konseptual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title > 'A'
  AND available > 0
  AND price > 10
  AND publishedOn > '2020-01-01T00:00:00Z';

gte

Lebih besar dari atau sama dengan. Mengembalikan rekaman di mana nilai bidang lebih tinggi dari atau sama dengan literal yang diberikan.

Dalam contoh ini, kita mendapatkan buku yang judulnya 'A' atau lebih baru, bendera yang tersedia benar, harganya setidaknya 10, dan tanggal yang diterbitkan adalah pada atau setelah 1 Januari 2020.

query {
  books(filter: {
    and: [
      { title: { gte: "A" } }
      { available: { gte: false } }
      { price: { gte: 10 } }
      { publishedOn: { gte: "2020-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL Konseptual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title >= 'A'
  AND available >= 0
  AND price >= 10
  AND publishedOn >= '2020-01-01T00:00:00Z';

lt

Kurang. Mengembalikan rekaman di mana nilai bidang benar-benar lebih rendah dari literal yang diberikan.

Dalam contoh ini, kita mendapatkan buku yang judulnya diurutkan sebelumnya 'Z', bendera yang tersedia salah, harganya kurang dari 50, dan tanggal yang diterbitkan adalah sebelum 1 Januari 2030.

query {
  books(filter: {
    and: [
      { title: { lt: "Z" } }
      { available: { lt: true } }
      { price: { lt: 50 } }
      { publishedOn: { lt: "2030-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL Konseptual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title < 'Z'
  AND available < 1
  AND price < 50
  AND publishedOn < '2030-01-01T00:00:00Z';

lte

Kurang dari atau sama dengan. Mengembalikan rekaman di mana nilai bidang lebih rendah dari atau sama dengan harfiah yang diberikan.

Dalam contoh ini, kita mendapatkan buku yang judulnya diurutkan 'Z'sebelum atau sama dengan , bendera yang tersedia benar, harganya adalah 100 atau kurang, dan tanggal yang diterbitkan pada atau sebelum 1 Januari 2030.

query {
  books(filter: {
    and: [
      { title: { lte: "Z" } }
      { available: { lte: true } }
      { price: { lte: 100 } }
      { publishedOn: { lte: "2030-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL Konseptual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title <= 'Z'
  AND available <= 1
  AND price <= 100
  AND publishedOn <= '2030-01-01T00:00:00Z';

and

Logis DAN. Menggabungkan beberapa predikat yang semuanya harus benar agar rekaman cocok.

Dalam contoh ini, kami mendapatkan buku yang tersedia, harganya kurang dari 30, dan diterbitkan setelah 1 Januari 2022.

query {
  books(filter: {
    and: [
      { available: { eq: true } }
      { price: { lt: 30 } }
      { publishedOn: { gt: "2022-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL Konseptual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE available = 1
  AND price < 30
  AND publishedOn > '2022-01-01T00:00:00Z';

or

Logis ATAU. Mengembalikan rekaman di mana setidaknya satu predikat dalam array dievaluasi ke true.

Dalam contoh ini, kita mendapatkan buku yang kehabisan stok atau harga di atas 50.

query {
  books(filter: {
    or: [
      { available: { eq: false } }
      { price: { gt: 50 } }
    ]
  }) {
    items { id title available price }
  }
}

SQL Konseptual

SELECT id, title, available, price
FROM Books
WHERE available = 0
   OR price > 50;

contains

Kecocokan substring. Mengembalikan rekaman di mana bidang berisi substring yang disediakan (sensitivitas huruf besar/kecil tergantung pada kolase database).

Dalam contoh ini, kita mendapatkan buku yang judulnya menyertakan kata "Dune."

query {
  books(filter: { title: { contains: "Dune" } }) {
    items { id title }
  }
}

SQL Konseptual

SELECT id, title
FROM Books
WHERE title LIKE '%Dune%';

notContains

Kecocokan substring negatif. Mengembalikan rekaman di mana bidang tidak berisi substring yang disediakan.

Dalam contoh ini, kita mendapatkan buku yang judulnya tidak menyertakan "Panduan."

query {
  books(filter: { title: { notContains: "Guide" } }) {
    items { id title }
  }
}

SQL Konseptual

SELECT id, title
FROM Books
WHERE title NOT LIKE '%Guide%';

startsWith

Kecocokan awalan. Mengembalikan rekaman di mana bidang dimulai dengan string yang disediakan.

Dalam contoh ini, kita mendapatkan buku yang judulnya dimulai dengan "The."

query {
  books(filter: { title: { startsWith: "The" } }) {
    items { id title }
  }
}

SQL Konseptual

SELECT id, title
FROM Books
WHERE title LIKE 'The%';

endsWith

Kecocokan akhiran. Mengembalikan rekaman di mana bidang berakhir dengan string yang disediakan.

Dalam contoh ini, kita mendapatkan buku yang judulnya berakhir dengan "Chronicles."

query {
  books(filter: { title: { endsWith: "Chronicles" } }) {
    items { id title }
  }
}

SQL Konseptual

SELECT id, title
FROM Books
WHERE title LIKE '%Chronicles';

in

Kecocokan keanggotaan. Mengembalikan rekaman di mana nilai bidang ada dalam daftar yang disediakan.

Dalam contoh ini, kita mendapatkan buku yang genrenya adalah "SciFi" atau "Fantasy."

query {
  books(filter: { genre: { in: ["SciFi", "Fantasy"] } }) {
    items { id title genre }
  }
}

SQL Konseptual

SELECT id, title, genre
FROM Books
WHERE genre IN ('SciFi', 'Fantasy');

isNull

Pemeriksaan null. Mengembalikan rekaman di mana nilai bidang null atau tidak null tergantung pada literal boolean.

Dalam contoh ini, kita mendapatkan buku di mana peringkatnya null.

query {
  books(filter: { rating: { isNull: true } }) {
    items { id title rating }
  }
}

SQL Konseptual

SELECT id, title, rating
FROM Books
WHERE rating IS NULL;

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.

  • Last updated on