Fields API Reference¶

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

Field descriptors¶

The typed scalar shortcuts and the unified Field they route through. All are imported from django_graphex.core. See Fields → Typed scalar descriptors for the usage guide.

The Django*Field classes documented further down are siblings of Field, not subclasses of it: both Field and every Django*Field mount through the same NativeMountedField base.

`Field`¶

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

ONE descriptor, usable in both an OUTPUT position (an ObjectType / Mutation payload body) and an INPUT position (a class Arguments body or a Field(args={...}) / field(args={...}) mapping). Direction is never declared on the descriptor — it comes from the declaration site.

Keyword	Position	Effect
`source="attr"`	output only	Resolve by reading `attr` off the root (or calling it if callable). Raises `TypeError` in an input position.
`resolver`	output only	Field-level resolver (wins over the parent). Raises `TypeError` in an input position.
`args`	output only	Explicit `{name: arg}` mapping (each value itself a `Field` / shortcut). Raises `TypeError` in an input position.
`default`	input only	The GraphQL default value; omit to leave the argument with no default (an explicit `default=None` is a real `null` default). Raises `TypeError` at output compile time.
`required=True`	both	Wrap the type in non-null (`T!`).
`description`	both	Field / argument description.
`name`	both	Explicit wire name (skips camelCase on output; drives `out_name` on input).
`deprecation_reason`	both	Renders `@deprecated(reason: ...)` on the compiled field / argument.

Typed scalar shortcuts¶

Each shortcut returns a Field bound to one scalar, usable in both positions. Signature (identical for all 11): (*, source=None, required=False, default=_UNSET, description=None, name=None, resolver=None, deprecation_reason=None).

Shortcut	GraphQL type	Shortcut	GraphQL type
`IDField`	`ID`	`DateField`	`CustomDate`
`IntField`	`Int`	`DateTimeField`	`CustomDateTime`
`FloatField`	`Float`	`TimeField`	`CustomTime`
`BooleanField`	`Boolean`	`DecimalField`	`Decimal`
`CharField`	`String`	`UUIDField`	`UUID`

JSONField is the one bespoke shortcut — it takes an extra as_str flag:

JSONField(*, as_str=False, source=None, required=False, default=_UNSET,
          description=None, name=None, resolver=None, deprecation_reason=None)

as_str=False (the default) binds the raw JSON scalar (structured objects/lists pass through on both output and input). as_str=True binds JSONString, the string-encoding escape hatch.

No InputField

There is a single Field (and a single set of typed shortcuts) for both positions. InputField and the per-scalar *InputField twins do not exist in this API.

DjangoObjectField¶

A GraphQL field for querying a single Django model object by ID.

# Subclasses the native NativeMountedField
class DjangoObjectField(NativeMountedField)

Parameters¶

Parameter	Type	Description
`_type`	`DjangoObjectType`	The GraphQL type representing the Django model
`*args`	`Any`	Additional positional arguments passed to base Field
`deprecation_reason`	`str \\| None`	Optional; renders `@deprecated(reason: ...)` on the compiled field
`**kwargs`	`Any`	Additional keyword arguments passed to base Field

Attributes¶

Attribute	Type	Description
`model`	`Model`	The Django model class associated with this field

Methods¶

`object_resolver(manager, output_type, root, info, **kwargs)`¶

Static method that resolves a single object by its ID.

Parameters: - manager (Manager): Django model manager - output_type (type): The DjangoObjectType subclass for this field, forwarded to queryset_factory so its get_queryset hook is applied - root (Any): Parent object in GraphQL resolution - info (ResolveInfo): GraphQL resolve info - **kwargs: Query arguments including id

Returns: Model instance or None if not found

`wrap_resolve(parent_resolver)`¶

Wraps the resolver with the object resolver functionality.

Parameters: - parent_resolver (Callable): Parent resolver function

Returns: Wrapped resolver function

Example Usage¶

from django_graphex.fields import DjangoObjectField
from django_graphex.core import ObjectType
from django_graphex.schema import DjangoGraphQLSchema
from django_graphex.types import DjangoObjectType
from .models import User

class UserType(DjangoObjectType):
    class Meta:
        model = User

class Query(ObjectType):
    user = DjangoObjectField(UserType, description="Get a single user")

schema = DjangoGraphQLSchema(query=Query)

GraphQL Query¶

