Types API Reference¶

This section provides detailed API documentation for GraphQL type classes in django-graphex.

Field descriptors¶

Capitalized field descriptors for declaring custom (non-model) fields and mutation arguments. All are imported from django_graphex.core. See Declaring fields: the descriptor API for the usage guide.

Field (both positions)¶

Field(type, *, source=None, required=False, default=_UNSET, description=None,
      name=None, resolver=None, args=None, deprecation_reason=None)

One descriptor for both positions — an ObjectType / Mutation payload body (output) and a class Arguments body or Field(args={...}) / field(args={...}) mapping (input). Direction comes from the declaration site, never from the descriptor. type takes:

• Output: any graphql-core output type, a DjangoObjectType reference (resolved lazily), or a NativeList / NativeNonNull wrapper.
• Input: a DjangoInputObjectType / InputType CLASS (resolved lazily to its compiled input type) or a bare graphql-core scalar.

Wrong-position keywords fail loud: an output-only source= / resolver= / args= set on a field used in an argument position raises a clear TypeError; the input-only default= set in an output position raises a TypeError at output compile.

Scalar shortcuts¶

There are 11 shortcuts, each binding one scalar and each position-agnostic (usable in an ObjectType body and a class Arguments body). Each returns a Field. Signature: (*, source=None, required=False, default=_UNSET, description=None, name=None, resolver=None, deprecation_reason=None) (JSONField additionally takes as_str=False).

The 12 former *InputField twins (CharInputField, IntInputField, …) and the standalone InputField descriptor are removed in 2.0 — the single Field and these shortcuts cover both positions.

DjangoObjectType¶

Enhanced Django model GraphQL type with filtering and pagination support.

class DjangoObjectType(ObjectType)

Meta Configuration¶

The DjangoObjectType is configured through a nested Meta class:

class UserType(DjangoObjectType):
    class Meta:
        model = User
        only_fields = ('id', 'username', 'first_name', 'last_name')
        filter_fields = {'username': ('exact', 'icontains')}

DJANGO_GRAPHEX = {"CACHE_ACTIVE": False}

Meta Options¶

Methods¶

resolve_id(info)¶

Resolve the ID field for the object.

Returns: Primary key value of the model instance

is_type_of(root, info) (classmethod)¶

Check if the root object is of this type.

Parameters: - root (Any): Object to check - info (ResolveInfo): GraphQL resolve info

Returns: bool - True if object matches this type

get_queryset(queryset, info) (classmethod)¶

Override to customize the queryset used for this type. Applied wherever the type is mounted — at the root and through a parent relation alike.

Parameters: - queryset (QuerySet): Base queryset - info (ResolveInfo): GraphQL resolve info

Returns: Modified QuerySet

Raises: TypeError if the override returns anything other than a QuerySet (the scope cannot be honoured, so the request is denied instead of serving unscoped rows)

get_node(info, id) (classmethod)¶

Get a single node by ID. The lookup runs through get_queryset, so a row the scope excludes is reported as missing — the ID comes straight from the caller.

Parameters: - info (ResolveInfo): GraphQL resolve info - id (Any): Object identifier

Returns: Model instance or None

Example Usage¶

from django_graphex.types import DjangoObjectType
from .models import User

class UserType(DjangoObjectType):
    class Meta:
        model = User
        description = "User account type"
        only_fields = ('id', 'username', 'first_name', 'last_name')

class UserType(DjangoObjectType):
    class Meta:
        model = User
        only_fields = ('id', 'username', 'first_name', 'last_name')
        filter_fields = {
            'username': ('exact', 'icontains'),
            'first_name': ('exact', 'icontains'),
            'last_name': ('exact', 'icontains'),
        }

class UserType(DjangoObjectType):
    class Meta:
        model = User
        only_fields = ('id', 'username', 'first_name', 'last_name')
        # Alternative: exclude_fields = ('password', 'user_permissions')

class UserType(DjangoObjectType):
    class Meta:
        model = User
        only_fields = ('id', 'username', 'first_name', 'last_name')

    @classmethod
    def get_queryset(cls, queryset, info):
        return queryset.select_related('profile').prefetch_related('posts')

DjangoInputObjectType¶

Django model GraphQL input type for mutations and arguments.

