Group Reference¶

By default, a FilterSet validates and then filters its query parameters independently of each other, ultimately resulting in a chain of .filter() calls. Due to the nature of filter chaining, it’s not trivial to, for example, make a group of filters that are mutually exclusive to each other.

Filter groups solve this limitation by processing subsets of parameters together, enabling higher level validation and filtering behavior.

Validation¶

A filter group only applies group-level validation. For example, a mutually exclusive group is responsible for validating that only one of its parameters is present. It is not responsible for validating the individual values, which is still performed by the underlying filter instances.

Filtering¶

In contrast to validation, a filter group overrides its filtering behavior. Internally, a group may use the .filter() methods of its filters, but it might also override it completely. For example, the RequiredGroup delegates filtering to each of its underlying filters, while CombinedRequiredGroup constructs a Q object.

Builtin Groups:¶

`BaseFilterGroup`(filters)	Base class for validating & filtering query parameters as a group.
`ExclusiveGroup`(filters)	A group of mutually exclusive filters.
`RequiredGroup`(filters)	A group of mutually required filters.
`CombinedGroup`(filters[, combine])	A group of filters that result in a combined query (a `Q` object).
`CombinedRequiredGroup`(filters[, combine])	A group of mutually required filters that result in a combined query.

BaseFilterGroup¶

class django_filters.groups.BaseFilterGroup(filters)¶

Base class for validating & filtering query parameters as a group.

abstract validate(form, **data)¶

Validate the subset of cleaned data provided by the form.

Parameters

form – The underlying Form instance used to validate the query params. A FilterGroup should add errors to this form using form.add_error(<field name>, <error message>).
**data – The subset of a form’s cleaned_data for the filters in the group.

abstract filter(qs, **data)¶

Filter the result queryset with the subset of cleaned data.

Parameters

qs – The QuerySet instance to filter.
**data – The subset of a form’s cleaned_data for the filters in the group.

Returns

The filtered queryset instance.

format_labels(filters)¶

Return a formatted string of labels for the given filter names.

This inspects the filter labels from the self.parent FilterSet, and combines them into a formatted string. This string can then be used in validation error messages.

Parameters

filters – A list of filter names.

Returns

The formatted string of labels. For example, if filters ‘a’, ‘b’, and ‘c’ have corresponding labels ‘Filter A’, ‘Filter B’, and ‘Filter C’, then…

>>> group.format_labels(['a', 'b'])
"'Filter A' and 'Filter B'"

>>> group.format_labels(['a', 'b', 'c'])
"'Filter A', 'Filter B', and 'Filter C'"

ExclusiveGroup¶

class django_filters.groups.ExclusiveGroup(filters)¶

A group of mutually exclusive filters.

If any filter in the group is included in the request data, then all other filters in the group must not be present in the request data.

filters¶: The set of filter names to operate on.

RequiredGroup¶

class django_filters.groups.RequiredGroup(filters)¶

A group of mutually required filters.

If any filter in the group is included in the request data, then all other filters in the group must be present in the request data. Filtering is still performed by the individual filters and is not combined via Q objects. To use Q objects instead (e.g., for OR-based filtering), use the CombinedRequiredGroup.

filters¶: The set of filter names to operate on.

CombinedGroup¶

class django_filters.groups.CombinedGroup(filters, combine=<built-in function and_>)¶

A group of filters that result in a combined query (a Q object).

This implementation combines Q objects instead of chaining .filter() calls. The Q objects are generated from the filter’s field_name, lookup_expr, and exclude attributes, and the resulting queryset will call .distinct() if set on any of the filters.

In short, instead of generating the following filter call:

qs.filter(a=1).filter(b=2)

This group would generate a call like:

qs.filter(Q(a=1) & Q(b=2))

This is useful for enabling OR filtering, as well as combining filters that span multi-valued relationships (more info).

filters¶: The set of filter names to operate on.

combine¶: A function that combines two Q objects. Defaults to operator.and_. For OR operations, use operator.or_.

CombinedRequiredGroup¶

class django_filters.groups.CombinedRequiredGroup(filters, combine=<built-in function and_>)¶

A group of mutually required filters that result in a combined query.

This combines the validation logic of a RequiredGroup with the filtering logic of a CombinedGroup.

filters¶: The set of filter names to operate on.

combine¶: A function that combines two Q objects. Defaults to operator.and_. For OR operations, use operator.or_.