Settings¶

All configuration lives under a single DJANGO_GRAPHEX dict in your Django settings. Every key is optional — unset keys fall back to the defaults below.

# settings.py
DJANGO_GRAPHEX = {
    # --- Pagination -------------------------------------------------------- #
    "DEFAULT_PAGINATION_CLASS": None,
    "DEFAULT_PAGE_SIZE": None,
    "MAX_PAGE_SIZE": None,

    # --- Response cache ---------------------------------------------------- #
    "CACHE_ACTIVE": False,
    "CACHE_TIMEOUT": 300,
    "CLEAN_RESPONSE": False,

    # --- Queryset optimization (N+1) --------------------------------------- #
    "OPTIMIZE_QUERYSET": True,
    "OPTIMIZE_ONLY_FIELDS": True,

    # --- Subscriptions ----------------------------------------------------- #
    "SUBSCRIPTION_SERIALIZE_DATA": False,

    # --- Security ---------------------------------------------------------- #
    "ALLOW_INTROSPECTION": False,
    "INTROSPECTION_ALLOW_SUPERUSER": True,
    "PROTECTED_FIELDS": (),

    # --- Query depth & cost ------------------------------------------------ #
    "MAX_QUERY_DEPTH": None,
    "MAX_QUERY_COST": None,
    "EXPOSE_QUERY_COST": False,
    "DEFAULT_LIST_MULTIPLIER": 10,
    "COST_PAGINATION_ARGS": ("limit", "page_size", "first", "last"),

    # --- Filtering --------------------------------------------------------- #
    "COMMON_FILTER_LOOKUPS": ("exact", "in", "isnull"),
}

Pagination¶

Setting	Default	Description
`DEFAULT_PAGINATION_CLASS`	`None`	Dotted path (or class) of the paginator applied to list fields that don't set one. `None` = no default pagination. See Pagination.
`DEFAULT_PAGE_SIZE`	`None`	Page size used when the client omits it. `None` = unbounded unless a paginator default applies.
`MAX_PAGE_SIZE`	`None`	Hard ceiling on the effective page size, applied even when no page-size argument is sent. `None` = no ceiling.

Response cache¶

Setting	Default	Description
`CACHE_ACTIVE`	`False`	Enable response caching in `GraphQLView`.
`CACHE_TIMEOUT`	`300`	Cache TTL in seconds.
`CLEAN_RESPONSE`	`False`	Strip `null` values from the response payload.

Queryset optimization (N+1)¶

Setting	Default	Description
`OPTIMIZE_QUERYSET`	`True`	Auto-apply `select_related` / `prefetch_related` derived from the query selection. See Query Optimization.
`OPTIMIZE_ONLY_FIELDS`	`True`	Also narrow columns with `.only()` across the `select_related` span. Set `False` if resolvers/properties read non-selected columns.

Subscriptions¶

Setting	Default	Description
`SUBSCRIPTION_SERIALIZE_DATA`	`False`	When `False`, change notifications carry only `{"id": <pk>}`; `True` serializes the full instance through the subscription's backend. Per-subscription override: `Meta.serialize_data`. See Subscriptions.

Security¶

Setting	Default	Description
`ALLOW_INTROSPECTION`	`False`	Allow `__schema` / `__type` introspection (`DisableIntrospectionMiddleware`).
`INTROSPECTION_ALLOW_SUPERUSER`	`True`	Let superusers bypass the introspection block.
`PROTECTED_FIELDS`	`()`	Top-level field names requiring auth via `AuthenticatedFieldsMiddleware` (when not using `ExtraGraphQLSchema`). See Security.

Query depth & cost¶

Setting	Default	Description
`MAX_QUERY_DEPTH`	`None`	Global max nested-object depth (`DepthLimitValidationRule`). `None` disables the global limit; per-type `Meta.max_deep` still applies.
`MAX_QUERY_COST`	`None`	Reject queries whose estimated cost exceeds this (`CostLimitValidationRule`). `None` disables the budget.
`EXPOSE_QUERY_COST`	`False`	Add `extensions.cost` (`requestedCost` / `maxCost`) to responses. Combine with `MAX_QUERY_COST=None` for a non-blocking observation mode.
`DEFAULT_LIST_MULTIPLIER`	`10`	Cost multiplier for a list field whose page size is unknown (no literal/variable value and no `MAX_PAGE_SIZE` cap).
`COST_PAGINATION_ARGS`	`("limit", "page_size", "first", "last")`	Argument names treated as a list's page size when costing a field.

See Query Optimization and Security for the depth/cost guides.

Filtering¶

Setting	Default	Description
`COMMON_FILTER_LOOKUPS`	`("exact", "in", "isnull")`	The common base lookup set every field receives when `Meta.filter_fields` declares it in list form. Text fields additionally get `icontains` / `istartswith`, and ordered (number/date/datetime) fields `gt` / `gte` / `lt` / `lte` / `range`. Dict-form declarations are explicit and ignore this. See Filtering.

How settings are read¶

DJANGO_GRAPHEX is read through a small self-contained reader (no DRF dependency). Changes are picked up automatically in tests via Django's setting_changed signal, so @override_settings(DJANGO_GRAPHEX={...}) works as expected. An unknown key raises AttributeError to catch typos early.