class DjangoInputObjectType(InputType)  # InputType = django_graphex.core

Meta Configuration¶

Configure input types through the Meta class:

class ArticleInput(DjangoInputObjectType):
    class Meta:
        model = Article
        input_for = 'create'
        only_fields = ('title', 'body', 'status')

Meta Options¶

nested_parent_model is what makes a nested payload writable without repeating the parent's id: the nested writer injects that key at save time, so requiring it inline would make every nested create unsatisfiable. It is set automatically on the per-parent child input a Meta.nested_fields entry builds (see the nested child input type); set it by hand only on an input you mount yourself inside another model's input. The child's Pydantic validation model still requires the key, so a standalone create that omits it fails cleanly.

Methods¶

get_type() (classmethod)¶

Get the type when the unmounted type is mounted.

Returns: The input type class

Example Usage¶

from django_graphex.types import DjangoInputObjectType

class ArticleCreateInput(DjangoInputObjectType):
    class Meta:
        model = Article
        input_for = 'create'
        only_fields = ('title', 'body', 'status')

class ArticleUpdateInput(DjangoInputObjectType):
    class Meta:
        model = Article
        input_for = 'update'
        exclude_fields = ('internal_notes',)

class ArticleDeleteInput(DjangoInputObjectType):
    class Meta:
        model = Article
        input_for = 'delete'

class ArticleInput(DjangoInputObjectType):
    class Meta:
        model = Article
        input_for = 'create'
        # {accessor name: child model} — the relations to expand
        # into nested input objects
        nested_fields = {'profile': Profile, 'addresses': Address}

DjangoListObjectType¶

GraphQL type for paginated lists of Django objects with count and results.

class DjangoListObjectType(ObjectType)

Meta Configuration¶

Configure list types with pagination and filtering:

class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        pagination = LimitOffsetGraphqlPagination(default_limit=25)

Meta Options¶

Generated Fields¶

A DjangoListObjectType automatically generates these fields:

Pagination and ordering arguments (limit, offset, page, pageSize, first, ordering, cursor arguments) are placed on the results(...) subfield. totalCount (and pageInfo, for cursor pagination) are siblings of results. Filter arguments are placed on the list field itself.

Methods¶

RetrieveField(**kwargs) (classmethod)¶

Create a field for retrieving a single object from this list type.

Parameters: - **kwargs: Additional field arguments

Returns: DjangoObjectField instance

BaseType() (classmethod)¶

Return the base DjangoObjectType wrapped by this list type.

Returns: The base object type class

Example Usage¶

from django_graphex.paginations import LimitOffsetGraphqlPagination
from django_graphex.types import DjangoListObjectType

class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        description = "Paginated list of users"
        pagination = LimitOffsetGraphqlPagination(default_limit=20)

from django_graphex.paginations import PageGraphqlPagination

class PostListType(DjangoListObjectType):
    class Meta:
        model = Post
        pagination = PageGraphqlPagination(
            page_size=15,
            page_size_query_param='pageSize'
        )
        filter_fields = {
            'title': ('icontains',),
            'status': ('exact',),
            'author__username': ('icontains',),
        }

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

class UserListType(DjangoListObjectType):
    class Meta:
        model = User
        pagination = LimitOffsetGraphqlPagination(default_limit=25)

class Query(ObjectType):
    active_users = DjangoListObjectField(UserListType)

    def resolve_active_users(self, info, **kwargs):
        # A `resolve_<field>` returning a QuerySet is honored by
        # `queryset_factory`, scoping the list's base queryset.
        return User.objects.filter(is_active=True).select_related('profile')

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

class Query(ObjectType):
    # Preferred: DjangoListObjectField takes the list type directly
    all_users = DjangoListObjectField(UserListType)

    # RetrieveField() shorthand is available on DjangoListObjectType
    user = UserListType.RetrieveField()

schema = DjangoGraphQLSchema(query=Query)

GraphQL Response Structure¶

{
  "data": {
    "allUsers": {
      "totalCount": 150,
      "results": [
        {
          "id": "1",
          "username": "john_doe",
          "email": "john@example.com"
        },
        {
          "id": "2",
          "username": "jane_smith",
          "email": "jane@example.com"
        }
      ]
    }
  }
}