query GetUser($id: ID!) {
  user(id: $id) {
    id
    username
    email
  }
}

DjangoListField¶

A basic GraphQL field for querying a list of Django model objects.

# Subclasses the native NativeMountedField
class DjangoListField(NativeMountedField)

Parameters¶

Parameter	Type	Description
`_type`	`DjangoObjectType`	The GraphQL type representing the Django model
`*args`	`Any`	Additional positional arguments
`**kwargs`	`Any`	Additional keyword arguments

Properties¶

Property	Type	Description
`type`	`Field`	Returns the GraphQL field type

Example Usage¶

from django_graphex.core import ObjectType
from django_graphex.fields import DjangoListField

class Query(ObjectType):
    users = DjangoListField(UserType)

Not exported at the top level

DjangoListField is a low-level building block; import it from django_graphex.fields. For list queries prefer DjangoFilterListField, DjangoFilterPaginateListField or DjangoListObjectField (all imported from django_graphex.fields).

DjangoFilterListField¶

A GraphQL field for querying a filtered list of Django model objects.

# Subclasses the native NativeMountedField
class DjangoFilterListField(NativeMountedField)

Parameters¶

Parameter	Type	Default	Description
`_type`	`DjangoObjectType`	Required	The GraphQL type
`fields`	`dict`	`None`	Filter field configuration
`*args`	`Any`	-	Additional positional arguments
`deprecation_reason`	`str \\| None`	`None`	Renders `@deprecated(reason: ...)` on the compiled field
`**kwargs`	`Any`	-	Additional keyword arguments

Attributes¶

Attribute	Type	Description
`model`	`Model`	The Django model class
`fields`	`dict`	Filter field configuration
`filter_backend`	`object`	Native (`Q`-based) filter backend applied to the queryset
`filter_type`	`InputObjectType`	Generated `<Model>FilterInput` for the `filter:` argument

Methods¶

`list_resolver(manager, filter_backend, custom_filters, output_type, root, info, **kwargs)`¶

Static method that resolves a filtered list of objects.

Parameters: - manager (Manager): Django model manager - filter_backend (object): native filter backend; apply with filter_backend.apply(qs, kwargs.get("filter")) - custom_filters (list): list of (arg_name, method, metadata) triples from @filter_field-decorated methods on the output type - output_type (type): the DjangoObjectType subclass for this field; its get_queryset hook is applied on both resolution paths — inside queryset_factory for a fresh queryset, and directly on the relation when the field is reached through a parent object - root (Any): Parent object in GraphQL resolution - info (ResolveInfo): GraphQL resolve info - **kwargs: Query arguments including the filter value

Returns: Filtered QuerySet

Example Usage¶

from django_graphex.fields import DjangoFilterListField
from django_graphex.core import ObjectType

class Query(ObjectType):
    users = DjangoFilterListField(
        UserType,
        description="Filtered list of users"
    )

GraphQL Query¶

query GetFilteredUsers {
  users(filter: { username: { icontains: "john" }, isActive: { exact: true } }) {
    id
    username
    email
    isActive
  }
}

DjangoFilterPaginateListField¶

A GraphQL field for querying a filtered and paginated list of Django model objects.

# Subclasses the native NativeMountedField
class DjangoFilterPaginateListField(NativeMountedField)

Parameters¶

Parameter	Type	Default	Description
`_type`	`DjangoObjectType`	Required	The GraphQL type
`pagination`	`BaseDjangoGraphqlPagination`	Default pagination	Pagination configuration
`fields`	`dict`	`None`	Filter field configuration
`*args`	`Any`	-	Additional positional arguments
`deprecation_reason`	`str \\| None`	`None`	Renders `@deprecated(reason: ...)` on the compiled field
`**kwargs`	`Any`	-	Additional keyword arguments

Attributes¶

Attribute	Type	Description
`model`	`Model`	The Django model class
`fields`	`dict`	Filter field configuration
`filter_backend`	`object`	Native (`Q`-based) filter backend applied to the queryset
`filter_type`	`InputObjectType`	Generated `<Model>FilterInput` for the `filter:` argument
`pagination`	`BaseDjangoGraphqlPagination`	Pagination instance

Methods¶

`get_queryset(manager, root, info, **kwargs)`¶

Get the base queryset for this field.

