Filtrování dat v REST ($filter)

Filtrování zužuje velké datové sady jenom na záznamy, které potřebujete. Tvůrce rozhraní DATA API (DAB) v REST podporuje parametr dotazu inspirovaný $filter platformou OData. Každý filtr se zkompiluje do parametrizovaného SQL pro zajištění bezpečnosti a konzistence.

Rychlý přehled

Operator Meaning
eq rovný
ne není rovno
gt větší než
ge větší než nebo rovno
lt méně než
le menší než nebo rovno
and logický operátor AND
or logický operátor OR
not logické NE
( ) seskupení

eq

Rovná se. Vrátí záznamy, ve kterých hodnota pole přesně odpovídá zadanému literálu nebo null.

V tomto příkladu získáváme knihy, kde se název rovná 'Dune', dostupný příznak je pravdivý, cena je 20, publikované datum je 1. ledna 2024 a hodnocení má hodnotu null.

GET /api/books?$filter=
  title eq 'Dune' and
  available eq true and
  price eq 20 and
  published_on eq 2024-01-01T00:00:00Z and
  rating eq null

Poznámka:

$filter podporuje eq null a ne null přímo pro porovnání s hodnotou null.

Koncepční SQL

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

ne

Nerovná se. Vrátí záznamy, ve kterých hodnota pole neodpovídá danému literálu nebo není null.

V tomto příkladu dostáváme knihy, kde název není 'Foundation', dostupný příznak není false, cena není nula, datum publikování není 31. prosince 2023 a hodnocení nemá hodnotu null.

GET /api/books?$filter=
  title ne 'Foundation' and
  available ne false and
  price ne 0 and
  published_on ne 2023-12-31T00:00:00Z and
  rating ne null

Poznámka:

Při filtrování podle polí data nebo data a času použijte necitovaný formát ISO 8601 UTC (yyyy-MM-ddTHH:mm:ssZ). Formáty ve stylu quoted nebo OData jsou neplatné.

  • Nesprávný: $filter=Date ge '2025-01-01'
  • Nesprávný: $filter=Date ge datetime'2025-01-01'
  • Správně: $filter=Date ge 2025-01-01T00:00:00Z

Koncepční SQL

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

gt

Větší než. Vrátí záznamy, ve kterých je hodnota pole přísně vyšší než daný literál.

V tomto příkladu dostáváme knihy, jejichž název seřadí abecedně po 'A', dostupný příznak je pravdivý, cena je větší než 10 a datum publikování je po 1. lednu 2020.

GET /api/books?$filter=
  title gt 'A' and
  available gt false and
  price gt 10 and
  published_on gt 2020-01-01T00:00:00Z

Koncepční SQL

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

ge

Větší než nebo rovno. Vrátí záznamy, ve kterých je hodnota pole vyšší nebo rovna danému literálu.

V tomto příkladu dostáváme knihy, jejichž název je 'A' nebo novější, dostupný příznak je pravdivý, cena je aspoň 10 a datum publikování je 1. ledna 2020 nebo po 1. lednu 2020.

GET /api/books?$filter=
  title ge 'A' and
  available ge false and
  price ge 10 and
  published_on ge 2020-01-01T00:00:00Z

Koncepční SQL

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

lt

Méně než. Vrátí záznamy, ve kterých je hodnota pole přísně nižší než daný literál.

V tomto příkladu dostáváme knihy, jejichž název seřadí před 'Z', dostupný příznak je false, cena je menší než 50 a datum publikování je před 1. lednem 2030.

GET /api/books?$filter=
  title lt 'Z' and
  available lt true and
  price lt 50 and
  published_on lt 2030-01-01T00:00:00Z

Koncepční SQL

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

le

Menší než nebo rovno. Vrátí záznamy, ve kterých je hodnota pole nižší nebo rovna danému literálu.