DjangoModelType¶

GraphQL type with automatic CRUD operations driven directly by a Django model.

class DjangoModelType(ObjectType)

Meta Configuration¶

Configure model types with automatic CRUD operations:

class ArticleType(DjangoModelType):
    class Meta:
        model = Article
        pagination = LimitOffsetGraphqlPagination(default_limit=25)

Meta Options¶

class ProfileCard(DjangoModelType):
    class Meta:
        model = Profile
        model_operations = ("list", "retrieve")
        only_fields = ("id", "display_name", "avatar")
        queryset = Profile.objects.filter(is_public=True)

>>> ProfileCard.CreateField()
AttributeError: "create" is not enabled on ProfileCard;
Meta.model_operations is ('list', 'retrieve').

ImproperlyConfigured: UserCard.Meta.only_fields cannot be honored: the
output 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 only_fields on UserType instead, or remove the
option.

Generated Methods¶

QueryFields(**kwargs) (classmethod)¶

Generate both single object and list query fields.

Returns: Tuple of (single_field, list_field), restricted to the operations enabled in Meta.model_operations

ListField(**kwargs) (classmethod)¶

Create a list field for this model type.

Returns: DjangoListObjectField instance

RetrieveField(**kwargs) (classmethod)¶

Create a retrieve field for single objects.

Returns: DjangoObjectField instance

MutationFields(**kwargs) (classmethod)¶

Generate the create, delete and update mutation fields.

Returns: Tuple of (create_field, delete_field, update_field), restricted to the operations enabled in Meta.model_operations

CreateField(**kwargs) / DeleteField(**kwargs) / UpdateField(**kwargs) (classmethod)¶

Create the individual mutation fields wired to the create, delete and update resolvers respectively.

Returns: Field instance

Override Hooks¶

DjangoModelType exposes hooks you can override on your subclass to scope querysets and enforce authorization across all CRUD operations:

get_queryset(manager, info, **kwargs) (classmethod)¶

Return the base queryset for retrieve, list and mutation responses. The default uses Meta.queryset (falling back to the model's default manager) and applies filter_queryset. Override to add select_related/annotate, etc.

filter_queryset(qs, info, **kwargs) (classmethod)¶

Per-request scoping hook. The default returns qs unchanged.

authorize(info, action, **kwargs) (classmethod)¶

Authorization hook called by every CRUD method before it runs. The default delegates to check_permissions using the configured permission_classes, raising GraphQLError when denied. Override to customize.

permission_classes (class attribute)¶

Tuple of permission classes checked per action. Empty (the default) means no checks. A permission denies on any falsy return value (False, None, 0, ""), so return user and user.is_staff is safe. See django_graphex.permissions.

Example Usage¶

from django_graphex.types import DjangoModelType
from .models import Article

class ArticleType(DjangoModelType):
    class Meta:
        model = Article
        description = "Article type"

class ArticleType(DjangoModelType):
    class Meta:
        model = Article
        pagination = LimitOffsetGraphqlPagination(default_limit=30)
        filter_fields = {
            'title': ('exact', 'icontains'),
            'status': ('exact',),
        }

from django_graphex.core import ObjectType
from django_graphex.schema import DjangoGraphQLSchema

class Query(ObjectType):
    # Generate both fields automatically
    article, articles = ArticleType.QueryFields()

    # Or create individual fields
    article_list = ArticleType.ListField()
    single_article = ArticleType.RetrieveField()

schema = DjangoGraphQLSchema(query=Query)

Type Registration¶

All types are automatically registered in a global registry for reuse and relationship resolution.

Registry Operations¶

from django_graphex.registry import get_global_registry

# Get the global registry
registry = get_global_registry()

# Check if a type is registered
user_type = registry.get_type_for_model(User)

# Register a type manually
registry.register(CustomUserType)

Custom Registry¶

Registry is part of the public API and can be imported directly from django_graphex:

from django_graphex.registry import Registry

# Create custom registry
custom_registry = Registry()

class UserType(DjangoObjectType):
    class Meta:
        model = User
        registry = custom_registry
        only_fields = ('id', 'username', 'first_name', 'last_name')

Advanced Usage¶

Custom Field Resolvers¶

from django_graphex.core import CharField, IntField

class UserType(DjangoObjectType):
    full_name = CharField()
    post_count = IntField()

    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}"

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