Parameters: - manager (Manager): Django model manager - root (Any): Parent object - info (ResolveInfo): GraphQL resolve info - **kwargs: Query arguments

Returns: Base QuerySet

`list_resolver(manager, filter_backend, root, info, **kwargs)`¶

Resolve a filtered and paginated list of objects.

Parameters: - manager (Manager): Django model manager - filter_backend (object): native filter backend; apply with filter_backend.apply(qs, kwargs.get("filter")) - root (Any): Parent object - info (ResolveInfo): GraphQL resolve info - **kwargs: Query arguments including the filter value and pagination

Returns: Paginated QuerySet

Example Usage¶

from django_graphex.fields import DjangoFilterPaginateListField
from django_graphex.core import ObjectType
from django_graphex.paginations import LimitOffsetGraphqlPagination

class Query(ObjectType):
    users = DjangoFilterPaginateListField(
        UserType,
        pagination=LimitOffsetGraphqlPagination(default_limit=20),
        description="Paginated and filtered list of users"
    )

GraphQL Query¶

query GetPaginatedUsers {
  users(
    filter: { username: { icontains: "john" }, isActive: { exact: true } },
    limit: 10,
    offset: 20
  ) {
    id
    username
    email
    isActive
  }
}

DjangoListObjectField¶

A GraphQL field for Django list objects that returns both count and results.

# Subclasses the native NativeMountedField
class DjangoListObjectField(NativeMountedField)

Parameters¶

Parameter	Type	Default	Description
`_type`	`DjangoListObjectType`	Required	The GraphQL list type
`fields`	`dict`	`None`	Filter field configuration
`*args`	`Any`	-	Additional positional arguments
`deprecation_reason`	`str \\| None`	`None`	Renders `@deprecated(reason: ...)` on the compiled field
`**kwargs`	`Any`	-	Additional keyword arguments

Attributes¶

Attribute	Type	Description
`model`	`Model`	The Django model class
`fields`	`dict`	Filter field configuration
`filter_backend`	`object`	Native (`Q`-based) filter backend applied to the queryset
`filter_type`	`InputObjectType`	Generated `<Model>FilterInput` for the `filter:` argument

Methods¶

`list_resolver(manager, filter_backend, output_type, root, info, **kwargs)`¶

Resolve a list object with count and results.

Parameters: - manager (Manager): Django model manager - filter_backend (object): native filter backend; apply with filter_backend.apply(qs, kwargs.get("filter")) - output_type (type): the DjangoObjectType subclass for the list items (the DjangoListObjectType._meta.baseType), forwarded to queryset_factory so its get_queryset hook is applied - root (Any): Parent object - info (ResolveInfo): GraphQL resolve info - **kwargs: Query arguments including the filter value

Returns: DjangoListObjectBase with count and results

Example Usage¶

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

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

class Query(ObjectType):
    all_users = DjangoListObjectField(
        UserListType,
        description="All users with count and pagination"
    )

GraphQL Query¶

query GetUserList {
  allUsers {
    totalCount
    results(limit: 10, offset: 0) {
      id
      username
      email
    }
  }
}

For DjangoListObjectField, filter arguments are placed on the list field itself, while pagination and ordering arguments (limit, offset, page, pageSize, first, ordering, cursor arguments) are placed on the results(...) subfield. totalCount and pageInfo are siblings of results.

Response Structure¶

{
  "data": {
    "allUsers": {
      "totalCount": 150,
      "results": [
        {
          "id": "1",
          "username": "user1",
          "email": "user1@example.com"
        }
      ]
    }
  }
}

Field Configuration Examples¶

Basic Field Setup¶

from django_graphex.fields import DjangoObjectField, DjangoFilterListField, DjangoFilterPaginateListField, DjangoListObjectField
from django_graphex.core import ObjectType

class Query(ObjectType):
    # Single object
    user = DjangoObjectField(UserType)

    # Simple filtered list
    users = DjangoFilterListField(UserType)

    # Filtered and paginated list
    users_paginated = DjangoFilterPaginateListField(UserType)

    # List object with count
    all_users = DjangoListObjectField(UserListType)

Advanced Field Configuration¶

from django_graphex.core import ObjectType
from .paginations import CustomPagination

