Фильтры

Каждое поле на странице списка может иметь собственный набор операторов фильтрации, таких как contains, between и is null. Ваши пользователи комбинируют эти операторы во вложенное дерево AND/OR, и вам не приходится писать сложные запросы к базе данных вручную.

Admin определяет доступные фильтры на основе типа поля. Для любого поля вы можете сократить этот набор, расширить его или полностью заменить.

from starlette_admin.contrib.sqla import ModelView


class PostView(ModelView):
    fields = ["id", "title", "content", "published", "created_at"]
    # Enable filtering and searching for these specific fields
    searchable_fields = ["title", "content", "published", "created_at"]

См. examples/02-filters — это работающее приложение, демонстрирующее фильтры по умолчанию, переопределение фильтров для отдельных полей и пользовательский подкласс BaseFilter.

Для каждого поля, перечисленного в searchable_fields, на панели инструментов списка появляется выпадающее меню Filters. С его помощью пользователи комбинируют любое количество фильтров, чтобы найти нужные строки.

Как работает конструктор фильтров

При нажатии кнопки Filters открывается форма-выпадающее меню, в которой пользователи формируют свои запросы:

• Add filter: добавляет строку условия. Пользователь выбирает поле, выбирает один из доступных для этого поля операторов фильтрации и указывает значение. Ввод адаптируется к оператору: обычное текстовое поле для contains, два поля для between и отсутствие ввода вовсе для is null.
• Add group: добавляет вложенную подформу со своим селектором AND/OR. Используйте её для построения условий вида A AND (B OR C).
• Match all/any of the following: задаёт, какая логика применяется на текущем уровне — AND или OR.
• Apply filters: отправляет форму как GET-запрос. Admin сериализует всё дерево фильтров в единственный параметр запроса filter, формат которого описан в разделе Формат URL фильтра.
• Active filters: каждый активный фильтр отображается в виде удаляемой «пилюли» над таблицей. Нажатие на × повторно отправляет список без этого правила. Вложенная группа сворачивается в одну «пилюлю», которую можно удалить целиком.

Переопределение фильтров для конкретного поля

Если фильтры по умолчанию слишком широкие или вам требуется что-то более специфичное, передайте аргумент filters= в поле, чтобы заменить набор по умолчанию.

Вы можете сократить список до нужных операторов, расширить его пользовательским фильтром или добавить операторы в поле, которому по умолчанию доступны только базовые проверки на NULL, например TagsField:

from enum import Enum

from starlette_admin import (
    DateTimeField,
    DecimalField,
    EnumField,
    StringField,
    TagsField,
)
from starlette_admin.contrib.sqla import ModelView

# Import the concrete filter implementations for your specific backend
from starlette_admin.contrib.sqla.filters import (
    BetweenFilter,
    DateInPastFilter,
    DateTimeBetweenFilter,
    GreaterThanFilter,
    NumericEqualFilter,
)


class ProductStatus(str, Enum):
    ACTIVE = "ACTIVE"
    OUT_OF_STOCK = "OUT_OF_STOCK"
    DISCONTINUED = "DISCONTINUED"


class ProductView(ModelView):
    fields = [
        "id",
        StringField("name"),  # Uses the default filter set, no override needed
        EnumField("status", enum=ProductStatus),  # Uses the default filter set
        DecimalField(
            "price",
            # Narrowed down to just 3 of the 9 default numeric filters
            filters=[GreaterThanFilter, BetweenFilter, NumericEqualFilter],
        ),
        DateTimeField("created_at", filters=[DateTimeBetweenFilter, DateInPastFilter]),
    ]

Формат URL фильтра

Конструктор фильтров сериализует своё состояние в параметр запроса filter в виде компактной строки.

Формат выглядит так: field__operator — для фильтра без значений, field__operator=value — для одного значения и field__operator=value..value2 — для фильтра с двумя значениями, например between. Правила соединяются через AND или OR, а круглые скобки образуют группу:

/admin/product/list?filter=price__gt=50+AND+status__eq=ACTIVE

/admin/product/list?filter=created_at__between=2026-01-01..2026-01-31+AND+(price__gt=12+OR+price__eq=8)

Заключайте значение в кавычки, если оно содержит пробел или круглую скобку: name__eq="quoted value". Значение-список для мультивыбора фильтра, такого как is one of, разделяется запятыми и в кавычках не нуждается: status__in=ACTIVE,OUT_OF_STOCK.

Если URL содержит недопустимую строку filter — например, неизвестное поле, недоступный оператор или значение, которое не удаётся разобрать, — приложение возвращает ошибку HTTP 400, вместо того чтобы молча отбросить часть условия.

Справочник встроенных фильтров

В следующей таблице перечислены все доступные из коробки фильтры, соответствующие slug в URL (который вы видите в сохранённой ссылке) и тип значения, который ожидает каждый из них. Для фильтров, помеченных как «два значения», необходимо указать и value, и value2 в URL, например between=2026-01-01..2026-01-31.

Если вам нужен фильтр для типа данных, который не покрывается встроенными фильтрами, например JSON-поле или гео-точка, обратитесь к разделу Пользовательские фильтры, чтобы написать подкласс BaseFilter и зарегистрировать его глобально или для отдельного экземпляра поля.

Что дальше

• Пользовательские фильтры: напишите и зарегистрируйте подкласс BaseFilter.
• Действия: добавьте массовые действия и действия для строк на страницы списков.
• Представления: узнайте больше о searchable_fields и остальной конфигурации страницы списка.