Mutations

Getting started

Mutations can be defined the same way as strawberry’s mutations , but instead of using @strawberry.mutation , use @strawberry_django.mutation .

Here are the differences between those:

• Strawberry Django’s mutation will be sure that the mutation is executed in an async safe environment, meaning that if you are running ASGI and you define a sync resolver, it will automatically be wrapped in a sync_to_async call.
• It will better integrate with the permission integration
• It has an option to automatically handle common django errors and return them in a standardized way (more on that below)

Django errors handling

When defining a mutation you can pass handle_django_errors=True to make it handle common django errors, such as ValidationError , PermissionDenied and ObjectDoesNotExist :

@strawberry.type
class Mutation:
    @strawberry_django.mutation(handle_django_errors=True)
    def create_fruit(self, name: str, color: str) -> Fruit:
        if not is_valid_color(color):
            raise ValidationError("The color is not valid")

        # Creation can also raise ValidationError, if the `name` is
        # larger than its allowed `max_length` for example.
        fruit = models.Fruit.objects.create(name=name)
        return cast(Fruit, fruit)  

The code above would generate following schema:

enum OperationMessageKind {
  INFO
  WARNING
  ERROR
  PERMISSION
  VALIDATION
}

type OperationInfo {
  """List of messages returned by the operation."""
  messages: [OperationMessage!]!
}

type OperationMessage {
  """The kind of this message."""
  kind: OperationMessageKind!

  """The error message."""
  message: String!

  """
  The field that caused the error, or `null` if it isn't associated with any particular field.
  """
  field: String

  """The error code, or `null` if no error code was set."""
  code: String
}

type Fruit {
  name: String!
  color: String!
}

union CreateFruitPayload = Fruit | OperationInfo

mutation {
  createFruit(
    name: String!
    color: String!
  ): CreateFruitPayload!
}  

Input mutations

Those are defined using @strawberry_django.input_mutation and act the same way as the @strawberry_django.mutation , the only difference being that it injects an InputMutationExtension in the field, which converts its arguments in a new type (check the extension’s docs for more information).

CUD mutations

The following CUD mutations are provided by this lib:

• strawberry_django.mutations.create : Will create the model using the data from the given input
• strawberry_django.mutations.update : Will update the model using the data from the given input
• strawberry_django.mutations.delete : Will delete the model using the id from the given input

A basic example would be:

from strawberry import auto
from strawberry_django import mutations, NodeInput
from strawberry.relay import Node



@strawberry_django.type(SomeModel)
class SomeModelType(Node):
    name: auto

@strawberry_django.input(SomeModel)
class SomeModelInput:
    name: auto


@strawberry_django.partial(SomeModel)
class SomeModelInputPartial(NodeInput):
    name: auto

@strawberry.type
class Mutation:
    create_model: SomeModelType = mutations.create(SomeModelInput)
    update_model: SomeModelType = mutations.update(SomeModelInputPartial)
    delete_model: SomeModelType = mutations.delete(NodeInput)  

Some things to note here:

• Those CUD mutations accept the same arguments as @strawberry_django.mutation accepts. This allows you to pass handle_django_errors=True to it for example.
• The mutation will receive the type in an argument named "data" by default. To change it to "info" for example, you can change it by passing argument_name="info" to the mutation, or set MUTATIONS_DEFAULT_ARGUMENT_NAME="info" in your strawberry django settings to make it the default when not provided.
• Take note that inputs using partial will not automatically mark non-auto fields optional and instead will respect explicit type annotations; see partial input types documentation for examples.
• It’s also possible to update or delete a model using a unique identifier other than id by passing a key_attr argument:

@strawberry_django.partial(SomeModel)
class SomeModelInputPartial:
    unique_field: strawberry.auto

@strawberry.type
class Mutation:
    update_model: SomeModelType = mutations.update(
        SomeModelInputPartial,
        key_attr="unique_field",
    )
    delete_model: SomeModelType = mutations.delete(
        SomeModelInputPartial,
        key_attr="unique_field",
    )  

Filtering

Filters can be added to update and delete mutations. More information in the filtering section.

import strawberry
from strawberry_django import mutations

@strawberry.type
class Mutation:
    updateFruits: list[Fruit] = mutations.update(FruitPartialInput, filters=FruitFilter)
    deleteFruits: list[Fruit] = mutations.delete(filters=FruitFilter)

schema = strawberry.Schema(mutation=Mutation)  

Batching

If you need to make multiple creates, updates, or deletes as part of one atomic mutation you can use batching. Batching has a similar syntax except that the mutations take and return a list.

import strawberry
from strawberry_django import mutations

@strawberry.type
class Mutation:
    createFruits: list[Fruit] = mutations.create(list[FruitPartialInput])
    updateFruits: list[Fruit] = mutations.update(list[FruitPartialInput])
    deleteFruits: list[Fruit] = mutations.delete(list[FruitPartialInput])

schema = strawberry.Schema(mutation=Mutation)