Settings🔗

Type: list[type[LifecycleHook]] | Default: []

Lifecycle hooks to use during GraphQL operations in addition to the built-in ones. Values should be given as the dotted paths to the lifecycle hooks used. Each hook runs at the point set by its priority, so the order of this list does not matter. See Lifecycle Hooks for more information.

Type: list[type[ASTValidationRule]] | Default: []

Additional validation rules to use for validating GraphQL documents (i.e. "requests"). Values should be given as the dotted paths to the validation rules used.

Type: bool | Default: False

Whether to allow the 'did you mean' suggestions on error messages. Disabled by default so that information on the schema structure cannot be gained from error messages when trying to find schema entrypoints through trial and error (a form of security through obscurity).

Automatically forced to False when a schema uses visibility.

Type bool | Default: False

Whether schema introspection queries are allowed or not. Disabled by default so that information on the schema structure cannot be gained through introspection (a form of security through obscurity).

Should set this to True if using GraphiQL.

Type: bool | Default: False

Whether queries can be executed over multipart/mixed HTTP requests.

Type: bool | Default: False

Whether queries can be executed over Server-Sent Events.

Type: bool | Default: False

Whether mutations can be executed over multipart/mixed HTTP requests.

Type: bool | Default: False

Whether mutations can be executed over Server-Sent Events.

Type: bool | Default: False

Whether queries can be executed over WebSockets.

Type: bool | Default: False

Whether mutations can be executed over WebSockets.

Type bool | Default: False

Whether to use async view for the GraphQL endpoint or not. See Undine's Async documentation for more information.

Type bool | Default: False

Whether to automatically generate Fields for QueryTypes, Inputs for MutationTypes, Filters for FilterSets, and Orders for OrderSets. Can also be set on an individual QueryType, MutationType, FilterSet, and OrderSet classes.

Type bool | Default: False

Whether clients can register persisted documents during the request phase using the APQ protocol. See automatic persisted queries for more information.

Type: str | Default: "undine_calculation_argument"

The key used to store a CalculationArgument in the extensions of its GraphQLArgument.

Type: bool | Default: True

Should field names be converted from 'snake_case' to 'camelCase' for the GraphQL schema? Conversion is not applied if schema_name is set manually in on the Entrypoint, Field, Input, etc.

Type: str | Default: "undine_connection"

The key used to store a Connection in the extensions of its GraphQLObjectType.

Type: str | Default: "undine"

The Datadog service name recorded on spans created by the Datadog lifecycle hooks. See Datadog for more information.

Type: Callable[[LifecycleHookContext], bool] | Default: "undine.integrations.datadog.skip_introspection_queries"

Function to use for checking if an operation should be recorded without its field spans. By default, introspection queries are recorded without them, since they resolve a field for every type and field in the schema. See Datadog for more information. Value should be given as the dotted path to the function.

Type: Callable[[Span, LifecycleHookContext], None] | Default: "undine.integrations.datadog.no_op_span_callback"

Function called with each span the Datadog lifecycle hook records so it can add its own tags to it. By default, no tags are added. See Datadog for more information. Value should be given as the dotted path to the function.

Type: Callable[[LifecycleHookContext], dict[str, Any]] | Default: "undine.integrations.datadog.redacted_variables"

Function that returns the GraphQL variables that are attached to Datadog operation spans. By default, the name of each variable is attached with its value redacted, since the values can contain sensitive data. See Datadog for more information. Value should be given as the dotted path to the function.

Type: str | Default: "undine_directive_argument"

The key used to store a DirectiveArgument in the extensions of its GraphQLArgument.

Type str | Default: "undine_directive"

The key used to store a Directive in the extensions of its GraphQLDirective.

Type bool | Default: False

Disable optimizing fetched fields with queryset.only().

Type type[DocstringParserProtocol] | Default: "undine.parsers.parse_docstring.RSTDocstringParser"

The docstring parser to use to parse function docstrings to schema descriptions. Should be given as the dotted path to the docstring parser class.

Type Container[Any] | Default: (None, "", [], {})

By default, if a Filter receives any of these values, that filter will be ignored. Can be changed on per-Filter basis using the empty_values argument.

Type bool | Default: False

Whether to parse class attribute docstrings or not. Disabled by default to improve performance of the schema creation.

Type int | Default: 0

How many seconds each Entrypoint of the Query root type can be cached for when it doesn't set its own cache_time. Set to 0 (default) to cache no Entrypoint unless it asks for it. See response caching for more information.

