Filtering

It is possible to define filters for Django types, which will be converted into .filter(...) queries for the ORM:

import strawberry_django
from strawberry import auto

@strawberry_django.filter(models.Fruit)
class FruitFilter:
    id: auto
    name: auto

@strawberry_django.type(models.Fruit, filters=FruitFilter)
class Fruit:
    ...  

The code above would generate following schema:

input FruitFilter {
  id: ID
  name: String
  AND: FruitFilter
  OR: FruitFilter
  NOT: FruitFilter
  DISTINCT: Boolean
}  

AND, OR, NOT, DISTINCT …

To every filter AND , OR , NOT & DISTINCT fields are added to allow more complex filtering

{
  fruits(
    filters: {
      name: "kebab"
      OR: {
        name: "raspberry"
      }
    }
  ) { ... }
}  

Lookups

Lookups can be added to all fields with lookups=True , which will add more options to resolve each type. For example:

@strawberry_django.filter(models.Fruit, lookups=True)
class FruitFilter:
    id: auto
    name: auto  

The code above would generate the following schema:

input IDBaseFilterLookup {
  exact: ID
  isNull: Boolean
  inList: [String!]
}

input StrFilterLookup {
  exact: ID
  isNull: Boolean
  inList: [String!]
  iExact: String
  contains: String
  iContains: String
  startsWith: String
  iStartsWith: String
  endsWith: String
  iEndsWith: String
  regex: String
  iRegex: String
}

input FruitFilter {
  id: IDFilterLookup
  name: StrFilterLookup
  AND: FruitFilter
  OR: FruitFilter
  NOT: FruitFilter
  DISTINCT: Boolean
}  

Single-field lookup can be annotated with the FilterLookup generic type.

from strawberry_django import FilterLookup

@strawberry_django.filter(models.Fruit)
class FruitFilter:
    name: FilterLookup[str]  

Filtering over relationships

@strawberry_django.filter(models.Color)
class ColorFilter:
    id: auto
    name: auto

@strawberry_django.filter(models.Fruit)
class FruitFilter:
    id: auto
    name: auto
    color: ColorFilter | None  

The code above would generate following schema:

input ColorFilter {
  id: ID
  name: String
  AND: ColorFilter
  OR: ColorFilter
  NOT: ColorFilter
}

input FruitFilter {
  id: ID
  name: String
  color: ColorFilter
  AND: FruitFilter
  OR: FruitFilter
  NOT: FruitFilter
}  

Custom filter methods

You can define custom filter method by defining your own resolver.

@strawberry_django.filter(models.Fruit)
class FruitFilter:
    name: auto
    last_name: auto

    @strawberry_django.filter_field
    def simple(self, value: str, prefix) -> Q:
        return Q(**{f"{prefix}name": value})

    @strawberry_django.filter_field
    def full_name(
        self,
        queryset: QuerySet,
        value: str,
        prefix: str
    ) -> tuple[QuerySet, Q]:
        queryset = queryset.alias(
            _fullname=Concat(
                f"{prefix}name", Value(" "), f"{prefix}last_name"
            )
        )
        return queryset, Q(**{"_fullname": value})

    @strawberry_django.filter_field
    def full_name_lookups(
        self,
        info: Info,
        queryset: QuerySet,
        value: strawberry_django.FilterLookup[str],
        prefix: str
    ) -> tuple[QuerySet, Q]:
        queryset = queryset.alias(
            _fullname=Concat(
                f"{prefix}name", Value(" "), f"{prefix}last_name"
            )
        )
        return strawberry_django.process_filters(
            filters=value,
            queryset=queryset,
            info=info,
            prefix=f"{prefix}_fullname"
        )  

[!TIP]

process_filters

As seen above strawberry_django.process_filters function is exposed and can be reused in custom methods. Above it’s used to resolve fields lookups

null values

By default null value is ignored for all filters & lookups. This applies to custom filter methods as well. Those won’t even be called (you don’t have to check for None ). This can be modified using strawberry_django.filter_field(filter_none=True)

This also means that built in exact & iExact lookups cannot be used to filter for None and isNull have to be used explicitly.

value resolution

• value parameter of type relay.GlobalID is resolved to its node_id attribute
• value parameter of type Enum is resolved to is’s value
• above types are converted in lists as well

resolution can modified via strawberry_django.filter_field(resolve_value=...)

• True - always resolve
• False - never resolve
• UNSET (default) - resolves for filters without custom method only

The code above generates the following schema:

