Types¶

django-graphex provides enhanced type classes built directly on graphql-core.

DjangoObjectType¶

The base node type: it maps a Django model to a GraphQL object type. Declare a model and the library converts its fields (including choices → enums and relations → nested list types). It is the building block every other type and field resolves to.

from django.contrib.auth import get_user_model

from django_graphex.types import DjangoObjectType

User = get_user_model()

class UserType(DjangoObjectType):
    class Meta:
        description = "Type definition for a single user"
        model = User
        # The projection. It is a security boundary, not cosmetics — see
        # [the rule](#projection-security-boundary) — and it is the ONE
        # projection for `User` on this page: every later sample that lists,
        # filters or orders users is bound by exactly these columns.
        only_fields = (
            "id", "username", "first_name", "last_name",
        )
        # Enables `filter:` when this type is used as a (nested) list.
        filter_fields = {"username": ("exact", "icontains")}

Use it directly with DjangoObjectField to fetch a single object by id, as the node of a DjangoListObjectType, or as the output of a mutation. Relations on the model are exposed as nested lists with the uniform results / totalCount shape — see Nested lists.

from django.urls import path

from django_graphex.views import AuthenticatedGraphQLView

urlpatterns = [
    path("graphql/", AuthenticatedGraphQLView.as_view(schema=schema)),
]

DJANGO_GRAPHEX = {"CACHE_ACTIVE": False}

user = get_user_model().objects.create_user(
    username=username,
    password=password,
)

Custom per-field filter arguments — @filter_field¶

Added in v1.3.0. Use the @filter_field decorator to expose a custom GraphQL filter argument directly on the type, co-located with its logic:

from graphql import GraphQLString
from django.db.models import Q
from django_graphex.filtering import filter_field
from django_graphex.types import DjangoObjectType

class PostType(DjangoObjectType):
    class Meta:
        model = Post
        filter_fields = {"title": ("exact", "icontains")}

    @filter_field(GraphQLString, description="Full-text search")
    def search(cls, queryset, info, value):
        return queryset.filter(
            Q(title__icontains=value) | Q(body__icontains=value)
        )

See Filtering — @filter_field for the full reference including type override, composition order, and reserved argument names.

Custom queryset (per-request filtering)¶

Override get_queryset(cls, queryset, info) to scope what a type exposes on a per-request basis — for example, to restrict rows to the current user's data:

class ArticleType(DjangoObjectType):
    class Meta:
        model = Article
        filter_fields = {"title": ("icontains",)}

    @classmethod
    def get_queryset(cls, queryset, info):
        # Only expose articles owned by the requesting user.
        return queryset.filter(owner=info.context.user)

The hook is called by all four top-level field types before the query optimizer runs, so select_related / prefetch_related are applied on top of the already-narrowed queryset — the same interplay described for DjangoModelType.Meta.queryset in the optimizer docs:

Both results and totalCount reflect the hook — the hook is applied before the COUNT query is issued.

The hook applies wherever the field is mounted, root or nested: a DjangoFilterListField you mount by hand on a parent type (e.g. created_posts = DjangoFilterListField(PostType) on AuthorType) scopes its rows even when it is reached through the parent's relation, not only at the top level.

Meta options are validated¶

