strawberry-orm

Backend-agnostic schema generation for Strawberry GraphQL on top of Django ORM, SQLAlchemy, and Tortoise ORM.

Warning — strawberry-orm is still in alpha. Expect breaking changes and incomplete APIs while the package stabilizes.

Contents

Start here: Installation · Quick start · Choose a backend · How loading works

Before you ship: Security · Production baseline

Feature guide: Defining types · Declaring fields · Filters and ordering · Custom filters and ordering · Grouping and aggregation · Payloads · Mutations · Relay · Async

Reference: API reference · Backend options · Public exports · Full example

Installation

uv add "strawberry-orm[sqlalchemy]"   # or [django] or [tortoise]

Or with pip:

pip install "strawberry-orm[sqlalchemy]"

Requires Python >=3.12 and strawberry-graphql>=0.311.0.

Quick start

Minimal blog API: users with published posts only. Assumes SQLAlchemy models User and Post where Post.is_published is a boolean. See Choose a backend to wire session context.

# SQLAlchemy
import strawberry
from strawberry_orm import StrawberryORM, auto

orm = StrawberryORM.for_sqlalchemy(
    dialect="postgresql",
    session_getter=lambda info: info.context["session"],
)

@orm.type(Post)
class PostType:
    id: auto
    title: auto

    @classmethod
    def scope_rows(cls, select, info):
        # hide drafts everywhere Post loads
        return select.where(Post.is_published.is_(True))

@orm.type(User)
class UserType:
    id: auto
    name: auto
    posts: list[PostType]

@strawberry.type
class Query:
    users: list[UserType] = orm.field.auto()

schema = orm.schema(query=Query)

QUERY = "{ users { name posts { title } } }"
# result = schema.execute_sync(QUERY, context_value={"session": session})
# → drafts excluded; only published post titles under each user

Drafts are hidden because PostType.scope_rows runs wherever Post rows load — including under users. How loading works explains why, and what you still have to configure yourself.

The field declarations

id: auto and posts: list[PostType] above are the two you need most. Here is the whole menu — orm.field has four named forms, and the name says when your code runs.

On a type — every field on an @orm.type class is one of these:

# SQLAlchemy — see "Reading the examples" for the Django / Tortoise spelling
@orm.type(Post)
class PostType:
    # --- declared: the library resolves it, you describe it ---------------------
    title: auto                                     # a column
    author: UserType                                # a relation, eager-loaded

    body: auto = orm.field.auto(                    # metadata on a resolved field
        permission_classes=[IsAdmin],               # field permissions
        description="Post body",                    # forwarded to Strawberry
    )
    tags: list[TagType] = orm.field.auto(
        filters=TagFilter, order=TagOrder,          # adds filter/order arguments
        using=["author"],                           # also load Post.author
    )                                               # also: compute=, disable_optimization=

    # --- scoped: (query, info), once while the prefetch is built ----------------
    @orm.field.scoped                               # named for the relation
    def comments(select, info) -> list[CommentType]:            # it narrows
        return select.where(Comment.is_public.is_(True))

    # --- written: (self, info), once per parent row -----------------------------
    @orm.field.custom                               # returns rows: hand back the
    def recent(self, info: strawberry.Info) -> list[CommentType]:   # query itself,
        return select(Comment).where(Comment.post_id == self.id)    # unexecuted

    @orm.field.custom(filters=CommentFilter)        # ...with filter/order arguments
    def searchable(self, info: strawberry.Info) -> list[CommentType]:
        return select(Comment).where(Comment.post_id == self.id)

    @orm.field.computed(using=["author"])           # returns a value read off
    def byline(self, info: strawberry.Info) -> str: # a relation
        return f"by {self.author.name}"

    @strawberry.field                               # plain Strawberry, no ORM
    def slug(self, info: strawberry.Info) -> str:
        return self.title.lower().replace(" ", "-")


@orm.type(User)
class UserType:
    posts: list[PostType] = orm.field.scoped(       # the inline spelling of
        lambda select, info: select.where(Post.is_published.is_(True))
    )

There is one scope per relation, and it carries that relation's name — comments above scopes Post.comments. A second, differently-filtered view is a custom resolver.

On the query root — the same forms, minus a parent row:

# SQLAlchemy
@strawberry.type
class Query:
    posts: list[PostType] = orm.field.auto()                      # generated resolver
    filtered: list[PostType] = orm.field.auto(filters=PostFilter) # ...with arguments

    @orm.field.custom                                             # your own criteria
    def published(self, info: strawberry.Info) -> list[PostType]:
        return select(Post).where(Post.is_published.is_(True))

    posts_page: ORMListConnection[PostType] = orm.connection()    # Relay

The split that matters: auto and scoped run once while the prefetch is built, so they cost one query no matter how many parents there are; custom and computed run once per parent row and receive self. Declaring fields covers how to choose, what the library checks for you, and the older spellings that still work.

Choose a backend

Every backend generates the same schema; they differ in how the session reaches a resolver.

Sync and async execution both work on Django; a custom async resolver that touches the ORM directly still needs sync_to_async(...).

Every constructor takes the same tuning options — limits, warnings, optimizer switches. They are listed under Backend options; the defaults are safe to start with.

Reading the examples

Everything strawberry-orm generates — types, filters, ordering, grouping, mutations — is identical across the three backends. What differs is the query object your own callables receive and return, in exactly one place: whenever you write a scope_rows, a scope=, or a resolver that returns rows.

Each code block below says which backend it is written in. Where only the query expression differs, translate it with this table rather than expecting a different API.

How loading works

The one rule: the optimizer can only add loads while the query is unexecuted. The first value that materializes ends optimization for everything beneath it.

Returning list(...), .first(), or already-loaded instances from a field means nothing below it can be eager-loaded or scoped. Every behaviour in this chapter follows from that.

Three layers are involved. Your Strawberry types and the client's selection set decide what is asked for; the optimizer mounted by orm.schema() turns that into loads and applies scoping; the ORM backend runs the SQL.

Resolution flow

For { users { name posts { title } } }:

1. Query.users returns a User queryset/select. UserType.scope_rows may filter it — including joins on related tables, which only affects which users match.
2. The optimizer walks the selection set and sees posts under users.
3. To build the prefetch it calls PostType.scope_rows, plus any scope= on UserType.posts. This is a separate scoping step for Post rows, not a re-run of UserType.scope_rows.
4. One batched query loads the users and their scoped posts.
5. GraphQL reads user.posts from the prefetched data. No further scoping pass happens on Django or SQLAlchemy for plain annotation relations.

