Operation directives

GraphQL uses directives to modify the evaluation of an item in the schema or the operation. Operation directives can be included inside any operation (query, subscription, mutation) and can be used to modify the execution of the operation or the values returned by the operation.

Directives can help avoid having to create resolvers for values that can be computed via the values of additional fields.

All Directives are proceeded by @ symbol

Default Operation directives

Strawberry provides the following default operation directives:

• @skip(if: Boolean!) - if Boolean is true, the given item is NOT resolved by the GraphQL Server

• @include(if: Boolean!) - if Boolean is false, the given item is NOT resolved by the GraphQL Server

Experimental Directives

When experimental incremental execution is enabled, these additional directives become available:

• @defer(if: Boolean, label: String) - Allows fields to be resolved asynchronously and delivered incrementally. The field will be omitted from the initial response and sent in a subsequent payload.

• @stream(if: Boolean, label: String, initialCount: Int) - Enables streaming of list fields. The list will be delivered incrementally, with initialCount items in the initial response and remaining items in subsequent payloads.

These experimental directives require graphql-core>=3.3.0a9 and must be enabled via schema configuration. See Defer and Stream for detailed usage information.

@deprecated(reason: String) IS NOT compatible with Operation directives. @deprecated is exclusive to Schema Directives

Examples of Default Operation directives

# @include
query getPerson($includePoints: Boolean!) {
  person {
    name
    points @include(if: $includePoints)
  }
}

# @skip
query getPerson($hideName: Boolean!) {
  person {
    name @skip(if: $hideName)
    points
  }
}

Custom Operation directives

Custom directives must be defined in the schema to be used within the query and can be used to decorate other parts of the schema.

# Definition
@strawberry.directive(
    locations=[DirectiveLocation.FIELD], description="Make string uppercase"
)
def turn_uppercase(value: DirectiveValue[str]):
    return value.upper()


@strawberry.directive(locations=[DirectiveLocation.FIELD])
def replace(value: DirectiveValue[str], old: str, new: str):
    return value.replace(old, new)

# Use
query People($identified: Boolean!) {
  person {
    name @turnUppercase
  }
  jess: person {
    name @replace(old: "Jess", new: "Jessica")
  }
  johnDoe: person {
    name @replace(old: "Jess", new: "John") @include(if: $identified)
  }
}

Locations for Operation directives

Directives can only appear in specific locations inside the query. These locations must be included in the directive's definition. In Strawberry the location is defined in the directive function's parameter locations.

@strawberry.directive(locations=[DirectiveLocation.FIELD])

Operation directives possible locations

Operation directives can be applied to many different parts of an operation. Here's the list of all the allowed locations:

• QUERY
• MUTATION
• SUBSCRIPTION
• FIELD
• FRAGMENT_DEFINITION
• FRAGMENT_SPREAD
• INLINE_FRAGMENT