Strawberry — Schema and Features

This page continues directly from Strawberry with FastAPI and assumes the same strawberry-graphql[fastapi] installation. Examples below assume these imports are in scope:

A custom scalar pairs a GraphQL name with Python serialize/parse_value functions that convert between the wire representation and a native Python type — the same serialize/parseValue/parseLiteral contract covered language-agnostically in Interfaces, Unions \& Inputs:

strawberry.scalar(…​) can wrap any Python type this way, and Strawberry also ships several scalars out of the box (strawberry.ID, JSON, Void) alongside the five SDL-defined scalars (Int, Float, String, Boolean, ID) that map directly onto Python’s int, float, str, and bool.

A Python enum.Enum becomes a GraphQL enum type by decorating it with @strawberry.enum; each member name is exposed to clients exactly as written, so members are conventionally named in SCREAMING_SNAKE_CASE to match GraphQL enum-value conventions:

Resolvers can accept and return BookGenre members like any other Python enum value; Strawberry handles the GraphQL-name-to-Python-member translation transparently in both directions.

@strawberry.interface declares a set of fields that multiple object types share; a concrete type opts in by inheriting from the interface class, and Strawberry resolves the correct concrete GraphQL type for each instance automatically from the Python class hierarchy:

No explicit resolve_type hook is required for this common case — Strawberry inspects the Python class of the value returned from a resolver and matches it against the interface’s registered implementations. A custom resolve_type is only needed when a field returns plain dictionaries or a type Strawberry cannot otherwise map, which is covered alongside `resolveType’s language-agnostic role in Interfaces, Unions \& Inputs.

A Strawberry union is a typing.Union of @strawberry.type classes, most often built with strawberry.union to give the union type an explicit GraphQL name:

As with interfaces, Strawberry infers which union member a given value maps to from its Python class, so a resolver simply returns instances of the member types and the schema’s __typename resolution follows without extra configuration.

A Generic[T] class decorated with @strawberry.type becomes a reusable GraphQL type template — Strawberry generates one concrete GraphQL type per type parameter it is instantiated with, which is the idiomatic way to build a paginated Connection-shaped wrapper without repeating its fields for every entity:

Page[Book] above produces a BookPage GraphQL type in the emitted schema; a second call site using Page[Author] would produce a distinct AuthorPage type, each generated from the same generic definition.

@strawberry.input marks a class as a GraphQL input object type — the argument-structuring construct covered language-agnostically in Interfaces, Unions \& Inputs — and is the idiomatic way to group several mutation arguments into one typed argument:

Fields with default values, like genre above, become optional on the generated AddBookInput GraphQL type; fields without a default are required arguments a client must supply.

strawberry.Private[T] marks a dataclass attribute as invisible to GraphQL entirely — it exists on the Python object for resolvers and business logic to read, but Strawberry excludes it from the generated schema and from introspection:

This is the idiomatic way to carry server-only data alongside a type’s public fields — an internal score used only to compute is_highly_rated above, a raw database row, or a cache key — without accidentally exposing it as a queryable field.

A BasePermission subclass centralizes an authorization check that would otherwise be repeated inside every resolver body; field(permission_classes=[…​]) attaches one or more permission classes to a specific field, and Strawberry runs has_permission before the resolver executes, short-circuiting with the class’s message-carrying error when it returns False:

Multiple permission classes on the same field are evaluated in order, and any one of them returning False denies access without running the rest. This complements, rather than replaces, the broader authorization model covered in Authorization — a BasePermission is a convenient place for a per-field policy check, but authentication itself and domain-layer authorization decisions still belong where that page describes. See Strawberry — Permissions for the full reference, including class-based composition and async has_permission implementations.

strawberry.dataloader.DataLoader batches many single-key lookups issued during one GraphQL request into a single call, and caches results for the lifetime of the request so the same key is never fetched twice — Strawberry’s implementation of the batch-and-cache pattern introduced language-agnostically in Performance \& N+1:

The batch function above always receives keys in the exact order .load(…​) was called for them, and must return a same-length list of results in that same order — DataLoader matches results back to callers positionally, not by re-inspecting the keys. A fresh DataLoader instance is expected once per request (usually constructed inside the context_getter covered on the previous page), since caching results across requests would leak one user’s data into another’s. See Strawberry — DataLoaders for batching multiple different key shapes, priming the cache ahead of time, and disabling caching for a specific loader.

A resolver that raises a Python exception surfaces as a top-level GraphQL error in the response’s errors array — the envelope shape covered language-agnostically in Response and Error Handling. For expected, client-facing failure cases, the idiomatic Strawberry pattern is instead to model the failure as data using a union return type, so a client can distinguish "found nothing" from "the server broke" via __typename rather than by parsing an error message:

Strawberry also exposes strawberry.exceptions.StrawberryGraphQLError for raising an error with custom extensions attached, and a schema-level process_errors hook for logging or reshaping every error before it reaches the response, for the cases where the top-level errors array genuinely is the right place to report a failure.

strawberry.relay implements the Relay Cursor Connections specification — Pagination's Connection/Edge/PageInfo shapes — so a paginated field can be declared without hand-writing that boilerplate. relay.Node also implements the Global Object Identification Node interface, giving a type an opaque, globally unique id for free:

relay.connection wires up the first/after/last/before arguments and the Connection/Edge/PageInfo response shape automatically from the resolver’s returned iterable; relay.NodeID marks which field on Book becomes the opaque part of its globally unique Relay ID, distinct from any id field the underlying data source already exposes. A schema built this way also gets a node(id:) root field for free, resolving any relay.Node subclass back from its opaque ID exactly as Global Object Identification describes. See Strawberry — Relay for cursor encoding customization, connection resolvers backed by a database LIMIT/OFFSET or keyset query, and the @relay.connection decorator form.

The strawberry export-schema CLI command prints a Strawberry schema’s SDL representation to standard output, which is the usual way to commit a generated .graphql schema file to version control or feed it to another tool’s codegen step:

myapp.schema:schema above is a Python import path — module myapp.schema, attribute schema — pointing at the strawberry.Schema instance to export. This is useful independent of any particular client: a client-side codegen tool (such as the ones covered in Clients overview) typically needs the SDL on disk rather than a running server to introspect, and keeping the exported file in version control makes schema changes visible in code review.

Because Strawberry types are plain dataclasses decorated at runtime, static analyzers cannot infer GraphQL-specific behavior — such as a @strawberry.field-decorated method’s true return type, or that a strawberry.Private attribute should be excluded from constructor checks — without help. Strawberry ships a mypy plugin that teaches mypy these semantics, enabled via pyproject.toml:

With the plugin enabled, mypy type-checks resolver signatures, input type construction, and generic type instantiations (such as the Page[Book] example earlier on this page) with the same accuracy it would apply to an equivalent, non-decorated dataclass.

This page covered Strawberry’s type-system extensions and runtime features beyond the FastAPI basics; two siblings cover the surrounding ground: