Filter

Служит для дополнительной фильтрации выборок по основным(список полей определяется для каждой сущности отдельно) и по дополнительным полям, созданным для сущности.

Название Тип данных Обязательность Описание
field string Обязательное Имя поля сущности (например first_name, region_id, date_of_birth).
operator Enum Обязательное Оператор фильтрации.
value string Обязательное Значение фильтра в текстовом представлении. Также поддерживается маска ${field} в качестве значения, где field — название поля, доступного для фильтрации; обязательное условие: тип данных поля field должен совпадать с типом данных ${field}. Для Exists/NotExists не обязательно и игнорируется.

Допустимые значения поля Value

Название Описание
Equal Равенство (=).
NotEqual Не равно (!=).
Greater Больше (>).
Less Меньше (<).
GreaterOrEqual Больше или равно (>=).
LessOrEqual Меньше или равно (<=).
Like Частичное совпадение (только для строковых полей).
Exists Проверка наличия значения.
NotExists Проверка отсутствия значения.

Для операторов Exists/NotExists поле Value не требуется и игнорируется.

Правила валидации и применимости операторов по типам полей

  • value должен соответствовать типу данных поля (data_type) или быть маской ${field} при соблюдении условий ниже:

    • string — любое строковое значение.

    • int — строка, представляющая целое число (должна парситься в int).

    • decimal — строка, представляющая десятичное число (должна парситься в decimal).

    • bool — строка "true" или "false" (регистронезависимо).

    • при использовании маски ${field}:

    • field внутри маски должен быть именем поля, доступного для фильтрации для данной сущности (основного или дополнительного пользовательского, если применимо).

    • обязательное условие: тип данных поля в field фильтра должен совпадать с типом данных поля, указанного в маске ${field}.

  • Ограничения по операторам:

    • Like — применимо только к полям с data_type = "string". Для других типов возвращается ошибка валидации.
    • Для data_type = "bool" допустимы только операторы: Equal, NotEqual, Exists, NotExists.
    • Для data_type = "int" и data_type = "decimal" допустимы все операторы, за исключением Like.

  • Если оператор требует Value (например Equal, Greater, LessOrEqual и т. п.), а Value отсутствует или не может быть корректно сконвертирован в соответствующий тип — возвращается ошибка валидации. Если Value задано маской ${field}, то дополнительно валидируется существование поля и совпадение типов данных (см. выше).

  • Для пользовательских дополнительных полей (is_custom = true) дополнительно проверяется, что поле существует в метаданных и принадлежит указанной сущности.

Пример JSON объекта фильтра

{ "field": "region_id", "operator": "Equal", "value": "5" }

Пример JSON применения фильтра для получения данных

{
  "filters": [
    { "field": "field_telegram_id", "operator": "Equal", "value": "123456789" }
  ]
}

Пример JSON объекта фильтра с маской ${field}

{ "field": "max_amount", "operator": "GreaterOrEqual", "value": "${min_amount}" }