flowchart TD
  Q["Query.users"] --> R["Root resolver returns User select/queryset"]
  R --> O["Optimizer: apply UserType.scope_rows"]
  O --> W["Walk selection set → sees posts"]
  W --> P["Build prefetch: PostType.scope_rows + scope=callable"]
  P --> SQL["Execute batched SQL"]
  SQL --> G["GraphQL serializes instances"]

scope_rows — one model, one type

scope_rows is the row-access boundary for a model: it is handed the query about to run and returns a narrowed one. It pairs with the field-level orm.field.scoped — same idea, one on the type, one on a single relation edge.

@orm.type(Post)                          # Django / Tortoise
class PostType:
    id: auto
    title: auto

    @classmethod
    def scope_rows(cls, queryset, info):
        return queryset.filter(is_published=True)


@orm.type(Post)                          # SQLAlchemy
class PostType:
    id: auto
    title: auto

    @classmethod
    def scope_rows(cls, select, info):
        return select.where(Post.is_published.is_(True))

The hook is always called positionally, so name the parameter after whatever your ORM actually hands you:

Define it on the @orm.type class for the model being loaded. A nested query runs one hook per model, not one hook for the whole path:

Renamed from get_queryset in 0.15. The old name named a Django type that only two of the three backends use, and get_ suggested it returns a fresh query rather than narrowing the one it is handed. warn_missing_queryset is now warn_missing_scope.

Parent scoping does not flow to children

This is the mistake that bites hardest, so it is worth one careful example.

users { posts { … } } looks like a single tree, but the ORM loads it in two steps: User rows first, then Post rows. A filter on the parent type restricts which parents come back. It does not restrict the children — even when that filter joins the child table.

# Django
@orm.type(User)
class UserType:
    id: auto
    name: auto
    posts: list[PostType]

    @classmethod
    def scope_rows(cls, queryset, info):
        return queryset.filter(posts__is_published=True).distinct()

@orm.type(Post)
class PostType:
    id: auto
    title: auto
    # no scope_rows

Given this data:

{ users { name posts { title } } } returns:

{
  "users": [
    { "name": "Alice", "posts": [{ "title": "Hello world" }, { "title": "Secret draft" }] }
  ]
}

Bob is gone, because the parent filter asked does this user have a published post — and Alice does. But the draft is still there: loading Post rows never consulted UserType.scope_rows again, and PostType has no scope of its own. The join tested existence; it did not filter the child rows.

The fix is to scope the model wherever it loads:

# Django
@orm.type(Post)
class PostType:
    id: auto
    title: auto

    @classmethod
    def scope_rows(cls, queryset, info):
        return queryset.filter(is_published=True)

Now { posts { title } } and { users { posts { title } } } both hide drafts. The same reasoning covers tenant IDs, soft deletes, and permissions: scope every model type a client can reach, and never assume a parent join stands in for a child scope.

Resolver kinds

How a field is written decides what scoping it gets.

The first four rows are all orm.field, which has four named forms that run at different times and take different arguments — see The four kinds of field.

Type-level and field-level scopes compose in that order — scope_rows first, then scope= — and both run before SQL executes.

Relation scoping does not depend on the optimizer. When the optimizer runs it applies the scope once while building the eager load; when it does not, the scope is applied again as each parent's relation is read. Either way the rows are scoped — the difference is how many queries it takes. The root field is the exception: scope_rows on a root query object is applied by the optimizer, so build with orm.schema().

Root custom query

A root Query field returns rows directly rather than through a relation. With orm.schema(), returning an unexecuted select or queryset still engages the optimizer: your filter composes with UserType.scope_rows, and nested fields still get their own type's hook at prefetch time.

# SQLAlchemy
@strawberry.type
class Query:
    @orm.field.custom
    def active_users(self, info: strawberry.Info) -> list[UserType]:
        return select(User).where(User.is_active.is_(True))   # ✓ query object
        # return session.scalars(...).all()                   # ✗ materialized

Use scope_rows when the same rule applies everywhere the model loads, and a custom root resolver when the criteria belong to that one entry point. See List Fields for a comparison.

Rows a resolver already fetched

A resolver that returns rows rather than a query object gives the optimizer nothing to add eager loads to. It handles that case anyway: the rows are all it needs, so it loads their relations onto them.

# Django
@strawberry.field
def create_post(self, info: strawberry.Info, ...) -> PostType:
    return Post.objects.create(...)      # relations below still eager-loaded

This reaches rows nested inside a wrapper too. A payload's data is a resolved field in its own right, so the rows arrive with exactly the selection that describes them.

Relations are loaded onto the rows you returned, so a value you just set in memory is never overwritten by a re-read of the database — the mutation above reports the title it wrote, not the one in the database.

# Django
rows = list(Post.objects.filter(...))
orm.optimize(rows, info)

orm.schema()

Build schemas with orm.schema(). The optimizer is enabled by default: it executes query objects, eager-loads relations from the selection set, applies field hints, and honours scope_rows. On Django and SQLAlchemy nested scoping depends on it, so this is not an optional performance tweak.

schema = orm.schema(query=Query, mutation=Mutation)
schema = orm.schema(query=Query, extensions=[MyCustomExtension()])

schema = orm.schema(query=Query, optimizer=False)              # opt out per schema
orm = StrawberryORM.for_sqlalchemy(enable_optimizer=False, …)  # or globally

Telling the optimizer what to load

The optimizer follows the selection set, so a relation the client asks for is prefetched without you saying anything. Two cases it cannot see:

@orm.type(Post)
class PostType:
    # a resolver reads a relation the query never selected
    @orm.field.computed(using=["author"])
    def byline(self, info: strawberry.Info) -> str:
        return f"by {self.author.name}"

@orm.type(User)
class UserType:
    # only some of the related rows should load
    posts: list[PostType] = orm.field.auto(scope=lambda qs, info: qs.filter(is_published=True))

using= answers what to load, scope= answers which rows. Both run while the prefetch is built, so using=["author"] becomes select_related on Django, joinedload / selectinload on SQLAlchemy, and prefetch_related on Tortoise — one query, not one per row.

A scope= callable receives (qs, info) and never the parent instance, which is exactly what lets the optimizer hoist it. When the query really does depend on the parent row, write a resolver instead.

Names are validated when the type is defined, so a typo fails immediately rather than silently doing nothing:

ValueError: PostType.byline: Post has no relation 'athor'. Did you mean 'author'?

See Declaring fields for the full set of forms and arguments.

Relation batching

A resolver on a relation field runs once per parent row, so { users { posts { … } } } over 250 users is 251 statements. When the resolver returns an unexecuted query, the optimizer rewrites that into one statement per query shape:

# Django
@orm.type(User)
class UserType:
    name: auto

    @strawberry.field
    def posts(self, info: strawberry.Info) -> list[PostType]:
        return Post.objects.filter(author=self, is_published=True)

Parents are already in memory and building a queryset touches no database, so the resolver runs for every sibling parent up front, the parent predicate is reflected out of each query, and the remainders are grouped. Branching therefore costs one statement per branch rather than one per row:

# Django
if self.is_admin:
    return Post.objects.filter(author=self)
return Post.objects.filter(author=self, is_published=True)

Batched queries take the same optimizer path as per-row ones, so the child type's scope_rows and scope= still apply. Turn it off with batch_relations=False.

# Django
@classmethod
def scope_rows(cls, queryset, info):
    print("SCOPE:PostType.scope_rows", flush=True)
    return queryset.filter(is_published=True)

posts: list[PostType] = orm.field.scoped(
    lambda qs, info: (
        print("SCOPE:UserType.posts.load", flush=True) or qs.filter(title != "GraphQL Guide")
    )
)

If nested rows come back unscoped, check that scope_rows exists on every exposed type. Scoping does not depend on the optimizer: a resolver returning a list is slower than one returning a query object, but it is not less scoped. See Security.

Security

strawberry-orm has safety-focused defaults, but schema design determines what clients can read and write.

What the library does by default

• orm.input(), orm.filter(), and orm.order() exclude sensitive-looking fields (password_hash, api_key, role, is_admin, etc.)
• String regex filters are disabled by default
• Filter depth, branch count, and inList size are capped
• orm.ref() provides explicit unlink and delete operations — both opt-in via unlink=True and delete=True
• When you use orm.schema() (optimizer enabled by default), nested relation loads honor each type's scope_rows — but only for types where you define it (the ORM warns at type registration when scope_rows is missing)
• Filtering through a relation (filter: { object: { author: … } }) is restricted to the rows the related type's scope_rows allows, so a filter cannot confirm values on rows the caller cannot read
• Ordering through a relation into a scoped type is rejected when orm.schema() builds, because the resulting sequence would itself rank hidden rows — see Ordering into a scoped type
• Connection aggregates and groups are computed with the type's scope_rows applied, so counts and sums cover only readable rows

Your responsibility

Ordering into a scoped type

Filtering through a relation can be made safe by restricting the join — hidden rows simply never match. Ordering cannot: every row still has to stand somewhere in the sequence, and its position leaks the hidden sort key. If visible authors bracket a hidden one alphabetically, the caller has learned something about a row they cannot read.

So if an order input can sort through a relation whose target type defines scope_rows, orm.schema() refuses to build:

Cannot order by Post.author: User is scoped by scope_rows, so ordering would
rank rows the caller cannot read. Order by a column on Post, or pass
allow_scoped_ordering=['author'] when building the order type for Post if every
readable Post is guaranteed to have a readable User.

Three ways forward:

# 1. Sort by a column on the row itself (also faster — no join)
@orm.order_type(Post)
class PostOrder:
    title: auto
    author_name: auto        # denormalized onto Post

# 2. Opt in, per relation, when the scope is a partition your rows can't cross
#    (e.g. tenancy: every readable Post already has a readable author)
@orm.order_type(Post, allow_scoped_ordering=["author"])
class PostOrder:
    title: auto
    author: auto

# 3. Take ownership with a custom order field — the library does not second-guess
#    hand-written callbacks, so the scoping decision is yours
@orm.order_type(Post)
class PostOrder:
    title: auto

    @order_field
    def by_author(self, query, value, info): ...

allow_scoped_ordering only lifts the ordering restriction for the relations you name, on that one order input. scope_rows keeps scoping reads and filter traversal exactly as before, and another order input over the same model is unaffected. Naming a relation the order input cannot sort through is an error, so typos fail loudly.

If you build with strawberry.Schema directly instead of orm.schema(), the build-time check does not run; the offending query is rejected at execution instead.

Common mistakes

Each one links to the mechanics.

# Django; translate the query expressions with "Reading the examples"
return list(self.posts.all())            # ✗ materialized: no scope_rows, no optimizer
return self.posts.all()                  # ✓ scoped, and batched into one statement

schema = strawberry.Schema(query=Query)  # ✗ nested hooks never run
schema = orm.schema(query=Query)         # ✓ optimizer and scoping active

return list(User.objects.all())          # ✗ optimizer skipped for everything below
return orm.get_default_queryset(User)    # ✓ still a query object

return queryset.filter(tenant_id=1)                             # ✗ same tenant always
return queryset.filter(tenant_id=info.context["tenant_id"])     # ✓ per-request scope

Better than a filtering resolver is no resolver at all, so the relation stays a single prefetch:

posts: list[PostType] = orm.field.scoped(lambda qs, info: qs.filter(is_published=True))

And keep secrets off output types explicitly:

@orm.type(User, exclude=["password_hash", "api_key"])
class UserType:
    id: auto
    name: auto

Production baseline

orm = StrawberryORM.for_sqlalchemy(
    dialect="postgresql",
    session_getter=lambda info: info.context["session"],
    default_query_limit=100,
    max_filter_depth=8,
    max_filter_branches=25,
    max_in_list_size=200,
)

schema = orm.schema(query=Query)  # optimizer on by default

Defining types

Relation fields load the related model; scoping is per type — see How loading works.

@orm.type(Model)

from strawberry_orm import auto

@orm.type(User)
class UserType:
    id: auto
    name: auto
    email: auto

auto is an alias for strawberry.auto. The backend inspects the model and resolves the Python type for each field.

Keyword arguments: include, exclude, name, filters, order.

@orm.type(User, exclude=["password_hash", "api_key"], name="PublicUser")
class PublicUserType:
    id: auto
    name: auto
    email: auto