Since v1.2.2 (#65), unknown or mistyped Meta options raise ImproperlyConfigured at server startup instead of being silently ignored. For example, a typo like filter_Filed (capital F) is caught immediately.

The full set of recognised options for DjangoObjectType.Meta is:

Graphene's own base options ride along on top of that list and are accepted too: possible_types, default_resolver and container. Every other public key is rejected at startup. Review your DjangoObjectType and DjangoListObjectType subclasses for typos before upgrading from pre-1.2.2.

The projection is a security boundary¶

This is the canonical statement of the rule. Every other page links here.

What "hidden" means — one predicate, both axes¶

Both axes ask one question of one function: does the type that will serve this request hand out the value this column holds? It is answered against the compiled type — the type in the SDL — and never by re-reading Meta, so orderable, filterable and selectable cannot drift apart. Five different causes therefore give one answer:

Two consequences worth spelling out, because both break code that used to work:

• A forward FK's _id column follows the target type's key. author_id is orderable and filterable only when PostType publishes author and the type behind author publishes the key author points at. A target that projects its own primary key away takes author_id down with it — the id was never readable through author { id } in that schema, so nothing about it was already public.
• A multi-table-inheritance parent link rides on the inherited key. The compiler drops the <parent>_ptr link as plumbing and publishes the parent's id in its place, so the child's pk follows that id.

The rule fails closed: a resolver body is user Python that no build-time check can read, so a resolve_<name> that happens to return the real column loses the column anyway. Drop the resolver, or publish the substitute under a different name. The one shortcut the compiler can read is exempt — a same-name source=, as in bio = CharField(source="bio"), provably reads that very attribute, so it keeps the column. A source= naming anything else does not.

The one exception, and the three open boundaries¶

There is exactly one exception, and it is about provenance, not about the column:

Three boundaries the rule cannot close, stated rather than hidden:

• A @filter_field method body. Its name is checked — a method spelled like a hidden column compiles the very <Model>FilterInput field a filter_fields entry naming it is refused, so the one-line rename is shut. The body is opaque user Python; keep your own ORM lookups inside your own projection. See Custom per-field filters.
• Per-type narrowing on the filter axis. There is one <Model>FilterInput per model, shared by every context, so a second, narrower type over the same model cannot get a narrower filter input — it gets a build failure instead. The boundary is measured against the union the shared input ends up serving, and against every type that will serve it, so the narrow type cannot inherit the wide one's filters in silence. See Two node types over one model share one input.
• A hand-written Subscription that names Meta.model. It builds its event type and its <Model>SubscriptionFilterInput from the model, so it does not inherit the projection of whatever DjangoObjectType the schema registered for that model: a column hidden on the node type stays selectable and equality-filterable on that subscription. The subscription honours a projection — its own Meta.only_fields / Meta.exclude_fields — so repeat it there. A subscription generated from a DjangoModelType (Meta.stream plus SubscriptionField()) is not affected: that host forwards its own projection into the subscription class it builds. See Subscriptions › Filter key validation.

Model inheritance¶

Abstract base — Django copies the parent's columns onto the child, so they appear on the child's type exactly once. Nothing special to do.

Multi-table inheritance — the parent keeps its own table and the child holds a parent link. A type over the child picks up everything it inherits: the parent's columns render alongside the child's own, and the parent's reverse relations render as their usual <Model>ListType containers.

class Place(models.Model):
    name = models.CharField(max_length=100)

class Review(models.Model):
    place = models.ForeignKey(Place, related_name="reviews", on_delete=models.CASCADE)

class Restaurant(Place):                 # multi-table inheritance
    serves_pizza = models.BooleanField(default=False)

type RestaurantType {
  id: ID!                   # inherited from Place
  name: String              # inherited from Place
  servesPizza: Boolean
  reviews: ReviewListType   # inherited from Place
}

Before this, an inherited reverse relation had no compiled counterpart and the whole schema build failed with RestaurantType fields cannot be resolved, while the inherited columns — the primary key among them — were absent from the type.

The implicit parent link (placePtr) is deliberately not exposed: the child already carries every inherited column, so the link would only offer a redundant hop back to a copy of the same row.

DjangoListObjectType¶

from django_graphex.types import DjangoListObjectType
from django_graphex.paginations import LimitOffsetGraphqlPagination
from django.contrib.auth.models import User

class UserListType(DjangoListObjectType):
    class Meta:
        description = "Type definition for user list"
        model = User
        pagination = LimitOffsetGraphqlPagination(
            default_limit=25,
            ordering="username"
        )
        filter_fields = {
            "username": ("exact", "icontains"),
            "first_name": ("exact", "icontains"),
        }

Features¶

• Built-in Pagination: Automatic pagination with configurable settings
• Filtering: Built on Django's ORM lookups + Q objects (no django-filter)
• Ordering: Custom ordering options
• Caching: Optional query result caching
• Custom Queryset: Override default queryset behavior

Configuration Options¶

A DjangoListObjectType concentrates its list behavior in Meta: the paginator (with its default/max page size and ordering), the filter_fields lookups exposed on the filter: argument, and a custom base queryset. The field restrictions are the one thing that does not belong here when a node type is already registered for the model — they live on that node type, for the reason the box under the sample gives. The example below continues the UserType declared at the top of this page:

class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        description = "User list with advanced features"

        # Pagination
        pagination = LimitOffsetGraphqlPagination(
            default_limit=20,
            max_limit=100,
            ordering=("username", "first_name")
        )

        # Filtering
        filter_fields = {
            "username": ("exact", "icontains", "istartswith"),
            "first_name": ("exact", "icontains"),
            "last_name": ("exact", "icontains"),
            # No "groups" entry. Filtering through a relation needs the TARGET
            # to be published too, and `Group` has no registered
            # `DjangoObjectType` here, so the compiler drops the relation and
            # the entry would refuse the build. Register a `GroupType` first if
            # you want it.
        }

        # Custom queryset
        queryset = User.objects.all()

        # Field restrictions: NOT here. `UserType` is already registered for
        # `User` (top of this page), so this container reuses that node type and
        # a projection of its own would be dropped — declaring one raises, see
        # the box below. The restriction lives on `UserType`, and every column
        # the two options above name is published there. It has to be: a
        # projection is a security boundary, so filtering or ordering by a
        # column the node type hides fails the build (see
        # [the rule](#projection-security-boundary)).

UserListType.Meta.exclude_fields cannot be honored: the node type for User
is reused from UserType, which was built from its own Meta, so the
projection would be silently dropped and any field it hides would stay
exposed. Declare exclude_fields on UserType instead, or remove the option.

Helper Methods¶

To mount a DjangoListObjectType on your Query, wrap it in a DjangoListObjectField — that produces the paginated results / totalCount field with the declared filters. The type also provides a RetrieveField() classmethod that builds a single-object lookup (by id) from the same node type:

from django_graphex.fields import DjangoListObjectField
from django_graphex.core import ObjectType

class Query(ObjectType):
    # Preferred: use DjangoListObjectField directly
    users = DjangoListObjectField(UserListType, description="List all users")
    # Or use the RetrieveField shorthand for a single object
    user = UserListType.RetrieveField(description="Get single user")

Declaring fields: the descriptor API¶

When a model doesn't already provide a field — a computed value, a hand-written mutation payload, a custom argument — declare it with a capitalized field descriptor imported from django_graphex.core. This is the primary idiom for custom (non-model) fields:

from django_graphex.core import CharField, IntField, Field, ObjectType

class UserType(ObjectType):
    full_name  = CharField(description="First + last")   # -> String
    post_count = IntField(required=True)                 # -> Int!
    email      = CharField(source="user_email")          # reads root.user_email

    def resolve_full_name(self, info):
        return f"{self.first_name} {self.last_name}"

Every descriptor compiles to the exact same graphql-core type as the low-level field() substrate it wraps — the SDL is byte-identical. The descriptors just give you a Django-model-field-style surface (source=, required=, typed shortcuts) with real import-time names your IDE can resolve.

Scalar shortcuts¶

Each shortcut binds one GraphQL scalar. There are 11 of them, and every one is position-agnostic — the same shortcut works in an ObjectType body (output) and in a class Arguments body (input). Use them anywhere you'd hand-write Field(<scalar>):

Every shortcut accepts the same keyword surface (the same one the unified Field accepts):

Setting an output-only keyword (source= / resolver=) on a field used in an argument position raises a clear TypeError; setting the input-only default= in an output position raises a TypeError at output compile.

For a type with no named shortcut (a DjangoObjectType reference, a GraphQLList/GraphQLNonNull wrapper, a custom scalar), use the general Field descriptor — it takes any type positionally and offers the same surface:

from graphql import GraphQLList, GraphQLString
from django_graphex.core import Field

class Query(ObjectType):
    me   = Field(UserType)                       # a DjangoObjectType reference
    tags = Field(GraphQLList(GraphQLString))     # list via the graphql-core wrapper
    slug = Field(GraphQLString, required=True)   # -> String!

Custom fields with resolvers¶

Descriptors work the same on a DjangoObjectType: declare the field on the class body and it is merged with the model-derived fields. When source= isn't enough, back the field with a resolve_<name> method — the contract is:

• The method name is resolve_ + the snake_case attribute name of a field declared on the class (full_name → resolve_full_name).
• It is called as resolve_<name>(self, info, **args): self is the object being serialized (the model instance on a DjangoObjectType), info.context is the request, and the field's declared arguments arrive as keyword arguments.
• Precedence: an explicit resolver= callable on the descriptor wins over the method; source= is the no-logic shortcut (it reads the named attribute off the instance, calling it if it's a method).

from django.contrib.auth.models import User
from graphql import GraphQLArgument, GraphQLInt, GraphQLString
from django_graphex.core import CharField, Field
from django_graphex.types import DjangoObjectType

class UserType(DjangoObjectType):
    # source= shortcut — reads (or calls) `get_short_name` on the instance.
    initials = CharField(source="get_short_name")

    # Computed field backed by the resolve_full_name method below.
    full_name = CharField(description="First + last name")

    # A field with its own GraphQL arguments; the resolver reads them as kwargs.
    greeting = Field(
        GraphQLString,
        args={"width": GraphQLArgument(GraphQLInt)},
    )

    class Meta:
        model = User
        only_fields = ("id", "username", "first_name", "last_name")

    def resolve_full_name(self, info):
        return f"{self.first_name} {self.last_name}".strip()

    def resolve_greeting(self, info, width=None):
        text = f"Hello, {self.username}!"
        return text.center(width) if width else text

{ user(id: 1) { fullName initials greeting(width: 30) } }

Argument dict keys are used verbatim as the wire names (declare a multi-word argument in camelCase, e.g. args={"maxWidth": ...}); each argument reaches the resolver as its snake_case keyword (max_width). The same contract applies on a plain ObjectType root (see the Query examples above) and on a DjangoModelType, where the resolver is forwarded to the generated output type.

Arguments use the same descriptors¶

There is one Field for both positions. Arguments on a hand-written Mutation (or inside Field(args={...})) are declared with the very same Field / scalar shortcuts you use in an ObjectType body — the direction comes from the declaration site, never from the descriptor. Field accepts either a DjangoInputObjectType / InputType CLASS (resolved lazily to its compiled input type) or a bare graphql-core scalar, so one descriptor covers both cases:

from django_graphex.core import CharField, Field, Mutation

class CreateUser(Mutation):
    class Arguments:
        new_user = Field(UserCreateInput, required=True)  # an input-object CLASS
        note     = CharField()                            # a bare String arg

    user = Field(UserType)
    ...

Field(SomeInput, required=True) replaces the older lambda: GraphQLArgument(GraphQLNonNull(SomeInput._meta.graphql_input_type)) thunk — same lazy timing, one readable line. In an argument position, a scalar shortcut accepts required=, default=, description=, name=, and deprecation_reason=; the output-only source= / resolver= / args= raise a clear TypeError if set there.

'name': got a django.db.models.Field (<django.db.models.CharField>). Did you
import CharField from django.db.models instead of django_graphex.core? Use
django_graphex.core.CharField (or Field) for GraphQL fields.

from graphql import GraphQLString
from django_graphex.core import field

server_time = field(GraphQLString, description="ISO timestamp")

DjangoInputObjectType¶

Creates input types for mutations based on Django models.

from django_graphex.types import DjangoInputObjectType
from myapp.models import Article

class ArticleInput(DjangoInputObjectType):
    class Meta:
        description = "Article input for mutations"
        model = Article
        only_fields = ("title", "body", "status")
        # or exclude specific fields
        # exclude_fields = ("internal_notes",)

Advanced Configuration¶

A DjangoInputObjectType derives its input fields from the model. Shape them with only_fields / exclude_fields and a description:

from django_graphex.types import DjangoInputObjectType

class ArticleCreateInput(DjangoInputObjectType):
    """Input for creating an article."""

    class Meta:
        model = Article
        only_fields = ("title", "body", "status")
        description = "Input type for article creation"

class ArticleUpdateInput(DjangoInputObjectType):
    """Input for updating an existing article."""

    class Meta:
        model = Article
        only_fields = ("title", "body", "status")
        description = "Input type for article updates"

Usage in Mutations¶

A DjangoInputObjectType is most often wired through a DjangoModelMutation, which consumes it automatically. For a hand-written Mutation, pass the input-type class to Field — it resolves the compiled input type lazily at schema-build time, so you reference the class directly with no thunk boilerplate:

from django_graphex.core import BooleanField, Field, Mutation

class CreateUserMutation(Mutation):
    class Arguments:
        new_user = Field(UserCreateInput, required=True)

    user = Field(UserType)
    success = BooleanField()

    @classmethod
    def mutate(cls, root, info, **kwargs):
        # The input object arrives as a dict of the declared fields.
        new_user = kwargs["new_user"]
        username = new_user["username"]
        email = new_user["email"]
        # ... mutation logic
        return cls(user=..., success=True)

Field(UserCreateInput, required=True) compiles to exactly the same GraphQLArgument(GraphQLNonNull(...)) the older lambda thunk produced. The thunk form still works as a low-level substrate — see Declaring fields: the descriptor API.

DjangoModelType¶

from myapp.models import Article
from django_graphex.types import DjangoModelType
from django_graphex.paginations import LimitOffsetGraphqlPagination

class ArticleType(DjangoModelType):
    class Meta:
        description = "Article type with auto-generated operations"
        model = Article
        pagination = LimitOffsetGraphqlPagination(
            default_limit=25,
            ordering="-published_at"
        )
        filter_fields = {
            "title": ("exact", "icontains"),
            "status": ("exact",),
        }

Custom queryset & per-request filtering¶

For anything beyond a static Meta.queryset, override two hooks. info.context is the request:

from django.db.models import Count, F
from myapp.models import Author

class AuthorType(DjangoModelType):
    class Meta:
        model = Author

    @classmethod
    def get_queryset(cls, manager, info, **kwargs):
        # custom base queryset for retrieve/list (and mutation responses)
        return Author.objects.select_related("user").annotate(
            email=F("user__email"),
            post_count=Count("posts"),
        )

    @classmethod
    def filter_queryset(cls, qs, info, **kwargs):
        # per-request scoping; default returns `qs` unchanged
        user = info.context.user
        if user.is_superuser:
            return qs
        return qs.filter(user=user)

• get_queryset(cls, manager, info, **kwargs) supplies the base queryset and applies filter_queryset; the default uses Meta.queryset (else the model manager).
• filter_queryset(cls, qs, info, **kwargs) is the scoping hook; the default is a no-op. It scopes every CRUD operation: update and delete resolve the row they are about to write through it too, and a row outside the scope is reported as not found instead of being written.

Custom output fields¶

To expose a field that isn't a plain model column (a model @property, an annotated value, a computed URL…), declare it directly on the DjangoModelType. It is added to the generated output type, so it shows up in both RetrieveField() and ListField() — no separate DjangoObjectType required:

from django_graphex.core import CharField, IntField

class AuthorType(DjangoModelType):
    # Typed descriptors, resolved from the instance (here from the annotations
    # added in get_queryset above, and a model property). `source=` reads the
    # named attribute off the instance.
    post_count = IntField(source="post_count")
    email = CharField(source="email")
    avatar_url = CharField(source="avatar_url")   # a model @property

    class Meta:
        model = Author

• The field is resolved like any descriptor: source="x" reads getattr(instance, "x"), or add a resolve_<name> method for custom logic.
• It appears in the detail and the list, because the list reuses the same item type.

resolve_<field> methods¶

A custom field can also be backed by a resolve_<field> method declared on the DjangoModelType — not just source=. The resolver is forwarded onto the generated output type, so it runs for both the retrieve and the list. This lets a custom field return another GraphQL type with arbitrary logic:

from django_graphex.core import Field
from django_graphex.types import DjangoModelType
from myapp.types import CommentType
from myapp.models import Post

class PostType(DjangoModelType):
    # A computed object field, resolved by the method below.
    featured_comment = Field(CommentType)

    class Meta:
        model = Post

    def resolve_featured_comment(self, info):
        # `self` is the Post instance being serialized; return any object
        # CommentType can resolve (here, the first approved comment).
        return self.comments.filter(is_approved=True).first()

• The method name must be resolve_<field> where <field> is the attribute name of a custom field declared on the class. It receives (self, info), with self bound to the model instance and info.context the request.
• The most-derived resolve_<field> wins, so a subclass can override an inherited resolver by redeclaring the method.
• A resolve_<x> without a matching custom field is ignored (it is not forwarded to the output type).

Custom fields are inherited like normal class attributes, so shared fields can live on an abstract base and a subclass may override one by redeclaring it:

from django_graphex.core import CharField, IntField

class TimestampedType(DjangoModelType):
    age = CharField(source="age_display")   # shared by subclasses

    class Meta:
        abstract = True

class InvoiceType(TimestampedType):
    total = IntField(source="total_cents")     # adds its own

    class Meta:
        model = Invoice        # gets `age` + `total`

Limiting the generated operations — model_operations¶

A DjangoModelType serves all five operations it can generate, so a type that declares nothing behaves exactly as it always has. Narrow that with Meta.model_operations:

That last clause is the opt-out for nested-write scoping: a DjangoModelType is a write host for the models a parent nests through Meta.nested_fields, so its Meta.queryset and its only_fields gate that nested write. In the common read-type-plus-write-mutation split that queryset is a display default, not a policy — declaring the type a read host says so:

class UserCard(DjangoModelType):
    class Meta:
        model = User
        # A display default, NOT a policy: hide deactivated users from the card.
        queryset = User.objects.filter(is_active=True)
        model_operations = ("list", "retrieve")

class Query(ObjectType):
    user_retrieve, user_list = UserCard.QueryFields()   # both still generated

UserCard.CreateField() now raises AttributeError, MutationFields() returns an empty tuple, and the card's queryset no longer decides whether a parent may write a User inline. Its read fields are unchanged. See the Meta reference for the full option table.

Auto-generated Query Fields¶

A DjangoModelType builds its read operations for you: RetrieveField() returns a single-object lookup (by id, routed through the type's get_queryset / filter_queryset hooks) and ListField() returns the paginated + filtered list with the uniform results / totalCount shape. QueryFields() is the shorthand that returns both at once. The GraphQL field names come from the attribute names you assign them to (article_retrieve → articleRetrieve):

from django_graphex.core import ObjectType

class Query(ObjectType):
    # Generate both retrieve and list queries automatically
    article_retrieve, article_list = ArticleType.QueryFields(
        description='Article queries'
    )

    # Or define them separately
    article_detail = ArticleType.RetrieveField(
        description='Get one article by ID'
    )
    article_list_custom = ArticleType.ListField(
        description='List articles with filtering and pagination'
    )

Auto-generated Mutation Fields¶

The write side is generated the same way: CreateField(), DeleteField() and UpdateField() each return a complete mutation — input type derived from the model, validation and DB integrity checks included — whose payload carries the mutated object plus ok / errors. MutationFields() is the shorthand that returns them in create, delete, update order:

from django_graphex.core import ObjectType

class Mutation(ObjectType):
    # Generate all CRUD mutations
    article_create, article_delete, article_update = ArticleType.MutationFields(
        description='Article write operations'
    )

    # Or define them separately
    create_article = ArticleType.CreateField(description='Create an article')
    delete_article = ArticleType.DeleteField(description='Delete an article')
    update_article = ArticleType.UpdateField(description='Update an article')

Both shorthands return only the operations Meta.model_operations enables, so the three-name unpack above is what the default — every operation — produces. Narrow the option and the tuple shrinks with it: a type declaring model_operations = ("list", "retrieve") returns an empty tuple from MutationFields(), and the unpack raises ValueError: not enough values to unpack. Unpack as many names as the type serves, or call the individual *Field() builders.

Custom mutation arguments — class Arguments¶

The generated mutations accept extra arguments beyond the auto-derived input object. Declare a class Arguments on the DjangoModelType — its members are added to every generated mutation (create / update / delete) alongside new_<model>, using the same argument descriptors as a hand-written Mutation (a raw GraphQLArgument also works):

from django_graphex.core import BooleanField
from django_graphex.types import DjangoModelType

class ArticleType(DjangoModelType):
    class Arguments:
        dry_run = BooleanField(description="Validate only; do not save")

    class Meta:
        model = Article

mutation {
  articleCreate(newArticle: { title: "Draft" }, dryRun: true) { ok }
}

The extra argument reaches the resolver as a snake_case kwarg — consume it by overriding the operation classmethod and delegating to super():

    @classmethod
    def create(cls, root, info, dry_run=False, **kwargs):
        if dry_run:
            return cls(ok=True)
        return super().create(root, info, **kwargs)

Custom validation¶

For field-level validation beyond the automatic DB checks, see Model backend (Pydantic) — the authoritative reference for inline validate_<field>() validators and Meta.pydantic_model. All validation patterns are documented there in one place.

Validation errors¶

When a create/update fails validation, the mutation returns ok: false and an errors list of { field, messages }:

{ "ok": false, "errors": [{ "field": "email", "messages": ["Enter a valid email."] }] }

• Errors from nested writes (Meta.nested_fields) are reported with the nested field name as a prefix — field: "addresses.zip_code" — including nested list children.
• non_field_errors is surfaced with an empty field (or just the nested model name).

DjangoUnionType — typed GenericForeignKey targets¶

DjangoUnionType is the base for a GraphQL Union whose members are concrete DjangoObjectTypes. Its primary use is to expose a Django GenericForeignKey (GFK) as a typed union instead of the flat GenericForeignKeyType scalar — so a client can select concrete fields per member with inline fragments (... on AccountType { balance }).

Members are explicitly enumerated via Meta.types; the library never inspects the django_content_type table to discover them.

Required declaration order¶

The declaration order is load-bearing (no lazy string forward-references in this release):

1. Declare the member DjangoObjectTypes first.
2. Declare the DjangoUnionType with Meta.types = (MemberAType, MemberBType).
3. Declare the owner DjangoObjectType LAST, naming its GFK union via Meta.unions = {"<gfk_field_name>": TheUnion}.

from django_graphex.types import DjangoObjectType, DjangoUnionType

# 1. Members first.
class AccountType(DjangoObjectType):
    class Meta:
        model = Account

class InvoiceType(DjangoObjectType):
    class Meta:
        model = Invoice

# 2. The union, enumerating members explicitly.
class CommentTargetUnion(DjangoUnionType):
    class Meta:
        types = (AccountType, InvoiceType)

# 3. The GFK owner LAST, mapping the GFK field name -> the union.
class CommentType(DjangoObjectType):
    class Meta:
        model = Comment              # has `target = GenericForeignKey(...)`
        unions = {"target": CommentTargetUnion}

Querying it:

{
  comments {
    target {
      __typename
      ... on AccountType { balance }
      ... on InvoiceType { amount }
    }
  }
}

If the union is declared after the owner (mis-ordered), the converter emits a WARNING and falls back to the flat GenericForeignKeyType — the schema still builds, but the field is not a union.

resolve_type is mandatory (and provided)¶

DjangoUnionType.resolve_type(instance, info) maps a plain Django row to its registered DjangoObjectType via registry.get_type_for_model(type(instance)). It raises a descriptive TypeError if a row's model has no registered type (rather than returning None, which would surface GraphQL's opaque "Abstract type must resolve to an Object type"). You do not override it.

Per-content-type column narrowing (Django 5.0+)¶

When OPTIMIZE_ONLY_FIELDS is on and Django is 5.0 or newer, the optimizer routes the union GFK through a GenericPrefetch, building one narrowed queryset per content type — each .only()-restricted to exactly the columns that member's inline fragment selected (e.g. the Account queryset fetches balance, the Invoice queryset fetches amount). This batches all parents into one query per content type (no N+1).

• Django < 5.0: the optimizer degrades gracefully to a single bare, full-load Prefetch — it never imports GenericPrefetch, never narrows columns, and is never slower than the pre-union behaviour.
• Per-content-type uniqueness: each distinct content type gets exactly one queryset. Two members backed by the same concrete table (e.g. proxy models) are collapsed into one queryset whose .only() columns are the union of both members' selections. Divergent per-row narrowing on a single shared table is out of scope; that bucket safely degrades to full-load.

DjangoInterfaceType — shared fields across types¶

DjangoInterfaceType is the base for a GraphQL Interface that declares fields shared by several DjangoObjectType implementors (typically backed by a shared abstract Django base model). It is schema-level field sharing only — it introduces no new queryset/fetch path; each implementor's own model drives its column narrowing.

from django_graphex.core import CharField
from django_graphex.types import DjangoInterfaceType, DjangoObjectType

class ProductInterface(DjangoInterfaceType):
    name = CharField()
    class Meta:
        pass

class BookType(DjangoObjectType):
    class Meta:
        model = Book
        interfaces = (ProductInterface,)

class MagazineType(DjangoObjectType):
    class Meta:
        model = Magazine
        interfaces = (ProductInterface,)

Implementors declare membership with the Meta.interfaces kwarg. Like DjangoUnionType, DjangoInterfaceType provides a mandatory resolve_type that maps each row to its concrete implementor.

Limiting query shape: max_depth & complexity¶

Every type above accepts two optional Meta options that protect your API from abusive queries. They are enforced before execution by the validation rules the library's GraphQLView enables by default. See Query depth & cost limits for the full reference; the mini-examples below are the gist.

max_depth — caps how many nested object levels may be selected below a field returning this type (scalars don't count):

class CategoryType(DjangoModelType):
    class Meta:
        model = Category
        max_depth = 2          # category -> posts -> comments OK; one level deeper is rejected

{
  category(id: 1) {
    posts {                # level 1 ✅
      comments {           # level 2 ✅
        author { username }  # level 3 ❌ "Query exceeds the maximum nesting depth of 2 ..."
      }
    }
  }
}

complexity — the cost weight of a field returning this type, used by cost analysis (MAX_QUERY_COST). Make expensive types cost more so a single page of them eats more of the budget:

class ReportType(DjangoObjectType):
    class Meta:
        model = Report
        complexity = 50       # one report is worth 50; default object weight is 1

Both work on DjangoObjectType, DjangoListObjectType and DjangoModelType (forwarded to its generated output type). A global depth cap (MAX_QUERY_DEPTH) and cost budget (MAX_QUERY_COST) are configured in settings — see Query depth & cost limits.

choices → GraphQL enums¶

Any model field with choices becomes a GraphQL enum automatically — on every type above (DjangoObjectType, DjangoListObjectType, DjangoModelType). The interesting part is how each enum member name is chosen, because GraphQL enum names must be valid identifiers (letters, digits, underscores; not starting with a digit) and should stay readable and stable across locales.

For each (value, label) choice the name is picked by this cascade:

1. The value, if it is already a valid GraphQL name — e.g. a Django TextChoices value "draft" becomes DRAFT.

2. Otherwise the label, resolved as its source msgid with translations off, so the schema is the same in every locale. This is why numeric values with human labels surface readably:

   GENDER_CHOICES = (("1", _("Male")), ("2", _("Female")))
   # -> enum members MALE / FEMALE   (NOT A_1 / A_2, and locale-independent)
   

3. Otherwise A_<value> as a last resort — e.g. a numeric value whose label is empty or also non-identifier-safe yields A_1, A_2, …

from django.db import models
from django.utils.translation import gettext_lazy as _

class Profile(models.Model):
    # value -> member name
    status = models.CharField(                  # "draft" -> DRAFT (from the value)
        max_length=20,
        choices=(("draft", "Draft"), ("published", "Published")),
    )
    gender = models.CharField(                   # "1"/"2" -> MALE/FEMALE (from the label)
        max_length=1,
        choices=(("1", _("Male")), ("2", _("Female"))),
    )

The enum member's description carries the original label, so the human-readable text is never lost.

MultiSelectField¶

When the optional django-multiselectfield package is installed, a MultiSelectField is a list of the generated choice enum, not one enum value. Detection uses isinstance, so a renamed subclass keeps the same shape in output and generated create/update input:

from multiselectfield import MultiSelectField


class FeatureFlagsField(MultiSelectField):
    pass


class Account(models.Model):
    flags = FeatureFlagsField(choices=(("beta", "Beta"), ("dark", "Dark")))

type AccountType { flags: [AccountFlagsEnum] }
input AccountCreateInput { flags: [AccountFlagsEnum] }
input AccountUpdateInput { flags: [AccountFlagsEnum] }

django-multiselectfield remains optional: install it only when the model uses that field. Without the package, importing django-graphex adds no runtime dependency. The development and integration environments install it only to exercise this optional adapter.

Field type conversion reference¶

How Django model fields map to GraphQL output types:

Worked example — ArrayField (incl. a choices base) and a range field:

from django.contrib.postgres.fields import ArrayField, IntegerRangeField
from django.db import models

class Article(models.Model):
    tags = ArrayField(models.CharField(max_length=50))          # -> tags: [String]
    grid = ArrayField(ArrayField(models.IntegerField()))        # -> grid: [[Int]]
    statuses = ArrayField(                                      # -> statuses: [ArticleStatusesEnum]
        models.CharField(max_length=10, choices=(("draft", "Draft"), ("pub", "Published"))),
    )
    span = IntegerRangeField()                                  # -> span: { lower: Int, upper: Int }

{ articles { tags grid statuses span { lower upper } } }

Accepted date/time input formats¶

DateField / DateTimeField / TimeField (both the model-derived output fields and the DateField() / DateTimeField() / TimeField() shortcuts) parse input with Python's datetime.fromisoformat, and serialize output with .isoformat(). What that means in practice:

Output is always .isoformat(), so an aware datetime renders with an explicit offset (2024-01-15T10:30:00+00:00) — never the shorthand Z.

JSONField → JSON¶

A model JSONField is exposed as the JSON scalar in every direction. JSON carries raw structured JSON on the wire: objects, lists, and scalars pass through as-is, with no string-encoding step and no client-side JSON.parse.

from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=100)
    specs = models.JSONField(null=True, blank=True)

# Inline object literal — accepted (no variables required):
mutation {
  productCreate(newProduct: { name: "Laptop", specs: { ram: 16, tags: ["a", "b"] } }) {
    product {
      specs      # -> { "ram": 16, "tags": ["a", "b"] }  (a real object; no parsing)
    }
    ok
  }
}

# Variables work too:
mutation CreateProduct($specs: JSON) {
  productCreate(newProduct: { name: "Laptop", specs: $specs }) {
    product { specs }
    ok
  }
}
# variables: { "specs": { "ram": 16 } }

Omitting specs leaves the column untouched; passing specs: null writes SQL NULL — the usual omit-vs-null semantics, unchanged.

from django_graphex.core import JSONField, ObjectType

class Query(ObjectType):
    config     = JSONField()              # -> JSON:       { "theme": "dark" }
    raw_config = JSONField(as_str=True)   # -> JSONString: "{\"theme\": \"dark\"}"

    def resolve_config(self, info):
        return {"theme": "dark"}   # sent as a JSON object

    def resolve_raw_config(self, info):
        return {"theme": "dark"}   # serialized to a JSON string

from django_graphex.core import GdxJSON, GdxJSONString

query Echo($d: JSON) { echo(data: $d) }
# variables: { "d": { "a": [1, 2] } }

Type Comparison¶

Best Practices¶

1. Choose the Right Type¶

# ✅ For list queries with custom logic
class UserListType(DjangoListObjectType):
    class Meta:
        model = User

# ✅ For input validation on an ordinary application model
class ArticleInput(DjangoInputObjectType):
    class Meta:
        model = Article
        only_fields = ("title", "body")

# ✅ For rapid prototyping
class ArticleType(DjangoModelType):
    class Meta:
        model = Article

2. Use Descriptive Names¶

# ✅ Clear naming
class UserListType(DjangoListObjectType): pass
class CreateUserInput(DjangoInputObjectType): pass
class UserCRUDType(DjangoModelType): pass

# ❌ Confusing naming
class UserType(DjangoListObjectType): pass  # Is it single or list?
class UserInput(DjangoModelType): pass  # Not an input type

3. Optimize Performance¶

class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        # Optimize database queries
        queryset = User.objects.select_related('profile').prefetch_related('groups')

        # Enable caching for expensive queries
        # (Configure in settings)

Limit the exposed fields with only_fields / exclude_fields (never fields / exclude) on the node type, not on the container: a container that reuses a registered DjangoObjectType cannot honour a projection of its own and refuses to build with one — see the projection is a security boundary. Narrowing the surface is a security decision before it is a performance one, which is precisely why it has exactly one home.

4. Combine Types Strategically¶

# Use DjangoModelType for basic CRUD on ordinary application models
class ArticleType(DjangoModelType):
    class Meta:
        model = Article

# Use DjangoListObjectType for complex list logic
class UserAnalyticsType(DjangoListObjectType):
    total_posts = IntField()          # a custom, computed output field

    class Meta:
        model = User

    def resolve_total_posts(self, info):
        return self.posts.count()

# Use DjangoInputObjectType for model-derived input; shape it with only_fields.
# For a bespoke, non-model input argument, use a hand-written Mutation with a
# Field / CharField argument instead (input bodies are model-derived).
class ArticleImportInput(DjangoInputObjectType):
    class Meta:
        model = Article
        only_fields = ("title", "body", "status")

For Django accounts, use the read-only projection and purpose-built create_user() registration shown in the Quick Start; generic model persistence does not hash passwords.

These examples assume the descriptor imports at the top of the module:

from django_graphex.core import IntField