Фильтрация данных в REST ($filter)

Фильтрация сужает большие наборы данных только к нужным записям. В REST построитель API данных (DAB) поддерживает параметр запроса, вдохновленный $filter OData. Каждый фильтр компилируется в параметризованный SQL для обеспечения безопасности и согласованности.

Краткий обзор

Operator Meaning
eq равный
ne не равно
gt больше чем
ge больше или равно
lt Менее
le меньше или равно
and логический И
or логический ИЛИ
not логическое НЕ
( ) группировка

eq

Равно. Возвращает записи, в которых значение поля точно соответствует предоставленному литералу или null.

В этом примере мы получаем книги, где название равно 'Dune', доступный флаг имеет значение true, цена составляет 20, дата публикации — 1 января 2024 года, а рейтинг равен 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

Замечание

$filter поддерживает eq null и ne null напрямую для сравнения значений NULL.

Концептуальный 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

Не равно. Возвращает записи, в которых значение поля не соответствует заданному литералу или не имеет значения NULL.

В этом примере мы получаем книги, где название не является 'Foundation', доступный флаг не false, цена не равна нулю, опубликованная дата не является 31 декабря 2023 года, а рейтинг не имеет значения 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

Замечание

При фильтрации по полям даты или даты и времени используйте неквотируемый формат ISO 8601 UTC (yyyy-MM-ddTHH:mm:ssZ). Недопустимые форматы в стиле OData или кавычки.

  • Неправильно: $filter=Date ge '2025-01-01'
  • Неправильно: $filter=Date ge datetime'2025-01-01'
  • Правильно: $filter=Date ge 2025-01-01T00:00:00Z

Концептуальный 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

Больше. Возвращает записи, в которых значение поля строго выше заданного литерала.

В этом примере мы получаем книги, названия которых сортируются по алфавиту по 'A'алфавиту, доступный флаг имеет значение true, цена превышает 10, а дата публикации — после 1 января 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

Концептуальный SQL

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

ge

Больше или равно. Возвращает записи, в которых значение поля выше или равно заданному литералу.

В этом примере мы получаем книги с названием 'A' или более поздней версией, доступный флаг имеет значение true, цена составляет не менее 10, а дата публикации — 1 января 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

Концептуальный SQL

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

lt

Менее. Возвращает записи, в которых значение поля строго ниже заданного литерала.

В этом примере мы получаем книги, названия которых сортируются до 'Z', доступный флаг имеет значение false, цена меньше 50, а дата публикации — до 1 января 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

Концептуальный SQL

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

le

Меньше или равно. Возвращает записи, в которых значение поля меньше или равно заданному литералу.

В этом примере мы получаем книги, названия которых сортируются до или равно 'Z', доступный флаг имеет значение true, цена составляет 100 или меньше, а дата публикации — до 1 января 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

Концептуальный SQL

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

and

Логический И. Объединяет несколько условий, которые должны соответствовать записи.

В этом примере мы получаем книги, где заголовок 'Dune', доступный флаг имеет значение true, цена меньше 50, опубликованная дата будет после 1 января 2020 года, а рейтинг равен 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

Концептуальный 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

Логический ИЛИ. Объединяет условия, в которых должно быть по крайней мере одно значение true для соответствующей записи.

В этом примере мы получаем книги, в которых имеется название 'Dune', или доступный флаг имеет значение true, или цена превышает 20, или дата публикации до 1 января 2025 г. или оценка имеет значение 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

Концептуальный 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

Логический НЕ. Отменяет условие, поэтому записи возвращаются только в том случае, если условие равно false.

В этом примере мы получаем все книги, которые не имеют названия 'Romance', не недоступны, не стоят менее $ 10, не были опубликованы до 1 января 2020 года и не имеют нулевой оценки.

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
  )

Концептуальный 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
);

( ) группировка

Группирует вложенные выражения, чтобы управлять порядком оценки в сложных фильтрах.

В этом примере мы получаем книги, где название 'Fiction' либо, либо 'SciFi', и книга доступна или цена ниже $ 25, и дата публикации после 1 января 2020 года, и рейтинг имеет значение 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

Концептуальный 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;

Пример конфигурации

{
  "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 items Выбор возвращаемых полей
Filtering $filter фильтр Ограничение строк по условию
Сортировка $orderby orderBy Определение порядка сортировки
Размер страницы $first first Ограничение количества элементов на страницу
Продолжение $after после Продолжить с последней страницы с помощью курсора

Замечание

Ключевые слова REST начинаются с $следующих соглашений OData.

  • Last updated on