Relations

Reference other generated types directly. The backend auto-generates resolvers for relationship fields:

@orm.type(Post)
class PostType:
    id: auto
    title: auto
    tags: list[TagType]

If the nested type carries filters and/or order, list relations expose those arguments automatically.

orm.input(Model) and orm.partial(Model)

Generate input types from model metadata:

CreateUserInput = orm.input(User, include=["name", "email"])
UpdateUserInput = orm.partial(User, include=["name", "email"])

input() and partial() share the same signature: include, exclude, exclude_pk (default True), name. Fields are optional (defaulting to strawberry.UNSET), skip relations, exclude primary keys by default, and exclude sensitive-looking fields unless explicitly included.

Declaring fields

A field is either declared — the library resolves it — or written by you. Which one you pick decides when your code runs and what it can see.

The four kinds of field

orm.field has four named forms. The name tells you when your code runs, and that in turn decides what it receives:

scoped gets info but never self. That absence is the point: with no parent row to look at, the optimizer folds it into a single prefetch covering every parent at once. It also makes a field-level scope symmetric with scope_rows(cls, qs, info).

# Django
@orm.type(User)
class UserType:
    id: auto
    name: auto

    # the library resolves it; you add metadata
    email: auto = orm.field.auto(permission_classes=[IsAdmin])

    # you narrow which rows load — named for the relation it narrows
    @orm.field.scoped
    def posts(queryset, info) -> list[PostType]:
        return queryset.filter(is_published=True)

    # you write the resolver; it returns rows
    @orm.field.custom
    def recent(self, info: strawberry.Info) -> list[PostType]:
        return Post.objects.filter(author_id=self.id)

    # you write the resolver; it returns a value
    @orm.field.computed(using=["comments"])
    def comment_count(self, info: strawberry.Info) -> int:
        return len(self.comments)

A scoped field takes the name of the relation it narrows — posts above scopes User.posts. There is one scope per relation; if you want a second, differently-filtered view, that is a custom resolver like recent. For the same reason, do not point using= at a relation you have also scoped — the two ask for the same prefetch with different querysets, which Django rejects outright.

Decorator or inline — the same call

@decorator is sugar for name = decorator(fn), so every form has an inline spelling. Only the source of the field's type changes:

@orm.field.scoped                                  # type ← return annotation
def posts(qs, info) -> list[PostType]:
    return qs.filter(is_published=True)

posts: list[PostType] = orm.field.scoped(          # type ← variable annotation
    lambda qs, info: qs.filter(is_published=True)
)

Inline is better for one-liners, and it is the only way to share a scope:

def published_only(qs, info):
    return qs.filter(is_published=True)

class UserType:
    posts: list[PostType] = orm.field.scoped(published_only)

class TagType:
    posts: list[PostType] = orm.field.scoped(published_only)

Choosing between scoped and custom

Both end up applying the child type's scope_rows, but they are not equivalent. Same query, same data, with PostType.scope_rows hiding drafts:

custom costs an extra query because the optimizer had already built the prefetch from the selection set; your resolver ignores it and runs its own. Batching keeps that at one statement rather than one per parent, but cannot remove it.

The last row is the one to remember: scoped has no way to lose the scope, because it receives a query and returns a query. custom is one list(...) away from silently returning rows the type exists to hide. Reach for custom only when the query genuinely depends on the parent row or on info.

What the library checks

Because the name declares the shape, mistakes are caught when the class is defined rather than deep inside a prefetch:

@orm.field.scoped
def posts(self, info) -> list[PostType]: ...
# TypeError: posts(self, ...) is not a scope: a scope receives (qs, info) and
# never sees the parent row. Use orm.field.custom for a resolver that needs self.

It also rejects a custom resolver without self, a scoped field with no type on either the annotation or the function, and scope= on a field that is not a relation on the model.

Metadata arguments

auto carries everything the optimizer needs to know about a field it resolves for you:

using= answers what to load; scope= answers which rows. You do not need using=["posts"] when the client already selects posts { … } — the optimizer follows the selection set. Reach for it when a resolver reads a relation the query did not ask for.

Names are validated when the type is defined, so a typo fails immediately:

ValueError: PostType.byline: Post has no relation 'athor'. Did you mean 'author'?

List fields

orm.field.auto() builds a list resolver from the model attached to the return type:

@strawberry.type
class Query:
    users: list[UserType] = orm.field.auto()

For a root field with custom criteria, return an unexecuted select/queryset from @orm.field.custom — still optimized by orm.schema(). See Root custom query.

Define row scope on the type with scope_rows — see scope_rows and the Quick Start.

Filters and ordering

Filters narrow rows within a type's query; they do not replace scope_rows — see Security and How loading works.

Filters

Generate a filter input and attach it to a type:

UserFilter = orm.filter(User)

@orm.type(User, filters=UserFilter)
class UserType:
    id: auto
    name: auto
    email: auto

List fields returning UserType then accept a filter argument:

{
  users(filter: { field: { name: { exact: "Alice" } } }) {
    id
    name
  }
}

Filter shape

Filters are recursive @oneOf trees supporting field, all, any, not, and oneOf:

# OR
{ users(filter: { any: [
    { field: { name: { exact: "Alice" } } }
    { field: { name: { exact: "Bob" } } }
] }) { name } }

# AND
{ posts(filter: { all: [
    { object: { author: { field: { id: { exact: 1 } } } } }
    { field: { isPublished: { exact: true } } }
] }) { title } }

# NOT
{ users(filter: {
    not: { field: { email: { contains: "example.com" } } }
}) { name } }

Object traversal

When filters are registered for related models, the generated filter gains an object key for filtering by conditions on related objects:

UserFilter = orm.filter(User)
PostFilter = orm.filter(Post)   # Post has an "author" relation to User

{
  posts(filter: {
    object: { author: { field: { name: { exact: "Alice" } } } }
  }) { title }
}

Object traversal composes with boolean operators and supports multi-level nesting when intermediate models also have registered filters:

# Comments on posts written by Alice
{
  comments(filter: {
    object: { post: {
      object: { author: { field: { name: { exact: "Alice" } } } }
    } }
  }) { body }
}

The object type is @oneOf. Relations only appear in object if their target model already has a registered filter at the time orm.filter() is called -- register leaf models first.