class Query(ObjectType):
    # Custom filtered list — `fields=` overrides the type's `filter_fields`
    staff_users = DjangoFilterListField(
        UserType,
        fields={"username": ("exact", "icontains"), "is_active": ("exact",)},
        description="Filtered list of staff users"
    )

    # Custom paginated list
    paginated_users = DjangoFilterPaginateListField(
        UserType,
        pagination=CustomPagination(default_limit=50),
        fields={"username": ("exact", "icontains"), "is_active": ("exact",)},
        description="Custom paginated user list"
    )

    # Custom resolver
    active_users = DjangoFilterListField(UserType)

    def resolve_active_users(self, info, **kwargs):
        return User.objects.filter(is_active=True)

Error Handling¶

from django_graphex.core import ObjectType

class Query(ObjectType):
    user = DjangoObjectField(UserType)

    def resolve_user(self, info, **kwargs):
        try:
            return User.objects.get(id=kwargs.get('id'))
        except User.DoesNotExist:
            return None  # Will return null in GraphQL response

Best Practices¶

Field Best Practices

Use Appropriate Fields: Choose the right field type for your use case
Add Descriptions: Always provide meaningful descriptions for your fields
Configure Filtering: Set up proper filter configurations for list fields
Handle Errors: Implement proper error handling in custom resolvers
Optimize Queries: Use select_related and prefetch_related for performance
Limit Results: Always configure reasonable pagination limits

Performance Optimization¶

class UserType(DjangoObjectType):
    class Meta:
        model = User

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

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

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

A prefetch declared here for a relation the optimizer also derives from the selection is replaced by the derived (narrowed, filtered) version rather than colliding with it; prefetches of other relations are kept. See Query Optimization.

get_queryset belongs on the node type, never on the list type

Note where the hook sits above: on UserType, not on UserListType. DjangoObjectType supports the hook; DjangoListObjectType does not, and a get_queryset declared on a list type is never called — silently, with no error and no warning.

The two are not distinguished by their base class — both subclass the same one. They are distinguished by a marker DjangoObjectType sets on itself and DjangoListObjectType does not. Every row-serving path funnels through one helper that checks for that marker and, when it is absent, hands the queryset back untouched. So the list type's hook is not overridden or shadowed: it is simply never looked up.

DjangoListObjectField resolves rows through the node type (DjangoListObjectType._meta.baseType, the DjangoObjectType registered for the same model), and that is the class whose hook runs.

This matters far beyond performance: the same hook is the row-level scoping hook (see Types → get_queryset). A tenant filter written on the list type leaks every row in the table, and totalCount counts them too.

To scope a list without touching the node type, set Meta.queryset on the list type instead — it replaces the default manager as the base queryset on every request.

This API reference provides comprehensive documentation for all field classes in django-graphex, enabling developers to effectively use and customize GraphQL fields for their Django applications.

Fields API Reference¶

Field descriptors¶

Field¶

Typed scalar shortcuts¶

DjangoObjectField¶

Parameters¶

Attributes¶

Methods¶

object_resolver(manager, output_type, root, info, **kwargs)¶

wrap_resolve(parent_resolver)¶

Example Usage¶

GraphQL Query¶

DjangoListField¶

Parameters¶

Properties¶

Example Usage¶

DjangoFilterListField¶

Parameters¶

Attributes¶

Methods¶

list_resolver(manager, filter_backend, custom_filters, output_type, root, info, **kwargs)¶

Example Usage¶

GraphQL Query¶

DjangoFilterPaginateListField¶

Parameters¶

Attributes¶

Methods¶

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

list_resolver(manager, filter_backend, root, info, **kwargs)¶

Example Usage¶

GraphQL Query¶

DjangoListObjectField¶

Parameters¶

Attributes¶

Methods¶

list_resolver(manager, filter_backend, output_type, root, info, **kwargs)¶

Example Usage¶

GraphQL Query¶

Response Structure¶

Field Configuration Examples¶

Basic Field Setup¶

Advanced Field Configuration¶

Error Handling¶

Best Practices¶

Performance Optimization¶

`Field`¶

`object_resolver(manager, output_type, root, info, **kwargs)`¶

`wrap_resolve(parent_resolver)`¶

`list_resolver(manager, filter_backend, custom_filters, output_type, root, info, **kwargs)`¶

`get_queryset(manager, root, info, **kwargs)`¶

`list_resolver(manager, filter_backend, root, info, **kwargs)`¶

`list_resolver(manager, filter_backend, output_type, root, info, **kwargs)`¶