Работа с фильтрами

При работе с 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"}
                        ]
                    }
                ]
            }
        ]
    }
}