GraphQL Configuration

Complete configuration reference for GraphQL API in HeliosDB.

Server Configuration

Basic Settings

[graphql]
# Enable GraphQL API
enabled = true

# GraphQL endpoint path
path = "/graphql"

# Enable GraphQL Playground
playground_enabled = true

# Playground path
playground_path = "/graphql"

# Enable introspection
introspection_enabled = true

# Maximum query depth
max_depth = 10

# Maximum query complexity
max_complexity = 1000

Schema Generation

[graphql.schema]
# Auto-generate schema from database
auto_generate = true

# Tables to include (empty = all)
include_tables = []

# Tables to exclude
exclude_tables = ["_migrations", "_audit_log"]

# Generate mutations (insert, update, delete)
generate_mutations = true

# Generate subscriptions
generate_subscriptions = true

# Use relay-style connections
use_relay_connections = true

# Add aggregation fields
add_aggregations = true

Authentication

[graphql.auth]
# Authentication method
method = "bearer"

# Require authentication for all queries
require_auth = true

# Public queries (no auth required)
public_queries = ["__schema", "__type"]

# Role-based access
enable_rbac = true

# Default role for unauthenticated requests
default_role = "anonymous"

Performance

[graphql.performance]
# Enable query batching
batching_enabled = true

# Maximum batch size
max_batch_size = 10

# Enable DataLoader for N+1 prevention
dataloader_enabled = true

# Query result cache TTL (seconds)
cache_ttl = 60

# Enable persistent queries
persistent_queries_enabled = true

# Tracing (for Apollo Studio)
tracing_enabled = true

Subscriptions

[graphql.subscriptions]
# Enable subscriptions
enabled = true

# WebSocket path
websocket_path = "/graphql/ws"

# Keep-alive interval (seconds)
keepalive_interval = 30

# Connection timeout (seconds)
connection_timeout = 300

# Maximum subscriptions per connection
max_subscriptions_per_connection = 10

Federation

[graphql.federation]
# Enable Apollo Federation
enabled = false

# Federation version (1 or 2)
version = 2

# Service name
service_name = "heliosdb"

# Enable @key directive
enable_key_directive = true

Environment Variables

Variable	Description	Default
HELIOSDB_GRAPHQL_ENABLED	Enable GraphQL	true
HELIOSDB_GRAPHQL_PATH	Endpoint path	/graphql
HELIOSDB_GRAPHQL_PLAYGROUND	Enable playground	true
HELIOSDB_GRAPHQL_INTROSPECTION	Enable introspection	true
HELIOSDB_GRAPHQL_MAX_DEPTH	Max query depth	10
HELIOSDB_GRAPHQL_MAX_COMPLEXITY	Max complexity	1000

Query Complexity Rules

Configure query complexity weights:

[graphql.complexity]
# Base cost per field
field_cost = 1

# Cost per connection
connection_cost = 5

# Cost multiplier for lists
list_multiplier = 2

# Custom field costs
[graphql.complexity.fields]
"User.orders" = 10
"Order.items" = 5
"Query.analytics" = 50

Rate Limiting

[graphql.rate_limit]
# Enable rate limiting
enabled = true

# Queries per minute
queries_per_minute = 100

# Mutations per minute
mutations_per_minute = 50

# Subscriptions per connection
subscriptions_per_connection = 10

# Complexity budget per minute
complexity_per_minute = 10000

Custom Scalars

[graphql.scalars]
# Enable custom scalar types
DateTime = true
JSON = true
UUID = true
BigInt = true
Decimal = true
Upload = true

Error Handling

[graphql.errors]
# Include stack traces (development only)
include_stack_trace = false

# Include internal error details
include_internal_details = false

# Log errors
log_errors = true

# Error format (graphql-spec, apollo)
format = "graphql-spec"

---

Last Updated: January 2026