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

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

Замечание

Фильтрация GraphQL поддерживает сравнение, логический, строковый шаблон, членство и пустые операторы. Фильтры GraphQL используют структурированные входные объекты: { fieldName: { operator: value } } Даты должны быть допустимыми строками ISO 8601 UTC. Проверки NULL используются isNull вместо eq null.

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

Operator	Meaning
`eq`	равный
`neq`	не равно
`gt`	больше чем
`gte`	больше или равно
`lt`	Менее
`lte`	меньше или равно
`and`	логический И
`or`	логический ИЛИ
`contains`	Соответствие подстроки
`notContains`	не соответствует подстроки
`startsWith`	Соответствие префикса
`endsWith`	совпадение суффикса
`in`	членство
`isNull`	Проверка null

`eq`

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

Замечание

При фильтрации по полям даты или даты и времени используйте неквотируемый формат 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

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

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`

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

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

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`

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

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

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`

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

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

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`

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

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

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`

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

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

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`

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

В этом примере мы получаем книги, которые доступны, стоимость менее 30 и были опубликованы после 1 января 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

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

`or`

Логический ИЛИ. Возвращает записи, в которых по крайней мере один предикат в массиве имеет значение true.

В этом примере мы получаем книги, которые либо из акций, либо оценены выше 50.

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

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

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

`contains`

Совпадение подстроки. Возвращает записи, в которых поле содержит указанную подстроку (конфиденциальность регистра зависит от сортировки базы данных).

В этом примере мы получаем книги, название которых включает слово "Dune".

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

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

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

`notContains`

Отрицательное совпадение подстроки. Возвращает записи, в которых поле не содержит указанную подстроку.

В этом примере мы получаем книги, название которых не содержит "Руководство".

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

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

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

`startsWith`

Совпадение префикса. Возвращает записи, в которых поле начинается с предоставленной строки.

В этом примере мы получаем книги, название которых начинается с "The".

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

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

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

`endsWith`

Суффикс совпадения. Возвращает записи, в которых поле заканчивается предоставленной строкой.

В этом примере мы получаем книги, название которых заканчивается "Хроники".

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

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

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

`in`

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

В этом примере мы получаем книги, жанр которых — SciFi или "Фантазия".

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

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

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

`isNull`

Флажок NULL. Возвращает записи, в которых значение поля равно null или не null в зависимости от логического литерала.

В этом примере мы получаем книги, в которых оценка имеет значение NULL.

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

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

SELECT id, title, rating
FROM Books
WHERE 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 2025-10-15

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

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

eq

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

neq

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

gt

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

gte

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

lt

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

lte

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

and

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

or

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

contains

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

notContains

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

startsWith

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

endsWith

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

in

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

isNull

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

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

См. также

Обратная связь

Дополнительные ресурсы

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

`eq`

`neq`

`gt`

`gte`

`lt`

`lte`

`and`

`or`

`contains`

`notContains`

`startsWith`

`endsWith`

`in`

`isNull`