Filtres

Chaque champ d'une page de liste peut disposer de son propre ensemble d'opérateurs de filtrage, tels que contains, between ou is null. Vos utilisateurs combinent ces opérateurs en un arbre AND/OR imbriqué, et vous n'avez jamais à écrire une requête complexe en base de données.

L'admin déduit les filtres disponibles du type sous-jacent du champ. Vous pouvez restreindre, étendre ou remplacer entièrement cet ensemble pour n'importe quel champ.

from starlette_admin.contrib.sqla import ModelView


class PostView(ModelView):
    fields = ["id", "title", "content", "published", "created_at"]
    # Activer le filtrage et la recherche pour ces champs spécifiques
    searchable_fields = ["title", "content", "published", "created_at"]

Consultez examples/02-filters pour une application exécutable couvrant les filtres par défaut, les remplacements par champ et une sous-classe personnalisée de BaseFilter.

Chaque champ listé dans searchable_fields reçoit un menu déroulant Filtres dans la barre d'outils de la liste. À partir de là, les utilisateurs combinent autant de filtres que nécessaire pour trouver les lignes recherchées.

Fonctionnement du constructeur de filtres

La sélection du bouton Filtres ouvre un formulaire déroulant dans lequel les utilisateurs construisent leurs requêtes :

• Ajouter un filtre : ajoute une ligne de condition. L'utilisateur choisit un champ, sélectionne un opérateur parmi les filtres disponibles pour ce champ et fournit une valeur. Le champ de saisie s'adapte à l'opérateur : une simple zone de texte pour contains, deux zones pour between, et aucune saisie pour is null.
• Ajouter un groupe : imbrique un sous-formulaire doté de son propre sélecteur AND/OR. Utilisez-le pour construire des conditions du type A AND (B OR C).
• Correspondre à tous/aucun des éléments suivants : détermine si le niveau courant utilise la logique AND ou OR.
• Appliquer les filtres : soumet le formulaire sous forme de requête GET. L'admin sérialise l'intégralité de l'arbre de filtres dans un seul paramètre de requête filter, décrit dans Le format URL des filtres.
• Filtres actifs : chaque filtre actif apparaît sous forme d'une pastille supprimable au-dessus du tableau. La sélection du × recharge la liste sans cette règle. Un groupe imbriqué est réduit en une seule pastille que les utilisateurs suppriment dans son intégralité.

Remplacer les filtres d'un champ spécifique

Lorsque les filtres par défaut sont trop larges, ou si vous avez besoin de quelque chose de plus spécifique, passez l'argument filters= à un champ pour remplacer son ensemble par défaut.

Vous pouvez restreindre la liste aux opérateurs qui vous importent, l'étendre avec un filtre personnalisé, ou ajouter des opérateurs à un champ qui ne dispose par défaut que des vérifications basiques de nullité, comme TagsField :

from enum import Enum

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

# Importer les implémentations concrètes des filtres pour votre backend spécifique
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"),  # Utilise l'ensemble de filtres par défaut, aucun remplacement nécessaire
        EnumField("status", enum=ProductStatus),  # Utilise l'ensemble de filtres par défaut
        DecimalField(
            "price",
            # Restreint à seulement 3 des 9 filtres numériques par défaut
            filters=[GreaterThanFilter, BetweenFilter, NumericEqualFilter],
        ),
        DateTimeField("created_at", filters=[DateTimeBetweenFilter, DateInPastFilter]),
    ]

Le format URL des filtres

Le constructeur de filtres sérialise son état dans le paramètre de requête filter sous forme d'une chaîne compacte.

Le format est field__operator pour un filtre sans valeur, field__operator=value pour une valeur unique, et field__operator=value..value2 pour un filtre à deux valeurs tel que between. Les règles sont jointes par AND ou OR, et les parenthèses imbriquent un groupe :

/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)

Placez une valeur entre guillemets lorsqu'elle contient un espace ou une parenthèse : name__eq="quoted value". Une valeur de liste pour un filtre à sélection multiple tel que is one of est séparée par des virgules et ne nécessite pas de guillemets : status__in=ACTIVE,OUT_OF_STOCK.

Lorsque l'URL contient une chaîne filter invalide, comme un champ inconnu, un opérateur indisponible ou une valeur non analysable, l'application renvoie une erreur HTTP 400 plutôt que de rejeter silencieusement une partie de la condition.

Référence des filtres intégrés

Le tableau suivant recense chaque filtre disponible nativement, le slug URL visible dans un lien mis en favori, ainsi que le type de valeur attendu par chacun. Les filtres marqués « deux valeurs » nécessitent à la fois une value et une value2 dans l'URL, par exemple between=2026-01-01..2026-01-31.

Si vous avez besoin d'un filtre pour un type de données non couvert par les filtres intégrés, comme un champ JSON ou un point géographique, consultez Filtres personnalisés pour écrire une sous-classe de BaseFilter et l'enregistrer globalement ou pour une instance de champ donnée.

Et ensuite

• Filtres personnalisés : écrire et enregistrer une sous-classe de BaseFilter.
• Actions : ajouter des actions groupées et des actions sur les lignes à vos pages de listes.
• Vues : en savoir plus sur searchable_fields et le reste de la configuration de la page de liste.