Ordering

@strawberry_django.ordering_type is an upgrade from the previous @strawberry_django.order implementation and allows sorting by multiple fields.

@strawberry_django.order_type(models.Color)
class ColorOrder:
  name: auto


@strawberry_django.order_type(models.Fruit)
class FruitOrder:
  name: auto
  color: ColorOrder | None

Tip

In most cases ordering fields should have Optional annotations and default value strawberry.UNSET . Above auto annotation is wrapped in Optional automatically. UNSET is automatically used for fields without field or with strawberry_django.order_field .

The code above generates the following schema:

enum Ordering {
  ASC
  ASC_NULLS_FIRST
  ASC_NULLS_LAST
  DESC
  DESC_NULLS_FIRST
  DESC_NULLS_LAST
}

input ColorOrder @oneOf {
  name: Ordering
}

input FruitOrder @oneOf {
  name: Ordering
  color: ColorOrder
}

As you can see, every input is automatically annotated with @oneOf . To express ordering by multiple fields, a list is passed.

Custom order methods

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

@strawberry_django.order_type(models.Fruit)
class FruitOrder:
  name: auto

  @strawberry_django.order_field
  def discovered_by(self, value: bool, prefix: str) -> list[str]:
    if not value:
      return []
    return [f"{prefix}discover_by__name", f"{prefix}name"]

  @strawberry_django.order_field
  def order_number(
          self,
          info: Info,
          queryset: QuerySet,
          value: strawberry_django.Ordering,  # `auto` can be used instead
          prefix: str,
  ) -> tuple[QuerySet, list[str]] | list[str]:
    queryset = queryset.alias(
      _ordered_num=Count(f"{prefix}orders__id")
    )
    ordering = value.resolve(f"{prefix}_ordered_num")
    return queryset, [ordering]

Warning

Do not use queryset.order_by() directly. Due to order_by not being chainable operation, changes applied this way would be overridden later.

Tip

The strawberry_django.Ordering type has convenient method resolve that can be used to convert field’s name to appropriate F object with correctly applied asc() , desc() method with nulls_first and nulls_last arguments.

The code above generates the following schema:

enum Ordering {
  ASC
  ASC_NULLS_FIRST
  ASC_NULLS_LAST
  DESC
  DESC_NULLS_FIRST
  DESC_NULLS_LAST
}

input FruitOrder @oneOf {
  name: Ordering
  discoveredBy: bool
  orderNumber: Ordering
}

Resolver arguments

prefix - represents the current path or position
- Required
- Important for nested ordering
- In code below custom order name ends up ordering Fruit instead of Color without applying prefix

@strawberry_django.order_type(models.Fruit)
class FruitOrder:
  name: auto
  color: ColorOrder | None


@strawberry_django.order_type(models.Color)
class ColorOrder:
  @strawberry_django.order_field
  def name(self, value: bool, prefix: str):
    # prefix is "fruit_set__" if unused root object is ordered instead
    if value:
      return ["name"]
    return []

{
  fruits( ordering: [{color: name: ASC}] ) { ... }
}

value - represents graphql field type
- Required, but forbidden for default order method
- must be annotated
- used instead of field’s return type
- Using auto is the same as strawberry_django.Ordering .
queryset - can be used for more complex ordering
- Optional, but Required for default order method
- usually used to annotate QuerySet

Resolver return

For custom field methods two return values are supported

iterable of values acceptable by QuerySet.order_by -> Collection[F | str]
tuple with QuerySet and iterable of values acceptable by QuerySet.order_by -> tuple[QuerySet, Collection[F | str]]

For default order method only second variant is supported.

What about nulls?

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

Overriding the default `order` method

Works similar to field order method, but:

is responsible for resolution of ordering for entire object
must be named order
argument queryset is Required
argument value is Forbidden

@strawberry_django.order_type(models.Fruit)
class FruitOrder:
  name: auto

  @strawberry_django.order_field
  def ordered(
          self,
          info: Info,
          queryset: QuerySet,
          value: strawberry_django.Ordering,
          prefix: str
  ) -> tuple[QuerySet, list[str]] | list[str]:
    queryset = queryset.alias(
      _ordered_num=Count(f"{prefix}orders__id")
    )
    return queryset, [value.resolve(f"{prefix}_ordered_num")]

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

    return strawberry_django.ordering.process_ordering_default(
      self,
      info=info,
      queryset=queryset,
      prefix=prefix,
    )

Tip

As seen above strawberry_django.ordering.process_ordering_default function is exposed and can be reused in custom methods. This provides the default ordering implementation.

Adding orderings to types

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

@strawberry_django.type(models.Fruit, ordering=FruitOrder)
class Fruit:
    ...

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

Adding orderings directly into a field

Orderings added into a field override the default order of this type.

@strawberry.type
class Query:
    fruit: Fruit = strawberry_django.field(ordering=FruitOrder)

Legacy Order

The previous implementation (@strawberry_django.order ) is still available, but deprecated and only provided to allow backwards-compatible schemas. It can be used together with @strawberry_django.ordering.ordering , however clients may only specify one or the other. You can still read the documentation for it .