Filter projection

Pass project={...} to control which relations appear in object and how deep traversal can go:

UserFilter    = orm.filter(User)
TagFilter     = orm.filter(Tag)
CommentFilter = orm.filter(Comment)

PostFilter = orm.filter(Post, project={"author": {}})  # only author, not tags/comments

Sub-project dicts control nested traversal. {} means "include as a leaf" (no further object traversal). A non-empty dict lists reachable relations:

CommentFilter = orm.filter(Comment, project={
    "post": {"author": {}},   # Comment -> post -> author (but not post -> tags)
})

Projected filters are cached internally and do not overwrite the global filter registry.

Ordering

UserOrder = orm.order(User)

Each order entry is a @oneOf input with a field key (for scalar columns) or an object key (for related models). Position in the list determines tie-break priority:

{
  users(order: [{ field: { name: ASC } }, { field: { email: DESC } }]) {
    name
    email
  }
}

Supported values: ASC, ASC_NULLS_FIRST, ASC_NULLS_LAST, DESC, DESC_NULLS_FIRST, DESC_NULLS_LAST.

Order by related object

When order types are registered for related models, the generated order gains an object key that lets you sort by fields on related objects — mirroring the filter object traversal structure:

{
  posts(order: [
    { object: { author: { field: { name: ASC } } } }
    { field: { title: DESC } }
  ]) {
    title
  }
}

Registration order matters: define related orders before the parent (e.g. orm.order(User) before orm.order(Post)).

Custom filters and ordering

orm.filter() and orm.order() auto-generate types from model introspection. When you need filter logic that goes beyond column lookups — full-text search across multiple fields, subquery-based conditions, or ordering by computed values — use orm.filter_type() and orm.order_type() with the @filter_field and @order_field decorators.

Custom filter types

orm.filter_type(Model) is a class decorator. Annotate fields with auto for standard lookups (identical to what orm.filter() generates). Add methods decorated with @filter_field for custom logic:

# SQLAlchemy
from strawberry_orm import StrawberryORM, filter_field, auto

orm = StrawberryORM.for_sqlalchemy(dialect="postgresql", session_getter=...)

@orm.filter_type(User)
class UserFilter:
    name: auto          # standard StringLookup
    email: auto         # standard StringLookup

    @filter_field
    def search(self, value: str, query):
        """Full-text search across name and email."""
        from sqlalchemy import or_
        return query.where(
            or_(User.name.ilike(f"%{value}%"), User.email.ilike(f"%{value}%"))
        )

    @filter_field
    def has_posts(self, value: bool, query):
        """Filter users who have (or lack) any posts."""
        from sqlalchemy import func, select
        subq = (
            select(func.count(Post.id))
            .where(Post.author_id == User.id)
            .correlate(User)
            .scalar_subquery()
        )
        if value:
            return query.where(subq > 0)
        return query.where(subq == 0)

Each @filter_field method must:

• Have a value parameter with a type annotation — this becomes the GraphQL input type for the field.
• Have a query parameter — receives the backend's native query object (Django QuerySet, SQLAlchemy Select, or Tortoise QuerySet).
• Return the modified query.
• Optionally accept an info parameter to receive the Strawberry Info context.

The generated GraphQL input places custom fields as top-level keys alongside field, object, all, any, not, and oneOf:

input UserFilter @oneOf {
  field: UserField           # auto-generated scalar lookups
  object: UserFilterObject   # auto-generated relation lookups (if any)
  search: String             # custom
  hasPosts: Boolean          # custom
  all: [UserFilter!]
  any: [UserFilter!]
  not: UserFilter
  oneOf: [UserFilter!]
}

Since filters are @oneOf, combine custom filters with standard lookups using all or any:

{
  users(filter: { all: [
    { search: "john" },
    { field: { email: { contains: "example.com" } } }
  ] }) {
    name
    email
  }
}

Custom order types

orm.order_type(Model) works the same way. auto fields get the standard Ordering enum. Methods decorated with @order_field receive a value of type Ordering (ASC, DESC, etc.) and return the modified query:

from strawberry_orm import order_field
from strawberry_orm.types import Ordering

@orm.order_type(User)
class UserOrder:
    name: auto          # standard Ordering (ASC/DESC/...)

    @order_field
    def post_count(self, value: Ordering, query):
        """Order users by how many posts they have."""
        from sqlalchemy import func
        query = query.outerjoin(Post, Post.author_id == User.id).group_by(User.id)
        col = func.count(Post.id)
        if "DESC" in value.value:
            return query.order_by(col.desc())
        return query.order_by(col.asc())

The generated GraphQL input:

input UserOrder @oneOf {
  field: UserOrderField      # auto-generated
  object: UserOrderObject    # auto-generated (if relations exist)
  postCount: Ordering        # custom
}

Custom and standard orders compose naturally in the order list:

{
  users(order: [
    { postCount: DESC },
    { field: { name: ASC } }
  ]) {
    name
  }
}

Using custom types

Custom filter and order types are used exactly like auto-generated ones:

@orm.type(User, filters=UserFilter, order=UserOrder)
class UserType:
    id: auto
    name: auto
    email: auto

@strawberry.type
class Query:
    @orm.field.custom
    def users(self, info: strawberry.Info) -> list[UserType]:
        return orm.get_default_queryset(User)

They also work with Relay connections and orm.connection().

Backend-specific examples

The query manipulation inside @filter_field and @order_field methods is backend-specific since it operates on native query objects. Here are equivalent examples for each backend:

from django.db.models import Q, Count, F

@orm.filter_type(User)
class UserFilter:
    name: auto

    @filter_field
    def search(self, value: str, query):
        return query.filter(Q(name__icontains=value) | Q(email__icontains=value))

@orm.order_type(User)
class UserOrder:
    name: auto

    @order_field
    def post_count(self, value: Ordering, query):
        query = query.annotate(_post_count=Count("posts"))
        dir_value = value.value
        if dir_value.startswith("DESC"):
            return query.order_by(F("_post_count").desc())
        return query.order_by(F("_post_count").asc())

from tortoise.queryset import Q
from tortoise.functions import Count

@orm.filter_type(User)
class UserFilter:
    name: auto

    @filter_field
    def search(self, value: str, query):
        return query.filter(Q(name__icontains=value) | Q(email__icontains=value))

