---
title: "GraphQL Configuration"
---

# GraphQL Configuration

:::caution[Planned: not in the current release]
A GraphQL API for HeliosDB Full is planned. The current release opens no GraphQL listener. Reach
the same data over the PostgreSQL listener or `POST /api/v1/query` today. This page
describes the planned interface.
:::

Complete configuration reference for GraphQL API in HeliosDB.

## Server Configuration

### Basic Settings

```toml
[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

```toml
[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

```toml
[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

```toml
[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

```toml
[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

```toml
[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:

```toml
[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

```toml
[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

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

## Error Handling

```toml
[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"
```

---