Dynamic Field Generation¶

class UserType(DjangoObjectType):
    class Meta:
        model = User
        only_fields = ('id', 'username', 'first_name', 'last_name')

    @classmethod
    def __init_subclass_with_meta__(cls, **options):
        # Add dynamic fields before calling super
        from django_graphex.core import CharField
        cls.custom_field = CharField()
        super().__init_subclass_with_meta__(**options)

Performance Optimization¶

class UserType(DjangoObjectType):
    class Meta:
        model = User
        only_fields = ('id', 'username', 'first_name', 'last_name')
        filter_fields = {
            'username': ('exact', 'icontains'),
        }

    @classmethod
    def get_queryset(cls, queryset, info):
        # Optimize queries with select_related and prefetch_related
        return queryset.select_related(
            'profile'
        ).prefetch_related(
            'posts',
            'posts__comments'
        )

Error Handling¶

Type Validation¶

class UserType(DjangoObjectType):
    class Meta:
        model = User
        only_fields = ('id', 'username', 'first_name', 'last_name')

    @classmethod
    def is_type_of(cls, root, info):
        # Custom type checking logic
        if hasattr(root, 'user_type'):
            return root.user_type == 'standard'
        return super().is_type_of(root, info)

Field Resolution Errors¶

from django_graphex.core import CharField

class UserType(DjangoObjectType):
    avatar_url = CharField()

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

    def resolve_avatar_url(self, info):
        try:
            if self.profile and self.profile.avatar:
                return self.profile.avatar.url
            return None
        except AttributeError:
            return None

Best Practices¶

Security Considerations¶

class UserType(DjangoObjectType):
    class Meta:
        model = User
        # Allow-list the complete public account surface.
        only_fields = ('id', 'username', 'first_name', 'last_name')

    @classmethod
    def get_queryset(cls, queryset, info):
        # Apply security filters
        if not info.context.user.is_staff:
            return queryset.filter(is_active=True)
        return queryset

DjangoUnionType¶

GraphQL Union over explicitly enumerated DjangoObjectType members.

class DjangoUnionType(ObjectType)  # ObjectType = django_graphex.core

Meta Options¶

Declaration Order (load-bearing)¶

1. Declare all member DjangoObjectTypes first.
2. Declare the DjangoUnionType with Meta.types.
3. Declare the owner DjangoObjectType LAST, referencing the union via Meta.unions (renamed from gfk_unions in 2.0; the old key raises ImproperlyConfigured).

A mis-ordered declaration logs a WARNING and falls back to GenericForeignKeyType — the schema still builds.

Methods¶

resolve_type(instance, info) (classmethod)¶

Maps a Django model instance to its registered DjangoObjectType via the global registry. Raises a descriptive TypeError if no type is registered for the instance's model (rather than returning None, which would surface an opaque GraphQL error).

You do not override this method.

Example Usage¶

from django_graphex.types import DjangoObjectType, DjangoUnionType

class AccountType(DjangoObjectType):
    class Meta:
        model = Account

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

class CommentTargetUnion(DjangoUnionType):
    class Meta:
        types = (AccountType, InvoiceType)

class CommentType(DjangoObjectType):
    class Meta:
        model = Comment              # has `target = GenericForeignKey(...)`
        unions = {"target": CommentTargetUnion}

See Types — DjangoUnionType for the full usage guide including optimizer behavior.

DjangoInterfaceType¶

GraphQL Interface for shared field declarations across multiple DjangoObjectType implementors.

class DjangoInterfaceType(ObjectType)  # ObjectType = django_graphex.core

Meta Options¶

No additional Meta options beyond the GraphQL interface basics. Implementors declare membership via the Meta.interfaces kwarg.

Methods¶

resolve_type(instance, info) (classmethod)¶

Maps a Django model instance to its registered concrete DjangoObjectType implementor via the global registry. Raises TypeError if the instance's model has no registered type.

You do not override this method.

Example Usage¶

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,)

See Types — DjangoInterfaceType for the full usage guide.

This comprehensive API reference covers all type classes in django-graphex, providing developers with the knowledge needed to effectively create and customize GraphQL types for their Django applications.