Type str | Default: "undine_entrypoint"

The key used to store an Entrypoint in the extensions of its GraphQLField.

Type: str | Default: "Unexpected error."

The message sent to the client in place of a masked error's own message. See ERROR_MASKING_PREDICATE for which errors are masked.

Type: Callable[[GraphQLError], bool] | Default: "undine.utils.graphql.utils.should_mask_error"

Function for checking whether an error should be masked before it's sent to the client. Value should be given as the dotted path to the function.

By default, only genuinely unexpected errors are masked. An error is unexpected when it comes from an exception that nobody raised for the client to see, like a RuntimeError from a resolver or a database error from a Django call.

Deliberate errors reach the client unchanged. An error is deliberate when it's a GraphQLError, whether you raised it yourself or Undine raised it for a server problem.

A masked error keeps its path, locations and status_code. Its message is replaced with ERROR_MASKING_MESSAGE, and all of its other extensions, like error_code, are removed.

A masked error never includes a traceback in the response, even if INCLUDE_ERROR_TRACEBACK is enabled.

Masking only affects the response. The original message and traceback are always logged to the undine logger.

To turn masking off, set this to "undine.utils.graphql.utils.never_mask_error".

Type type[UndineExecutionContext] | Default: "undine.execution.UndineExecutionContext"

GraphQL execution context class used by the schema. Should be given as the dotted path to the execution context class.

Type: bool | Default: False

Whether to enable experimental support for incremental delivery over HTTP.

Type: str | Default: "undine_federation_builtin"

Marker key set to True on the extensions of Apollo Federation builtin scalars and types.

Type: str | Default: "undine_federation_field"

The key used to store a FederationField in the extensions of its GraphQLField.

Type: str | Default: "undine_federation_min_version"

The key on the extensions of a builtin federation Directive that records the minimum FEDERATION_VERSION at which the directive is available. Used by create_federation_schema to reject directives applied on subgraphs pinned to an older federation version.

Type: str | Default: "undine_federation_sdl"

The key on schema extensions where the pre-computed federation SDL string is cached by create_federation_schema. The _service resolver reads from this key.

Type: str | Default: "undine_federation_type"

The key used to store a FederationType in the extensions of its GraphQLObjectType.

Type: str | Default: "2.15"

The Apollo Federation 2 spec version used by create_federation_schema. Must be one of "2.0" through "2.15".

Type: str | Default: "undine_field"

The key used to store a Field in the extensions of its GraphQLField.

Type: bool | Default: False

Whether file uploads are enabled. Should enable CSRF protection on the GraphiQL endpoint if enabled. See file uploads for more information.

Type: str | Default: "undine_filter"

The key used to store a Filter in the extensions of its GraphQLInputField.

Type: str | Default: "undine_filterset"

The key used to store a FilterSet in the extensions of its GraphQLInputObjectType.

Type: bool | Default: False

Whether to enable GraphiQL. Should also set ALLOW_INTROSPECTION_QUERIES to True, so that GraphiQL can introspect the GraphQL schema.

Type: bool | Default: False

Whether GraphiQL uses SSE for subscriptions instead of the built-in WebSocket client.

Type: bool | Default: False

Controls whether the SSE subscription client uses single connection mode. Only relevant when GRAPHIQL_SSE_ENABLED is enabled.

Type: str | Default: "graphql/"

The URL path where the GraphQL endpoint is located if it's included using path("", include("undine.http.urls")).

Type: str | Default: "graphql"

The name given to the GraphQL view in Django's URL resolvers if it's included using path("", include("undine.http.urls")).

Type: bool | Default: False

When a GraphQL request returns an error response, and the error is based on a non-GraphQL exception, if this setting is enabled, the error traceback will be included in the response. Useful for debugging.

Masked errors never include a traceback in the response. Turn masking off with ERROR_MASKING_PREDICATE to see tracebacks for server errors.

Type: int | Default: 0

Interval in seconds for incremental delivery over HTTP heartbeats. Set to 0 to disable.

Heartbeats are disabled by default, since they are not part of the incremental delivery over HTTP specification, and clients are not required to handle them.

Type: str | Default: "undine_input"

The key used to store an Input in the extensions of its GraphQLInputField.

Type: str | Default: "undine_interface_field"

The key used to store an InterfaceField in the extensions of its GraphQLField.

Type: str | Default: "undine_interface"