input FruitFilter {
  name: String
  lastName: String
  simple: str
  fullName: str
  fullNameLookups: StrFilterLookup
}  

Resolver arguments

• prefix - represents the current path or position
  • Required
  • Important for nested filtering
  • In code bellow custom filter name ends up filtering Fruit instead of Color without applying prefix

@strawberry_django.filter(models.Fruit)
class FruitFilter:
    name: auto
    color: ColorFilter | None

@strawberry_django.filter(models.Color)
class ColorFilter:
    @strawberry_django.filter_field
    def name(self, value: str, prefix: str):
        # prefix is "fruit_set__" if unused root object is filtered instead
        if value:
            return Q(name=value)
        return Q()  

{
  fruits( filters: {color: name: "blue"} ) { ... }
}  

• value - represents graphql field type
  • Required, but forbidden for default filter method
  • must be annotated
  • used instead of field’s return type
• queryset - can be used for more complex filtering
  • Optional, but Required for default filter method
  • usually used to annotate QuerySet

Resolver return

For custom field methods two return values are supported

• django’s Q object
• tuple with QuerySet and django’s Q object -> tuple[QuerySet, Q]

For default filter method only second variant is supported.

What about nulls?

By default null values are ignored. This can be toggled as such @strawberry_django.filter_field(filter_none=True)

Overriding the default filter method

Works similar to field filter method, but:

• is responsible for resolution of filtering for entire object
• must be named filter
• argument queryset is Required
• argument value is Forbidden

@strawberry_django.filter(models.Fruit)
class FruitFilter:
    def ordered(
        self,
        value: int,
        prefix: str,
        queryset: QuerySet,
    ):
        queryset = queryset.alias(
          _ordered_num=Count(f"{prefix}orders__id")
        )
        return queryset, Q(**{f"{prefix}_ordered_num": value})

    @strawberry_django.order_field
    def filter(
        self,
        info: Info,
        queryset: QuerySet,
        prefix: str,
    ) -> tuple[QuerySet, list[Q]]:
        queryset = queryset.filter(
            ... # Do some query modification
        )

        return strawberry_django.process_filters(
            self,
            info=info,
            queryset=queryset,
            prefix=prefix,
            skip_object_order_method=True
        )  

Adding filters to types

All fields and CUD mutations inherit filters from the underlying type by default. So, if you have a field like this:

@strawberry_django.type(models.Fruit, filters=FruitFilter)
class Fruit:
    ...

@strawberry.type
class Query:
    fruits: list[Fruit] = strawberry_django.field()  

The fruits field will inherit the filters of the type in the same way as if it was passed to the field.

Adding filters directly into a field

Filters added into a field override the default filters of this type.

@strawberry.type
class Query:
    fruits: list[Fruit] = strawberry_django.field(filters=FruitFilter)  

Generic Lookup reference

There is 7 already defined Generic Lookup strawberry.input classes importable from strawberry_django

BaseFilterLookup

• contains exact , isNull & inList
• used for ID & bool fields

RangeLookup

• used for range or BETWEEN filtering

ComparisonFilterLookup

• inherits BaseFilterLookup
• additionaly contains gt , gte , lt , lte , & range
• used for Numberical fields

FilterLookup

• inherits BaseFilterLookup
• additionally contains iExact , contains , iContains , startsWith , iStartsWith , endsWith , iEndsWith , regex & iRegex
• used for string based fields and as default

DateFilterLookup

• inherits ComparisonFilterLookup
• additionally contains year ,month ,day ,weekDay ,isoWeekDay ,week ,isoYear & quarter
• used for date based fields

TimeFilterLookup

• inherits ComparisonFilterLookup
• additionally contains hour ,minute ,second ,date & time
• used for time based fields

DatetimeFilterLookup

• inherits DateFilterLookup & TimeFilterLookup
• used for timedate based fields

Legacy filtering

The previous version of filters can be enabled via USE_DEPRECATED_FILTERS

When using legacy filters it is important to use legacy strawberry_django.filters.FilterLookup lookups as well. The correct version is applied for auto annotated filter field (given lookups=True being set). Mixing old and new lookups might lead to error DuplicatedTypeName: Type StrFilterLookup is defined multiple times in the schema .

While legacy filtering is enabled new filtering custom methods are fully functional including default filter method.

Migration process could be composed of these steps:

• enable USE_DEPRECATED_FILTERS
• gradually transform custom filter field methods to new version (do not forget to use old FilterLookup if applicable)
• gradually transform default filter methods
• disable USE_DEPRECATED_FILTERS - This is breaking change