V tomto příkladu dostáváme knihy, jejichž nadpis seřadí před nebo rovnou 'Z', dostupný příznak je pravdivý, cena je 100 nebo méně a publikované datum je dne nebo před 1. lednem 2030.

GET /api/books?$filter=
  title le 'Z' and
  available le true and
  price le 100 and
  published_on le 2030-01-01T00:00:00Z

Koncepční SQL

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

and

Logický operátor AND. Kombinuje více podmínek, které musí být splněny, aby se záznam shodoval.

V tomto příkladu dostáváme knihy, kde je 'Dune'název , dostupný příznak je pravdivý, cena je menší než 50, datum publikování je po 1. lednu 2020 a hodnocení má hodnotu null.

GET /api/books?$filter=
  title eq 'Dune' and
  available eq true and
  price lt 50 and
  published_on ge 2020-01-01T00:00:00Z and
  rating eq null

Koncepční SQL

SELECT * FROM Books
WHERE title = 'Dune'
  AND available = 1
  AND price < 50
  AND published_on >= '2020-01-01T00:00:00Z'
  AND rating IS NULL;

or

Logický operátor OR. Kombinuje podmínky, ve kterých musí být alespoň jedna pravdivá, aby se záznam shodoval.

V tomto příkladu dostáváme knihy, kde je 'Dune'název , nebo je dostupný příznak pravdivý, nebo cena je větší než 20, nebo datum publikování je před 1. lednem 2025 nebo hodnocení má hodnotu null.

GET /api/books?$filter=
  title eq 'Dune' or
  available eq true or
  price gt 20 or
  published_on lt 2025-01-01T00:00:00Z or
  rating eq null

Koncepční SQL

SELECT * FROM Books
WHERE title = 'Dune'
  OR available = 1
  OR price > 20
  OR published_on < '2025-01-01T00:00:00Z'
  OR rating IS NULL;

not

Logická NE. Negates a condition so records are return only if the condition is false.

V tomto příkladu dostáváme všechny knihy, které nemají název 'Romance', nejsou nedostupné, nejsou k dispozici, nejsou méně než 10 USD, nebyly publikovány před 1. lednem 2020 a nemají nulové hodnocení.

GET /api/books?$filter=
  not (
    title eq 'Romance' and
    available eq false and
    price lt 10 and
    published_on lt 2020-01-01T00:00:00Z and
    rating eq null
  )

Koncepční SQL

SELECT * FROM Books
WHERE NOT (
  title = 'Romance'
  AND available = 0
  AND price < 10
  AND published_on < '2020-01-01T00:00:00Z'
  AND rating IS NULL
);

( ) seskupení

Seskupí dílčí výrazy, abyste mohli řídit pořadí vyhodnocení ve složitých filtrech.

V tomto příkladu získáváme knihy, ve kterých je název buď 'Fiction' nebo 'SciFi', a kniha je k dispozici nebo je cena nižší než 25 USD a publikované datum je po 1. lednu 2020 a hodnocení má hodnotu null.

GET /api/books?$filter=
  (title eq 'Fiction' or title eq 'SciFi') and
  (available eq true or price lt 25) and
  published_on ge 2020-01-01T00:00:00Z and
  rating eq null

Koncepční SQL

SELECT * FROM Books
WHERE (title = 'Fiction' OR title = 'SciFi')
  AND (available = 1 OR price < 25)
  AND published_on >= '2020-01-01T00:00:00Z'
  AND rating IS NULL;

Příklad konfigurace

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

Viz také

Koncepce REST GraphQL Účel
Projection $select items Výběr polí, která se mají vrátit
Filtering $filter filtr Omezení řádků podle podmínky
Řazení $orderby orderBy Definování pořadí řazení
Velikost stránky $first first Omezení počtu položek na stránku
Pokračování $after po Pokračovat z poslední stránky pomocí kurzoru

Poznámka:

Klíčová slova REST začínají následujícími konvencemi $OData.

  • Last updated on