The key used to store a InterfaceType in the extensions of its GraphQLInterfaceType.

Type int | None | Default: None

Maximum number of objects that can be returned from a list Entrypoint when not using pagination. If None, all items are fetched.

Type: int | Default: 15

The maximum number of aliases allowed in a single operation.

Type: int | Default: 50

The maximum number of directives allowed in a single operation.

Type: int | Default: 100

The maximum number of validation errors allowed in a GraphQL request before it's rejected, even if validation is still not complete.

Type: int | Default: 20

The maximum number of filters allowed to be used for filtering a single QueryType.

Type: int | Default: 5

The maximum number of to-many relations that can be nested inside one another in a single operation. Only to-many relations count towards this limit, since to-one relations don't multiply the number of rows returned by the operation. See the MaxListNestingDepthRule documentation for more information.

Type: int | Default: 10

The maximum number of orderings allowed to be used for ordering a single QueryType.

Type: int | Default: 10

Maximum query complexity that is allowed to be queried in a single operation. See the field complexity documentation for more information.

Type int | Default: None

Maximum number of GraphQL document tokens the GraphQL parser will parse before it rejects a request. By default, this is set to None which means no limit.

Type: bool | Default: False

Whether to add translatable fields to the GraphQL schema when using django-modeltranslation. See the integration description for more information.

Type: bool | Default: True

Whether to add translation fields to the GraphQL schema when using django-modeltranslation. See the integration description for more information.

Type: int | Default: 12

Interval in seconds for multipart/mixed HTTP heartbeats. Set to 0 to disable.

Type: bool | Default: True

Whether to run model.full_clean() when creating or updating Model using MutationTypes. Turning this off can reduce the number of database queries during mutations, but may introduce issues that would be solved by running full Model validation.

Type: int | Default: 100

The maximum number of Model instances that can be mutated in a single request.

The limit is shared by every mutation in the request, and counts nested related objects and many-to-many through rows as well. See mutation instance limit.

Type: str | Default: "input"

The key that the input argument based on a MutationType is added to when said MutationType is used in Entrypoints.

Type: str | None | Default: None

Dotted module path where the test_generate_mutation_input_types management command writes the generated TypedDicts for each MutationType.__input_map__. For example, "myproj.gql_input_types" writes to myproj/gql_input_types.py.

The setting is a write target only; it is not imported at runtime. Set it to a module path under one of your Python packages before running the management command.

Type: str | Default: "undine_mutation_type"

The key used to store a MutationType in the extensions of its GraphQLInputObjectType.

Type: bool | Default: False

Whether to remove error location information to GraphQL errors.

Type: str | Default: "undine_offset_pagination"

The key used to store an OffsetPagination in the extensions of its GraphQLObjectType.

Type: Callable[[LifecycleHookContext], bool] | Default: "undine.integrations.opentelemetry.skip_introspection_queries"

Function to use for checking if an operation should be recorded without its field spans. By default, introspection queries are recorded without them, since they resolve a field for every type and field in the schema. See OpenTelemetry for more information. Value should be given as the dotted path to the function.

Type: Callable[[Span, LifecycleHookContext], None] | Default: "undine.integrations.opentelemetry.no_op_span_callback"

Function called with each span the OpenTelemetry lifecycle hook records so it can add its own attributes to it. By default, no attributes are added. See OpenTelemetry for more information. Value should be given as the dotted path to the function.

Type: Callable[[LifecycleHookContext], dict[str, Any]] | Default: "undine.integrations.opentelemetry.redacted_variables"

Function that returns the GraphQL variables that are attached to OpenTelemetry operation spans. By default, the name of each variable is attached with its value redacted, since the values can contain sensitive data. See OpenTelemetry for more information. Value should be given as the dotted path to the function.

Type: type[QueryOptimizer] | Default: "undine.optimizer.optimizer.QueryOptimizer"

The optimizer class to use for optimizing queries. Value should be given as the dotted path to the optimizer class.

Type: str | Default: "undine_order"

The key used to store an Order in the extensions of its GraphQLEnumValue.

Type: str | Default: "undine_orderset"

The key used to store a OrderSet in the extensions of its GraphQLEnumType.

Type: str | Default: "_undine_pagination_index"

The key to which a nested pagination indexes are annotated to.

Type: str | Default: "_undine_pagination_ordering"

The key prefix to which cursor pagination annotates the ordering values that are not plain columns, so that they are available for building cursors.

Type: int | Default: 100

