Работа с фильтрами
При работе с API получения списка элементов приложения можно задавать условия поиска, по которым элементы будут фильтроваться.
Добавление фильтрации выполняется путем вставки конструкции filter.
Пример:
{
"filter": {
}
}
Есть четыре вида операций:
- Табличная операция — позволяет формировать набор условий для фильтрации, в котором для каждого типа полей доступны свои преднастроенные варианты условий;
- Операции условий — позволяют формировать отдельные условия, в которых для значений полей разных типов можно задавать различные критерии;
- Операция EQL — позволяют добавлять в фильтр критерии выборки, заданные на языке EQL365;
- Логические операции — позволяют комбинировать, объединять, вкладывать, обращать условия.
Табличная операция
В условиях для фильтрации прописываются поля элемента и критерии, которым должны соответствовать их значения. Для каждого типа данных существует свой вариант установления критериев.
В одном фильтре можно задать условия для нескольких полей. В этом случае поиск будет возвращать элементы приложения, которые соответствуют всем введенным условиям.
Добавление фильтра выполняется путем вставки конструкции tf:
{
"filter": {
"tf": {
"title": "белый",
"description":"цвет с кодом"
}
}
}
Строка
Для строковых полей указывается строка, для которой ожидается вхождение в поле элемента приложения. Регистр значения не имеет.
Пример:
{
"filter": {
"tf": {
"__name": "Мой объект"
}
}
}
Число
Для числовых полей указывается промежуток, в который должно входить искомое значение.
Пример:
{
"filter": {
"tf": {
"weight": {
"min": 10,
"max": 100
}
}
}
}
Если необходимо найти точное число, то оба параметра выставляются равными искомому значению:
{
"filter": {
"tf": {
"weight": {
"min": 100,
"max": 100
}
}
}
}
Если необходимо найти значение больше или меньше определенного числа, то указывается один из параметров, а для второго выставляется null:
{
"filter": {
"tf": {
"weight": {
"min": 1,
"max": null
}
}
}
}
Дата/время
Для полей дат указывается промежуток. При этом следует учитывать, что:
- Время указывается во временной зоне +00;
- В случае если настройки поля менялись с даты на время или наоборот, то ранее внесенные данные могут не соответствовать ожидаемым для фильтра. Перед использованием фильтра в этом случае следует предварительно проанализировать хранимые данные.
Пример:
{
"filter": {
"tf": {
"__createdAt": {
"min": "2023-04-11T00:00:00Z",
"max": "2023-04-12T00:00:00Z"
}
}
}
}
Если необходимо найти дату раньше или позже заданной, то указывается один из параметров, а для второго выставляется null:
{
"filter": {
"tf": {
"__createdAt": {
"min": "2023-04-11T00:00:00Z",
"max": null
}
}
}
}
Не рекомендуется использовать вариант написания без указания времени. В зависимости от настроек системы и вариантов хранения данных результат поиска может отличаться.
Пример, как делать не стоит:
{
"filter": {
"tf": {
"__createdAt": {
"min": "2023-04-01",
"max": "2023-04-17"
}
}
}
}
Выбор «да/нет»
Для полей типа Выбор «да/нет» указывается значение true или false.
Пример:
{
"filter": {
"tf": {
"opened": true
}
}
}
Номер телефона
Для полей типа Номер телефона указывается строка, для которой ожидается вхождение в поле элемента приложения. Наличие разделительных символов в телефонном номере значения не имеет.
Пример:
{
"filter": {
"tf": {
"phone": "7-999-11"
}
}
}
Электронная почта
Для полей типа Электронная почта указывается строка, для которой ожидается вхождение в поле элемента приложения. Регистр значения не имеет.
Пример:
{
"filter": {
"tf": {
"email": "admin@admin.com"
}
}
}
Ф.И.О.
Для полей типа Ф.И.О. указывается строка, для которой ожидается вхождение в имя, фамилию или отчество, указанные в элементе приложения. Регистр значения не имеет.
Пример:
{
"filter": {
"tf": {
"fio": "иван"
}
}
}
Статус
Для поля типа Статус указывается массив с номерами статусов.
Пример:
{
"filter": {
"tf": {
"__status": [2,3]
}
}
}
Пользователи
Для полей типа Пользователи указывается UUID искомого пользователя.
Пример:
{
"filter": {
"tf": {
"user": "47cfc3d3-279d-441e-a245-a27adaac81e8"
}
}
}
Для множественного поля типа Пользователи также необходимо указать только одного искомого пользователя:
{
"filter": {
"tf": {
"users": "47cfc3d3-279d-441e-a245-a27adaac81e8"
}
}
}
Приложение
Для поиска по полю типа Приложение необходимо указать UUID элемента приложения.
Пример:
{
"filter": {
"tf": {
"myApp": {
"id":"7730e64b-551b-4eda-bb49-b0120e9712eb",
}
}
}
}
Произвольное приложение
Для поиска по полю типа Произвольное приложение необходимо указать UUID элемента, код приложения и код раздела.
Пример:
{
"filter": {
"tf": {
"myRandomApp": {
"id":"7730e64b-551b-4eda-bb49-b0120e9712eb",
"code":"myApplication",
"namespace":"myNamespace",
"inTrash":false
}
}
}
}
Категория
Для поиска по полю типа Категория необходимо указать код элемента перечисления.
Пример:
{
"filter": {
"tf": {
"errStatus":"blocker"
}
}
}
Операции условий
Задаются двумя параметрами:
- Наименование поля — задаётся конструкцией
field; - Условие — для одинарного условия задаётся конструкцией
const, для множественного — конструкциейlist. Если в операции нужно задать условие, описывающее отсутствие, то указываетсяnull.
Пример одинарного условия:
{
"eq": [
{"field": "weight"},
{"const": 5}
]
}
Пример множественного условия:
{
"in": [
{"field": "values"},
{"list": [1,4]}
]
}
Пример пустого условия:
{
"eq": [
{"field": "title"},
null
]
}
Формат записи условия зависит от типа поля, по которому ведётся фильтрация.
Форматы условий для типов данных
Строка
Для строковых полей указывается строка в кавычках.
Пример:
{
"filter": {
"eq": [
{"field": "stringField"},
{"const": "MyStringValue"}
]
}
}
Число
Для числового типа данных условие указывается в виде числа.
Пример для целого числа:
{
"filter": {
"neq": [
{"field": "intField"},
{"const": 14}
]
}
}
Пример для дробного числа:
{
"filter": {
"neq": [
{"field": "floatField"},
{"const": 12.05}
]
}
}
Деньги
Для типа данных Деньги условие указывается в виде числа, представляющего собой значение в минимальных единицах измерения валюты. Так, например, для суммы 54 рубля 45 копеек значение в фильтре будет 5445.
Пример:
{
"filter": {
"neq": [
{"field": "moneyField"},
{"const": 5445}
]
}
}
Дата/время
Для полей c датами или временем значение указывается в кавычках. При этом следует учитывать, что:
- Время указывается во временной зоне +00;
- В случае если настройки поля менялись с даты на время или наоборот, то ранее внесенные данные могут не соответствовать ожидаемым для фильтра. Перед использованием фильтра в этом случае следует предварительно проанализировать хранимые данные.
Не рекомендуется использовать вариант написания без указания времени. В зависимости от настроек системы и вариантов хранения данных результат поиска может отличаться.
Пример:
{
"filter": {
"eq": [
{"field": "dateTimeField"},
{"const": "2023-04-17T04:54:39Z"}
]
}
}
Выбор «да/нет»
Для полей Выбор «да/нет» значение в условии может быть true или false.
Пример:
{
"filter": {
"eq": [
{"field": "boolField"},
{"const": true}
]
}
}
Номер телефона
Для полей типа Номер телефона указывается строка. Наличие разделительных символов в телефонном номере значения не имеет.
Пример:
{
"filter": {
"eq": [
{"field": "phoneField"},
{ "const": "+71234566780"}
]
}
}
Электронная почта
Для полей типа Электронная почта указывается строка.
Пример:
{
"filter": {
"eq": [
{"field": "emailFiled"},
{"const": "example@example.example"}
]
}
}
Ф.И.О.
Для полей типа Ф.И.О. указывается строка. Данные в полях этого типа хранятся в особом формате, поэтому количество допустимых операций ограничено. Рекомендуется использовать операцию like.
Пример:
{
"filter": {
"like": [
{"field": "fioFiled"},
{"const": "Петрович"}
]
}
}
Статус
Для полей типа Статус указывается число, представляющее собой номер статуса.
Пример:
{
"filter": {
"in": [
{"field": "__status"},
{ "list": [1,2]}
]
}
}
Пользователи
Для полей типа Пользователи указывается строковое представление UUID пользователя в нижнем регистре в кавычках.
Пример:
{
"filter": {
"eq": [
{"field": "__createdBy"},
{"const": "95806fe5-f8e8-460c-b2be-ce607068726c"}
]
}
}
Приложение
Для поля типа Приложение нужно указать строковое представление UUID элемента. Независимо от того, множественное поле или одиночное, данные хранятся в виде массива. Поэтому рекомендуется работать с такими полями через оператор link.
Пример:
{
"filter": {
"link": [
{"field": "fieldApp"},
{"list": ["f5506c2b-0504-4420-9490-11a4f4d7f49d"]}
]
}
}
Категория
Для поля типа Категория нужно указать строковый код элемента перечисления.
Пример:
{
"filter": {
"eq": [
{"field": "enumField"},
{"const": "enumValue1"}
]
}
}
Операции равенства и неравенства
Операция равенства позволяет задавать условие фильтрации, основанное на полном совпадении. Задаётся конструкцией eq.
Операция неравенства позволяет задавать условие фильтрации, обратное операции равенства. Задаётся конструкцией neq.
Пример условия с равенством для целого числа:
{
"filter": {
"eq": [
{"field": "weight"},
{"const": 5}
]
}
}
Пример условия с равенством для поля, содержащего дату:
{
"filter": {
"eq": [
{"field": "ttlEnd"},
{"const": "2023-04-12T11:11:45.367Z"}
]
}
}
Пример условия с неравенством для поля типа Выбор «да/нет»:
{
"filter": {
"neq": [
{"field": "opened"},
{"const": true}
]
}
}
Пример для проверки на непустое значение поля enum типа Категория:
{
"filter": {
"neq": [
{"field": "enum"},
null
]
}
}
Операции «Больше», «Больше или равно», «Меньше» и «Меньше или равно»
Операция «Больше» позволяет задавать условие фильтрации, основанное на поиске большего значения. Задаётся конструкцией gt.
Операция «Больше или равно» позволяет задавать условие фильтрации, основанное на поиске большего или равного значения. Задаётся конструкцией gte.
Операция «Меньше» позволяет задавать условие фильтрации, основанное на поиске меньшего значения. Задаётся конструкцией lt.
Операция «Меньше или равно» позволяет задавать условие фильтрации, основанное на поиске меньшего или равного значения. Задаётся конструкцией lte.
Пример поиска статуса, отличного от начального:
{
"filter": {
"gt": [
{"field": "__status"},
{"const": 1}
]
}
}
Пример поиска даты, входящей в указанный промежуток:
{
"filter": {
"and": [
{
"gte": [
{"field": "ttlEnd"},
{"const": "2023-04-10T11:11:45.367Z"}
]
},
{
"lte": [
{"field": "ttlEnd"},
{"const": "2023-04-12T11:11:45.367Z"}
]
}
]
}
}
Операция вхождения подстроки
Операция вхождения подстроки позволяет задавать условие фильтрации, основанное на частичном совпадении. Задаётся конструкцией like.
Пример для поиска по частичному совпадению для строкового поля:
{
"filter": {
"like": [
{"field": "__name"},
{"const": "город"}
]
}
}
Операция вхождения подстроки по шаблону
Операция позволяет устанавливать условие для фильтрации по частичному совпадению строки на основе шаблона. Задаётся конструкцией like_format. Шаблон формируется с помощью управляющих символов % и _. Символ % обозначает произвольное количество символов, символ _ представляет один любой символ. Регистр не учитывается.
Пример поиска по вхождению слова в название:
{
"filter": {
"like_format": [
{"field": "__name"},
{"const": "%город%"}
]
}
}
Пример поиска регистрационного номера по шаблону заполнения:
{
"filter": {
"like_format": [
{"field": "regNumber"},
{"const": "М86_А_ 777"}
]
}
}
Операции вхождения в множество и невхождения в множество
Операция вхождения в множество позволяет задавать условие фильтрации, при котором значение одиночного поля проверяется на вхождение в множество. Задаётся конструкцией in.
Операция невхождения в множество позволяет задавать условие фильтрации, при котором значение одиночного поля проверяется на невхождение в множество. Задаётся конструкцией not_in.
Пример поиска по вхождению значения поля в заданный список:
{
"filter": {
"in": [
{"field": "weight"},
{ "list": [1, 11] }
]
}
}
Пример поиска по невхождению поля типа Категория в заданный список:
{
"filter": {
"not_in": [
{"field": "enum"},
{ "list": ["Number1", "Number3", "Number5"] }
]
}
}
Операция «В связанной коллекции»
Операция «В связанной коллекции» позволяет задавать условие фильтрации, при котором значение множественного поля типа Приложение проверяется на наличие связи с определённым элементом. Задаётся конструкцией link. В качестве значения передается UUID элемента приложения.
Пример:
{
"filter": {
"link": [
{"field": "fewApps"},
{ "list": ["f5506c2b-0504-4420-9490-11a4f4d7f49d", "e20379bc-2f80-4b63-9e77-fbb3fa50e362"] }
]
}
}
Операция «Вхождение множества»
Операция «Вхождение множества» позволяет задавать условие фильтрации, при котором значение множественного поля проверяется на вхождение в множество, заданное в условии. Задаётся конструкцией all.
Пример поиска по вхождению значения поля в заранее определенный список пользователей:
{
"filter": {
"all": [
{"field": "users"},
{ "list": ["95806fe5-f8e8-460c-b2be-ce607068726c", "f5506c2b-0504-4420-9490-11a4f4d7f49d"] }
]
}
}
Операция EQL
Операции EQL позволяют добавлять в фильтр критерии выборки, заданные на языке EQL365.
Чтобы добавить фильтр, используйте конструкцию eql:
"eql": {
"query":"[price] = 4000"
}
Подробнее о возможностях EQL-запросов читайте в статье справки «Синтаксис EQL-запроса».
Помимо указания значений условий для поиска в явном виде, вы можете задавать их через параметры. В EQL-запросе параметр создаётся с помощью символа @ и произвольного названия. Значение параметра задаётся в конструкции parameters.
Пример:
"eql":{
"query":"[price] = @priceValue",
"parameters":[
{
"priceValue":"100"
}
]
}
Логические операции
Логическая операция «И»
Логическая операция «И» позволяет соединять условия фильтрации. Результатом выборки будут элементы, удовлетворяющие всем условиям.
Задаётся конструкцией and.
Пример:
{
"filter": {
"and": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
}
]
}
}
Логическая операция «ИЛИ»
Логическая операция «ИЛИ» позволяет соединять условия фильтрации. Результатом выборки будут элементы, удовлетворяющие одному из условий.
Задаётся конструкцией or.
Пример:
{
"filter": {
"or": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
}
]
}
}
Логическая операция «НЕ»
Логическая операция «НЕ» позволяет инвертировать условие фильтрации. Результатом выборки будут элементы, не удовлетворяющие вложенным условиям.
Задаётся конструкцией not.
Пример:
{
"filter": {
"not": {
"eq": [
{"field": "field1"},
{"const": "value1"}
]
}
}
}
Комбинация логических операций
При объявлении фильтрации можно использовать комбинацию операций:
{
"filter": {
"not": {
"or": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"and": [
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
},
{
"eq": [
{"field": "field3"},
{"const": "value3"}
]
}
]
}
]
}
}
}