Skip to content

GraphQL Schema Modes & Context Injection

GraphQLBuilder compiles a GraphModel into an executable Strawberry GraphQL schema. You can control how node types are mapped onto the GraphQL schema using SchemaMode, and override the active graph per request using GraphQL execution context.

Schema Modes (SchemaMode)

1. Dynamic Mode (SchemaMode.DYNAMIC, Default)

In SchemaMode.DYNAMIC, GraphQLBuilder generates a dedicated GraphQL object type implementing GraphNode for each registered node type in the graph (for example, ServiceNode, EndpointNode), along with pluralized root query fields on Query (such as services, endpoints):

from graphinate import SchemaMode, model
from graphinate.builders import GraphQLBuilder

m = model(name='Architecture')


@m.node(type_='service')
def services():
    yield 'auth'


@m.node(type_='endpoint', parent_type='service')
def endpoints(service_id):
    yield f'{service_id}/login'


builder = GraphQLBuilder(m, mode=SchemaMode.DYNAMIC)
schema = builder.build()

result = schema.execute_sync('{ services { label neighbors { label } } }')

2. Static Mode (SchemaMode.STATIC)

In SchemaMode.STATIC, GraphQLBuilder uses a single GenericGraphNode type implementing GraphNode for all nodes and exposes a fixed root Query interface (graph, nodes, edges, measure). This mode is useful when node types are highly dynamic or when clients prefer a fixed GraphQL schema:

1
2
3
4
5
6
7
from graphinate import SchemaMode
from graphinate.builders import GraphQLBuilder

builder = GraphQLBuilder(m, mode=SchemaMode.STATIC)
schema = builder.build()

result = schema.execute_sync('{ nodes { type label neighbors { label } } }')

Dynamic Field Naming Strategies (DynamicFieldNaming)

When using SchemaMode.DYNAMIC, you can control how root query fields for dynamic node types are named using the dynamic_field_naming option on GraphQLBuilder:

  • DynamicFieldNaming.EXPLICIT (default): Preserves explicit snake_case field names (for example, git_commits, user_accounts). This guarantees full backward compatibility for existing client queries.
  • DynamicFieldNaming.AUTO: Delegates field naming to Strawberry's configuration. By default (auto_camel_case=True), field names are automatically converted to standard GraphQL camelCase (such as gitCommits, userAccounts).
from graphinate import DynamicFieldNaming, model
from graphinate.builders import GraphQLBuilder

m = model("VCS")


@m.node(type_="git_commit")
def commits():
    yield "c1"


# Idiomatic GraphQL camelCase root query fields
builder = GraphQLBuilder(m, dynamic_field_naming=DynamicFieldNaming.AUTO)
schema = builder.build()

result = schema.execute_sync("{ gitCommits { label } }")

Custom Strawberry Configuration

You can pass a custom strawberry.schema.config.StrawberryConfig to builder.build(config=...) or builder.schema(config=...) to customize casing, schema directives, or scalar mappings:

1
2
3
4
5
from strawberry.schema.config import StrawberryConfig

# Disable auto-camel-casing explicitly across the entire schema
config = StrawberryConfig(auto_camel_case=False)
schema = builder.build(config=config)

Context-Injected Graph Execution

By default, resolvers query the internal NetworkX graph built by GraphQLBuilder. You can also pass a custom nx.Graph at execution time via context_value={'graph': custom_graph} without rebuilding the strawberry.Schema:

1
2
3
4
5
6
7
8
9
from graphinate.builders import GraphQLBuilder, NetworkxBuilder

schema = GraphQLBuilder(m).build()
custom_graph = NetworkxBuilder(m).build()

result = schema.execute_sync(
    '{ graph { nodeCount edgeCount } nodes { label } }',
    context_value={'graph': custom_graph},
)