@orm.order_type(User)
class UserOrder:
    name: auto

    @order_field
    def post_count(self, value: Ordering, query):
        query = query.annotate(_post_count=Count("posts"))
        if value.value.startswith("DESC"):
            return query.order_by("-_post_count")
        return query.order_by("_post_count")

Custom group-by types

orm.group_type(Model) works like orm.filter_type() and orm.order_type(). auto fields get the standard group-by type (Boolean or DateGroupByOption). Methods decorated with @group_field add custom grouping logic:

from strawberry_orm import group_field

@orm.group_type(Order)
class OrderGroupBy:
    status: auto         # standard Boolean group-by
    created_at: auto     # DateGroupByOption with interval

    @group_field
    def by_customer_tier(self, value: bool, query):
        """Group by a computed customer tier."""
        from sqlalchemy import case
        return case(
            (Order.amount >= 100, "premium"),
            else_="standard",
        ).label("customer_tier")

Combining with orm.filter() / orm.order()

orm.filter(), orm.order(), and orm.group() remain available for fully auto-generated types. Use orm.filter_type(), orm.order_type(), and orm.group_type() only when you need custom logic. The types produced by both APIs are interchangeable in all contexts — orm.type(Model, filters=..., order=..., group=...), orm.field.auto(filters=..., order=...), and orm.connection().

Grouping and aggregation

Group-by and aggregation are available on Relay connection fields. Register a group-by type for a model and pass it to orm.type():

# SQLAlchemy
from strawberry import relay
from strawberry_orm import StrawberryORM, auto
from strawberry_orm.relay import ORMListConnection

orm = StrawberryORM.for_sqlalchemy(dialect="postgresql", session_getter=...)

OrderFilter  = orm.filter(Order)
OrderOrder   = orm.order(Order)
OrderGroupBy = orm.group(Order)

@orm.type(Order, filters=OrderFilter, order=OrderOrder, group=OrderGroupBy)
class OrderNode(relay.Node):
    id: relay.NodeID[int]
    status: auto
    amount: auto
    quantity: auto
    created_at: auto

@strawberry.type
class Query:
    orders: ORMListConnection[OrderNode] = orm.connection()

schema = orm.schema(query=Query)

When group is set, the generated connection type automatically includes aggregates, groups, and an extended pageInfo with aggregate data.

Querying aggregates

{
  orders(first: 100) {
    pageInfo {
      hasNextPage
      aggregates {
        count
        sum { amount }
        avg { amount }
      }
    }
    edges {
      node { status amount }
    }
  }
}

Aggregates are computed over the full filtered result set (before pagination). Page-level aggregates in pageInfo cover only the current page.

Auto-generated aggregate types include count, sum, avg, min, and max — scoped to the numeric and comparable fields on the model.

Querying groups

{
  orders(
    groupBy: [{ field: { status: true } }]
    first: 100
  ) {
    groups {
      key { status }
      aggregates {
        count
        sum { amount }
        avg { amount }
      }
      edgeIndices
      items(first: 5) {
        edges {
          node { status amount quantity }
        }
      }
    }
    edges {
      node { status amount }
    }
  }
}

Each group includes:

• key — the group-by column values
• aggregates — per-group aggregate values (count, sum, avg, min, max)
• edgeIndices — indices into the parent connection's edges array
• items — a nested cursor-paginated connection of items in that group

Date/datetime fields support interval-based grouping:

{
  orders(
    groupBy: [{ field: { createdAt: { interval: MONTH } } }]
  ) {
    groups {
      key { createdAt }
      aggregates { count }
    }
  }
}

Supported intervals: DAY, WEEK, MONTH, QUARTER, YEAR.

Custom aggregates

Use @aggregate_field to define computed aggregate expressions:

from strawberry_orm import aggregate_field

@orm.aggregate_type(Order)
class OrderAggregation:
    amount: auto
    quantity: auto

    @aggregate_field
    def total_revenue(self, columns) -> float:
        from sqlalchemy import func
        return func.sum(columns.amount * columns.quantity)

Data / errors payloads

A GraphQL error aborts the field and hands the client an errors array detached from the shape it asked for. If you would rather answer with a typed payload — data when the work succeeded, errors when it did not — orm.payload builds it.

Configure it once with the error type and how to convert an exception:

# Django
from strawberry_orm import PayloadPolicy, StrawberryORM

orm = StrawberryORM.for_django(
    payload=PayloadPolicy(
        errors=ErrorsObject,
        on_error=ErrorsObject.from_exception,
    ),
)

Then the resolver says what it returns, and the payload type is generated from it:

# Django
@strawberry.type
class Query:
    @orm.payload.query
    def recent_users(self) -> list[UserType]:
        return User.objects.order_by("-created_at")

@strawberry.type
class Mutation:
    @orm.payload.mutation
    def rename_user(self, identifier: str, name: str) -> UserType:
        ...

recentUsers returns a RecentUsersPayload with data and errors. The name comes from the resolver; pass name= to choose your own. orm.payload.mutation also takes input_mutation=True to collapse the arguments into a generated input argument.

Three things happen for you. Exceptions become errors and leave data null. Sync ORM work is moved off the event loop under async, decided per call so the same resolver is correct in tests and under an ASGI server. And rows returned through data are eager-loaded, because data is a resolved field like any other — the payload machinery itself does no optimization.

How an exception becomes errors

on_error is the whole translation step. It receives the exception and returns a value of your errors type:

# Django
@strawberry.type
class ErrorsObject:
    message: str
    field: str | None = None

    @classmethod
    def from_exception(cls, exc: BaseException) -> "ErrorsObject":
        if isinstance(exc, ValidationError):
            return cls(message=str(exc), field=exc.field)
        if isinstance(exc, AuthorizationError):
            return cls(message="Not allowed")
        raise exc          # anything unrecognised stays a GraphQL error

Given raise ValidationError("Title is required", field="title"), a client asking for

{ createPost(title: "") { data { id title } errors { message field } } }

gets its answer in the shape it asked for, with data null:

{ "data": { "createPost": { "data": null,
                            "errors": { "message": "Title is required",
                                        "field": "title" } } } }

Exactly one of data and errors is ever set.

That final raise matters: a converter that only recognises some of your errors needs a way to let the rest through. Anything on_error re-raises fails the field normally, so createPost comes back null with a top-level GraphQL error — a bug stays a bug rather than being flattened into a message.