The maximum number of items to return from a page when paginating.

Type: str | Default: "_undine_pagination_start"

The key to which a nested pagination start indexes are annotated to.

Type: str | Default: "_undine_pagination_stop"

The key to which a nested pagination stop indexes are annotated to.

Type: str | Default: "_undine_pagination_total_count"

The key to which a nested pagination total counts are annotated to.

Type: int | Default: 0

How many parsed documents the undine.hooks.ParseCacheHook keeps in the memory of the process. Set to 0 (default) to disable the cache. See document caching for more information.

Type: bool | Default: False

Whether to only allow persisted documents to be executed in the GraphQL API.

Type: str | Default: "persisted-documents/"

The path where the persisted documents registration endpoint is located by default.

Type: PersistedDocumentsPermissionsCallback | Default: undine.persisted_documents.utils.default_permission_callback

The function to use for permission checks for registration of persisted documents.

Type: str | Default: "persisted_documents"

The name of given to the persisted documents registration view in the URLconf.

Type: str | Default: "_undine_ts_vector"

A prefix to use for the filter aliases of postgres full text search Filters.

Type: str | Default: "_undine_prefetch_hack_cache"

The key to use for storing the prefetch hack cache in the queryset hints.

Type: str | Default: "undine_query_type"

The key used to store a QueryType in the extensions of its GraphQLObjectType.

Type: str | Default: "filter"

The name of the input argument that is created for a FilterSet when a QueryType using that FilterSet is used in a list Entrypoint or many-related Field.

Type: str | Default: "orderBy"

The name of the input argument that is created for an OrderSet when a QueryType using that OrderSet is used in a list Entrypoint or many-related Field.

Type: str | Default: "undine_request_cache_active"

The key on schema.extensions set to True when the schema has an Entrypoint that can be cached. Used internally to install the undine.hooks.RequestCacheHook only for the schemas that need it.

Type: str | Default: "default"

The cache alias to use for caching requests using the @cache directive.

Type: Callable[[LifecycleHookContext], dict[str, Any]] | Default: "undine.hooks.default_extra_context"

Function to use for extra context to add to the cache key. Value should be given as the dotted paths to the function.

Type: Callable[[LifecycleHookContext], bool] | Default: "undine.hooks.should_read_from_cache"

Function to use for checking if the result should be read from cache. Value should be given as the dotted paths to the function.

Type: Callable[[LifecycleHookContext], bool] | Default: "undine.hooks.should_write_to_cache"

Function to use for checking if the result should be written to cache. Value should be given as the dotted paths to the function.

Type: str | Default: "undine-cache"

The prefix to use for the cache keys when caching requests using the @cache directive.

Type: str | Default: "root"

The name of the root/parent parameter in Field/Entrypoint resolvers.

Type: str | Default: "undine_root_type"

The key used to store a RootType in the extensions of its GraphQLObjectType.

Type: Any | Default: None

The root value for the GraphQL execution. Can be accessed by Entrypoint resolvers from the root argument.

Type: str | Default: "undine_scalar"

The key used to store a Undine ScalarType in the extensions of its GraphQLScalarType.

Type: GraphQLSchema | Default: "undine.settings.example_schema"

The file and variable where the GraphQL Schema for Undine is located. Value should be given as the dotted path, usually created using undine.schema.create_schema.

Type: str | Default: "undine_schema_directives"

The key used to store the schema definition directives in the extensions of its GraphQLSchema.

Type: type[SDLPrinter] | Default: "undine.utils.graphql.sdl_printer.SDLPrinter"

The SDL printer to use. Value should be given as the dotted path to the SDL printer class.

Type: Callable[[GraphQLError], bool] | Default: "undine.integrations.sentry.report_server_errors"

Function to use for checking if a GraphQL error should be reported to Sentry as an issue. By default, only errors that indicate a fault in the server are reported. See Sentry for more information. Value should be given as the dotted path to the function.

Type: Callable[[LifecycleHookContext], bool] | Default: "undine.integrations.sentry.skip_introspection_queries"

Function to use for checking if an operation should be recorded without its field spans. By default, introspection queries are recorded without them, since they resolve a field for every type and field in the schema. See Sentry for more information. Value should be given as the dotted path to the function.

Type: Callable[[RecordedSpan, LifecycleHookContext], None] | Default: "undine.integrations.sentry.no_op_span_callback"

Function called with each span the Sentry lifecycle hook records so it can add its own attributes to it. By default, no attributes are added. See Sentry for more information. Value should be given as the dotted path to the function.

