Работа с фильтрами
При работе с API получения списка элементов приложения имеется возможность задавать условия поиска, по которым будут фильтроваться элементы.
Добавление фильтрации выполняется путем вставки конструкции filter
.
Пример:
{
"filter": {
}
}
Есть три вида операций:
- Табличная операция. Позволяет формировать единый набор условий фильтрации.
- Операции условий. Позволяют формировать одинарное условие фильтрации.
- Логические операции. Позволяют комбинировать, объединять, вкладывать операции условий.
Табличная операция
В качестве условий фильтра выступают поля элементов с прописанными условиями. Каждый тип поля может иметь собственный вариант задания условий. В фильтре можно комбинировать поля и условия поиска. В этом случае поиск будет возвращать те элементы приложения, которые соответствуют всем введенным условиям.
Добавление фильтрации выполняется путем вставки конструкции 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"
}
}
}
}
Для полей Да/Нет указывается искомое значение false или true.
Пример:
{
"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"
}
}
}
Операции условий
Задаются двумя параметрами:
- Первый - обязательная конструкция
filed
, определяющая наименование поля. - Вторая - условие. Для одинарного условие задается конструкцией
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": "enumFiled"},
{"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": "город"}
]
}
}
Операции "Вхождение в множество" и "Невхождение в множество"
Операция "Вхождение в множество" позволяет задавать условие фильтрации, при котором значение одиночного поля проверяется на вхождение в множество. Задается конструкцией in
.
Операция "Невхождение в множество" позволяет задавать условие фильтрации, при котором значение одиночного поля проверяется на невхождение в множество. Задается конструкцией not_in
.
Пример поиска по вхождению значения поля в список допустимых:
{
"filter": {
"in": [
{"field": "weight"},
{ "list": [1, 11] }
]
}
}
Пример поиска по невхождению поля типа Категория в список недопустимых:
{
"filter": {
"not_in": [
{"field": "enum"},
{ "list": ["Number1", "Number3", "Number5"] }
]
}
}
Операция "В связанной коллекции"
Операция "В связанной коллекции" позволяет задавать условие фильтрации, при котором проверяется на связь значения множественного поля типа Приложение. Задается конструкцией link
.
Пример:
{
"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"] }
]
}
}
Логические операции
Логическая операция "Логическое И"
Операция "Логическое И" позволяет соединять условия фильтрации. Результатом выборки будут элементы, удовлетворяющие всем условиям.
Задается конструкцией 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"}
]
}
]
}
}
Комбинация логических операций
Фильтрация может быть объявлена через комбинацию операций запросов.
Пример:
{
"filter": {
"or": [
{
"eq": [
{"field": "field1"},
{"const": "value1"}
]
},
{
"and": [
{
"eq": [
{"field": "field2"},
{"const": "value2"}
]
},
{
"eq": [
{"field": "field3"},
{"const": "value3"}
]
}
]
}
]
}
}