handles is the other way to draw that line. It decides what is caught in the first place, so an unlisted exception never reaches the converter and keeps its own traceback instead of being chained through one:

# Django
PayloadPolicy(
    errors=ErrorsObject,
    on_error=ErrorsObject.from_exception,
    handles=(ValidationError, AuthorizationError),
)

The default is (Exception,), which catches broadly and leaves the decision to on_error. Which you prefer is a question of where the list of known errors should live: next to the policy, or inside the converter.

Connection payloads

orm.payload.connection puts a Relay connection under data, with the generated filter / order / groupBy arguments and pagination hanging off it:

# Django
@strawberry.type
class Query:
    @orm.payload.connection(ORMListConnection[UserNode])
    def users(self):
        return User.objects.order_by("id")

{
  users {
    errors { message }
    data(first: 10, filter: { field: { name: { contains: "a" } } }) {
      totalCount
      edges { node { name } }
    }
  }
}

On failure data is an empty connection rather than null, so a client renders the same shape either way.

Mutations

Write plain @strawberry.mutation resolvers and use strawberry-orm for generated input types. Authorization and row-level checks are your responsibility — see Security.

CreatePostInput = orm.input(Post, include=["title", "body", "author_id"])

@strawberry.type
class Mutation:
    @strawberry.mutation
    def create_post(self, info: strawberry.types.Info, input: CreatePostInput) -> PostType:
        post = Post(title=input.title, body=input.body, author_id=input.author_id)
        ...
        return post

Related list inputs (orm.ref)

orm.ref(...) generates a @oneOf input for managing related lists:

CreateTagInput = orm.input(Tag, include=["name"])

@strawberry.input
class UpdateTagInput:
    id: strawberry.ID
    name: str | None = strawberry.UNSET

TagRef = orm.ref(Tag, create=CreateTagInput, update=UpdateTagInput, unlink=True, delete=True)

Each ref is a @oneOf with these keys:

• update — link an existing object by ID, or update its fields. Always present (an ID-only input is auto-generated if no custom update type is provided).
• create — create a new related object (present when create= is provided).
• unlink — remove the object from the relation without deleting it (present when unlink=True).
• delete — hard-delete the related row (present when delete=True).

All list mutations use patch semantics: only the items you mention are affected; existing related objects not listed are left untouched.

Apply ref operations with orm.apply_ref_list(parent, "relation_name", refs, info). An optional authorize callback (action, model, obj_id, info) -> bool can be provided for per-operation authorization.

mutation {
  setPostTags(postId: 1, tags: [
    { update: { id: "2" } }
    { update: { id: "1", name: "python3" } }
    { create: { name: "new-tag" } }
    { unlink: { id: "3" } }
    { delete: { id: "4" } }
  ]) {
    tags { id name }
  }
}

Note: Whether the order of items in the list affects the final ordering of the relation is an implementation detail that each backend must maintain.

Node mutation inputs

orm.mutations.create_node_input() and orm.mutations.update_node_input() generate a catch-all @oneOf input carrying one branch per registered Relay Node type, with recursive nested ref lists. The library deliberately does not ship a resolver that executes them — you write the mutation, so the write path (and its scoping) stays yours:

@orm.type(Post)
class PostNode(relay.Node):
    id: relay.NodeID[int]
    title: auto
    body: auto

CreateNodeInput = orm.mutations.create_node_input(name="CreateNodeInput")

@strawberry.type
class Mutation:
    @strawberry.mutation
    def create_node(self, info: strawberry.Info, input: CreateNodeInput) -> bool:
        # Exactly one root branch is set. Authorize it, then write it yourself.
        ...

scope_rows is a read control and does not scope writes — see Security. Because the resolver is yours, apply the same restriction there, or use a repo (AbstractRepo) whose can_* checks, scope_query, and on_* lifecycle hooks run for every write the library performs through orm.apply_ref_list().

Narrowing the input with project=

project= is a path-shaped dict that controls which relations appear in the generated input, and how each behaves:

project = {
    "post": {
        "author": {"_meta": {"onReplace": ["DISCONNECT", "DELETE"]}},
        "comments": {"author": {}},
        "tags": {},
    },
}

CreateNodeInput = orm.mutations.create_node_input(
    project=project, name="CreateNodeInput"
)

Rules:

• Root keys are model names (post, comment, ...).
• Nested keys are relation names on that model.
• _meta configures behavior for that relation subtree (create, update, upsert, onReplace).
• Relations you do not declare are absent from the input, so the schema rejects them.

Relay integration

strawberry-orm works with Strawberry's Relay support for cursor-based pagination and global node identification.

Relay node types

Extend relay.Node instead of a plain Strawberry type. Use relay.NodeID for the id field:

# SQLAlchemy
from strawberry import relay
from strawberry_orm import StrawberryORM, auto

orm = StrawberryORM.for_sqlalchemy(dialect="postgresql", session_getter=...)

UserFilter = orm.filter(User)
UserOrder  = orm.order(User)

@orm.type(User, filters=UserFilter, order=UserOrder)
class UserNode(relay.Node):
    id: relay.NodeID[int]
    name: auto
    email: auto

Connection fields

Use orm.connection() with ORMListConnection to create paginated connection fields. Filters and ordering from the node type are automatically wired in:

from collections.abc import Iterable
from strawberry_orm.relay import ORMListConnection

@strawberry.type
class Query:
    @orm.connection(ORMListConnection[UserNode])
    def users_connection(self) -> Iterable[UserNode]:
        return orm.get_default_queryset(User)

This gives you:

{
  usersConnection(
    filter: { field: { email: { contains: "example.com" } } }
    order: [{ field: { name: DESC } }]
    first: 10
    after: "YXJyYXljb25uZWN0aW9uOjk="
  ) {
    edges {
      cursor
      node { name email }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

Filters and ordering are applied before pagination, so the connection always slices from a correctly filtered and sorted result set.

orm.connection() accepts the same keyword arguments as relay.connection() — name, description, deprecation_reason, extensions, and max_results.

Supplying the queryset yourself

The decorator above is one way to give orm.connection() a resolver. You can also pass one by keyword, which is what you want when the connection is a field on a type you are assembling rather than a method you are writing:

# Django
def recent_users(info: strawberry.types.Info) -> Iterable[UserNode]:
    return User.objects.order_by("-created_at")

@strawberry.type
class Query:
    users = orm.connection(ORMListConnection[UserNode], resolver=recent_users)

Either way the library still builds everything around your rows: the generated filter, order, and groupBy arguments, the grouped connection type when the node declares a group-by, totalCount, and optimizer integration. Your resolver does not need to accept filter or order — they are applied to the query object you return. Arguments of your own are passed through and appear on the field.

Node mutations

orm.mutations.create_node_input() and orm.mutations.update_node_input() generate catch-all Relay Node mutation inputs with recursive nested refs; you supply the resolver. See Node Mutation Inputs for full documentation.

Async usage

strawberry-orm supports both sync and async execution (schema.execute / schema.execute_sync, Django AsyncGraphQLView, etc.).

orm = StrawberryORM.for_django()  # django_async_safe=True, lazy_resolution="warn"

schema = orm.schema(query=Query)

Custom sync resolvers declared with @orm.field.custom are async-safe automatically. Automatic filter and order arguments are wired on generated list and connection fields; pass them explicitly via @orm.field.custom(filters=..., order=...) if a hand-written resolver needs them.

Sync @orm.connection resolvers on @orm.type work under async execution, including when the method name matches a Django reverse relation (e.g. def comments(self, info: strawberry.Info) returning a queryset).

Optional runtime FK checks: extensions=[orm.lazy_resolution_extension()].

# Tortoise example
@strawberry.type
class Query:
    @strawberry.field
    async def users(self) -> list[UserType]:
        return await User.all()

apply_ref_list is sync for Django/sync-SQLAlchemy and awaitable for Tortoise/async-SQLAlchemy.

Migrating from a custom Django async integration layer

If you previously monkey-patched StrawberryORM for AsyncGraphQLView, you can remove that module and rely on:

Backend options

Passed to StrawberryORM.for_django() / for_sqlalchemy() / for_tortoise().

Shared options:

Django-only:

SQLAlchemy-only:

Public exports

Every name below is documented with its signature in the API reference.

StrawberryORM, auto, make_ref_type, PayloadPolicy, Ordering, DateGroupByInterval, DateGroupByOption, FieldDefinition, FieldHints, OptimizerExtension, OptimizerStore, UNSET, filter_field, order_field, group_field, aggregate_field, and the built-in lookup input classes from strawberry_orm.filters.

Appendix: full example

A blog API with users, posts, tags, and comments — covering types, relations, queryset scoping, optimizer hints, filters, ordering, object traversal, grouping, aggregation, mutations, ref lists, recursive node mutations, and the query optimizer:

# SQLAlchemy
import strawberry
from strawberry_orm import StrawberryORM, auto

orm = StrawberryORM.for_sqlalchemy(
    dialect="postgresql",
    session_getter=lambda info: info.context["session"],
)

# -- Filters, ordering, and grouping (register leaf models first) ------------

UserFilter = orm.filter(User)
UserOrder  = orm.order(User)
TagFilter  = orm.filter(Tag)
TagOrder   = orm.order(Tag)

CommentFilter = orm.filter(Comment)
PostFilter    = orm.filter(Post)      # picks up author/tags/comments relations
PostOrder     = orm.order(Post)
PostGroupBy   = orm.group(Post)       # group-by support for aggregation

# -- Types -------------------------------------------------------------------

@orm.type(User, filters=UserFilter, order=UserOrder)
class UserType:
    id: auto
    name: auto
    email: auto
    posts: list["PostType"]

@orm.type(Tag, filters=TagFilter, order=TagOrder)
class TagType:
    id: auto
    name: auto

@orm.type(Comment, filters=CommentFilter)
class CommentType:
    id: auto
    body: auto

@orm.type(Post, filters=PostFilter, order=PostOrder, group=PostGroupBy)
class PostType:
    id: auto
    title: auto
    body: auto
    is_published: auto
    tags: list[TagType] = orm.field.scoped(
        lambda select, info: select.order_by(Tag.name)
    )
    comments: list[CommentType]

    @orm.field.custom
    def author(self, info: strawberry.Info) -> UserType:
        return self.author

    @classmethod
    def scope_rows(cls, select, info):
        return select.where(Post.is_published.is_(True))

# -- Mutations ---------------------------------------------------------------

CreatePostInput = orm.input(Post, include=["title", "body", "author_id"])
CreateTagInput  = orm.input(Tag, include=["name"])
TagRef = orm.ref(Tag, create=CreateTagInput, unlink=True, delete=True)

CreateNodeInput = orm.mutations.create_node_input(name="CreateNodeInput")


@strawberry.type
class Mutation:
    @strawberry.mutation
    def create_post(self, input: CreatePostInput) -> PostType:
        post = Post(title=input.title, body=input.body, author_id=input.author_id)
        ...
        return post

    @strawberry.mutation
    def set_post_tags(self, post_id: int, tags: list[TagRef]) -> PostType:
        post = ...
        orm.apply_ref_list(post, "tags", tags)
        return post

    @strawberry.mutation
    def create_node(self, info: strawberry.Info, input: CreateNodeInput) -> bool:
        ...  # authorize, then write it yourself

@strawberry.type
class Query:
    users: list[UserType] = orm.field.auto()
    posts: list[PostType] = orm.field.auto()

schema = orm.schema(query=Query, mutation=Mutation)

# Filter posts by a related author's name, ordered by title
{
  posts(
    filter: {
      all: [
        { field: { isPublished: { exact: true } } }
        { object: { author: { field: { name: { exact: "Alice" } } } } }
      ]
    }
    order: [{ field: { title: ASC } }]
  ) {
    title
    author { name }
    tags { name }
  }
}

mutation {
  setPostTags(postId: 1, tags: [
    { update: { id: "2" } }
    { create: { name: "new-tag" } }
    { unlink: { id: "3" } }
    { delete: { id: "4" } }
  ]) {
    tags { id name }
  }
}

mutation {
  createNode(input: {
    post: {
      title: "Hello"
      body: "World"
      author: { create: { name: "Alice", email: "alice@example.com" } }
      tags: [{ create: { name: "python" } }]
    }
  })
}

Contributing

Bug reports and pull requests are welcome — see CONTRIBUTING.md for development setup, the test layout, and the backend parity rules.

License

MIT