GraphQLHandler API

Core entry point for GraphQL mode — generate SDL, execute queries, and integrate GraphiQL.

GraphQLHandler

Create a handler to manage GraphQL schema generation and query execution.

from nexusx import GraphQLHandler

handler = GraphQLHandler(
    base=SQLModel,                    # SQLModel base class (auto-discover entities)
    session_factory=async_session,    # Async session factory (required)
    enable_pagination=False,          # Enable list relationship pagination
    auto_query_config=None,           # AutoQueryConfig for auto queries
)

Parameters

Parameter	Type	Default	Description
base	type	—	SQLModel base class for auto-discovering entities
session_factory	Callable	—	Async session factory function
enable_pagination	bool	False	Enable list relationship pagination
auto_query_config	AutoQueryConfig	None	Auto query configuration

Warning

You must provide session_factory — without it, DataLoader cannot load relationship data and queries will fail.

Tip

Enable auto_query_config to automatically generate by_id and by_filter queries for all your entities. This is especially useful during development and for CRUD operations.

Methods

Method	Signature	Description
execute	async execute(query: str, context: dict = None) -> dict	Execute a GraphQL query
get_graphiql_html	get_graphiql_html(endpoint: str = "/graphql") -> str	Get GraphiQL HTML

@query Decorator

Mark a method as a GraphQL query field.

from nexusx import query

class Post(SQLModel, table=True):
    @query
    async def get_all(cls, limit: int = 10) -> list['Post']:
        """Get all posts."""
        ...

• The decorator automatically converts the method to a classmethod
• The docstring becomes the GraphQL field description
• The first parameter must be cls
• query_meta parameters do not appear in the SDL

@mutation Decorator

Mark a method as a GraphQL mutation field.

from nexusx import mutation

class Post(SQLModel, table=True):
    @mutation
    async def create(cls, title: str, author_id: int) -> 'Post':
        """Create a new post."""
        ...

Follows the same rules as @query.

AutoQueryConfig

Configure automatic query generation for standard CRUD operations.

from nexusx import AutoQueryConfig

config = AutoQueryConfig(session_factory=async_session)

Auto-generates by_id and by_filter queries for all entities. Requires entities to have exactly one primary key field.

Tip

Use AutoQueryConfig when you want quick CRUD access without manually writing @query methods for each entity. You can always add custom queries alongside the auto-generated ones.

QueryParser

Parse GraphQL query strings into FieldSelection trees. Typically not used directly — the handler invokes this automatically during query execution.

FieldSelection

Represents a field and its sub-selections in a GraphQL selection set. This is the output type from QueryParser and is used internally during query execution.

add_standard_queries

Manually register auto queries to an existing GraphQLHandler.

from nexusx import add_standard_queries

add_standard_queries(handler, AutoQueryConfig(session_factory=async_session))

Use this when you want to add standard CRUD queries to a handler that was created without auto_query_config.