Type: Callable[[LifecycleHookContext], dict[str, Any]] | Default: "undine.integrations.sentry.redacted_variables"

Function that returns the GraphQL variables that are attached to Sentry operation spans. By default, the name of each variable is attached with its value redacted, since the values can contain sensitive data. See Sentry for more information. Value should be given as the dotted path to the function.

Type: int | Default: 12

Interval in seconds for SSE keep-alive pings sent on the event stream. These pings prevent reverse proxies and load balancers from closing idle connections. Set to 0 to disable.

Type: int | Default: 30

Timeout in seconds for an operation to wait for the event stream to open (Single Connection mode).

Type: str | Default: "graphql-over-sse-stream"

Key prefix used to store the GraphQL over SSE stream state in the user's session (Single Connection mode).

Type: str | Default: "X-GraphQL-Event-Stream-Token"

The name of the HTTP header to use for the GraphQL over SSE event stream token (Single Connection mode).

Type: str | Default: "token"

The name of the query string parameter to use for the GraphQL over SSE event stream token (Single Connection mode).

Type: type[SubscriptionBroker] | Default: "undine.brokers.InMemorySubscriptionBroker"

The broker that signal subscriptions publish their events to and receive them from. Value should be given as the dotted path to the broker class. The default broker delivers events within a single process. See Brokers for the alternatives.

Type: bool | Default: False

Whether to include the full stacktrace in testing client instead of just the relevant frames when checking where SQL queries are made.

Type: bool | Default: False

Whether to disable the websocket timeouts in testing client. Can be useful in debugging.

Type: str | Default: "totalCount"

The name of the parameter in a connection ObjectType for holding the count for the total number of items that can be queried from the connection.

Type: type[Model] | Default: "undine.persisted_documents.models.PersistedDocument"

NOTE: This setting should be set in the top level of the settings file, not in the UNDINE dictionary!

The model to use for the PersistedDocument model. Works similarly to AUTH_USER_MODEL, so must be set before running migrations for the persisted documents app.

Type: str | Default: "undine_union_type"

The key used to store a Undine UnionType in the extensions of its GraphQLUnion.

Type: bool | Default: False

Whether Server-Sent Events should use distinct connections mode even with a HTTP/1.1 connection. Note that when using HTTP/1.1, the maximum number of open connections is limited to 6 per domain and browser. That means you will likely hit the limit in a real production environment with multiple requests and browser tabs.

Type: int | Default: 0

How many validated documents the undine.hooks.ValidationCacheHook keeps in the memory of the process. Set to 0 (default) to disable the cache. See document caching for more information.

Type: str | Default: "undine_visibility_active"

The key on schema.extensions set to True when visibility is detected in the schema. Used internally to install the visibility validation rule per schema; you rarely need to read it yourself.

Type: str | Default: "default"

The cache alias to use for visibility caching.

Type: Callable[[DjangoRequestProtocol], Any] | Default: "undine.utils.visibility.default_visibility_extra_context"

Function returning any JSON-serialisable extra context added to the cross-request visibility cache key. Use this when per-user visibility depends on more than the user primary key (for example a tenant identifier or group membership).

Type: str | Default: "undine_visibility"

Prefix used for the cross-request visibility cache keys.

Type: int | Default: 0

How many seconds to cache the filtered introspection payload per user context. Set to 0 (default) to disable cross-request caching; the per-request visibility memoization still runs.

Type: str | Default: "_undine_visibility_memo"

The attribute on the request where visibility check results are memoized for the duration of the request. This is separate from the cross-request visibility cache.

Type: WebSocketConnectionInitHook | Default: "undine.utils.graphql.websocket.connection_init_hook"

The function to use for custom ConnectionInit logic. Value should be given as the dotted path to the function.

Type: int | Default: 3

The number of seconds to wait for the ConnectionInit message after opening a WebSocket before closing it.

Type: str | Default: "graphql/"

The path where the GraphQL over WebSocket endpoint is located if using undine.integrations.channels.get_websocket_enabled_app.

Type: WebSocketConnectionPingHook | Default: "undine.utils.graphql.websocket.ping_hook"

The function for specifying custom Ping message logic. Value should be given as the dotted path to the function.

Type: WebSocketConnectionPongHook | Default: "undine.utils.graphql.websocket.pong_hook"

The function to for specifying custom Pong message logic. Value should be given as the dotted path to the function.