HeliosDB GraphQL - Quick Reference

HeliosDB GraphQL - Quick Reference

Server Setup

use heliosdb_graphql::{GraphQLServer, GraphQLConfigBuilder};

let config = GraphQLConfigBuilder::new()
    .bind_address("0.0.0.0:8080".parse()?)
    .playground(true)
    .build();

let server = GraphQLServer::new(config).await?;
server.run().await?.wait().await?;

Query Examples

Basic Query

query {
  users {
    id
    name
    email
  }
}

With Filtering

query {
  users(where: {
    email: { contains: "@example.com" }
  }) {
    id
    name
  }
}

With Pagination

query {
  users(skip: 10, take: 5) {
    id
    name
  }
}

With Sorting

query {
  users(orderBy: [{ createdAt: DESC }]) {
    id
    name
    createdAt
  }
}

Mutation Examples

Create

mutation {
  createUser(data: {
    name: "Alice"
    email: "alice@example.com"
  }) {
    id
    name
  }
}

Update

mutation {
  updateUser(id: "1", data: { name: "Bob" }) {
    id
    name
  }
}

Delete

mutation {
  deleteUser(id: "1") {
    id
  }
}

Subscription Examples

Listen to Creates

subscription {
  userCreated {
    id
    name
    email
  }
}

Listen to Updates

subscription {
  userUpdated {
    id
    name
  }
}

Filter Operators

Operator	Description	Example
equals	Exact match	{ name: { equals: "Alice" } }
not	Not equal	{ status: { not: "inactive" } }
in	In array	{ status: { in: ["active", "pending"] } }
notIn	Not in array	{ status: { notIn: ["deleted"] } }
contains	String contains	{ email: { contains: "@example" } }
startsWith	String starts with	{ name: { startsWith: "A" } }
endsWith	String ends with	{ email: { endsWith: ".com" } }
lt	Less than	{ age: { lt: 18 } }
lte	Less than or equal	{ age: { lte: 65 } }
gt	Greater than	{ price: { gt: 100 } }
gte	Greater than or equal	{ price: { gte: 50 } }

Logical Operators

# AND
query {
  users(where: {
    AND: [
      { status: { equals: "active" } }
      { age: { gte: 18 } }
    ]
  }) {
    id
    name
  }
}

# OR
query {
  users(where: {
    OR: [
      { status: { equals: "premium" } }
      { age: { gte: 65 } }
    ]
  }) {
    id
    name
  }
}

# NOT
query {
  users(where: {
    NOT: { status: { equals: "deleted" } }
  }) {
    id
    name
  }
}

Authentication

// Generate token
use heliosdb_graphql::auth::{TokenManager, Claims};

let manager = TokenManager::new("secret".to_string());
let claims = Claims::new("user123".to_string(), vec!["admin".to_string()], 3600);
let token = manager.generate_token(claims)?;

HTTP Header:

Authorization: Bearer <token>

Configuration Options

GraphQLConfigBuilder::new()
    .bind_address(addr)           // Server address
    .playground(true)             // Enable playground UI
    .introspection(true)          // Enable introspection
    .max_depth(10)                // Max query depth
    .max_complexity(100)          // Max query complexity
    .subscriptions(true)          // Enable subscriptions
    .federation(false)            // Enable federation
    .rate_limit(1000)             // Requests per minute
    .jwt_secret(secret)           // JWT secret
    .log_queries(true)            // Log all queries
    .build()

Type System

SQL	GraphQL
VARCHAR	String
INTEGER	Int
BIGINT	String
FLOAT	Float
DECIMAL	Decimal
BOOLEAN	Boolean
UUID	UUID
JSON	JSON
TIMESTAMP	DateTime

Error Handling

use heliosdb_graphql::error::GraphQLError;

match result {
    Ok(data) => { /* success */ }
    Err(GraphQLError::Authentication(msg)) => { /* auth error */ }
    Err(GraphQLError::QueryExecution(msg)) => { /* query error */ }
    Err(e) => { /* other errors */ }
}

Federation

use heliosdb_graphql::federation::FederationSupport;

let federation = FederationSupport::new();
let resolver = Arc::new(TableEntityResolver::new("users".to_string()));
federation.register_resolver("User".to_string(), resolver).await;

Metrics

Prometheus metrics are automatically exported:

• heliosdb_graphql_requests_total - Total requests
• heliosdb_graphql_query_duration_seconds - Query duration
• heliosdb_graphql_errors_total - Total errors
• heliosdb_graphql_subscriptions_active - Active subscriptions

Endpoints

• POST /graphql - GraphQL queries and mutations
• GET / - GraphQL Playground (if enabled)
• GET /ws - WebSocket for subscriptions
• GET /health - Health check

Best Practices

1. Use pagination for large result sets
2. Limit query depth to prevent abuse
3. Enable rate limiting in production
4. Use authentication for sensitive data
5. Monitor query complexity and slow queries
6. Cache frequently accessed data
7. Use subscriptions for real-time features
8. Implement proper error handling
9. Enable query logging for debugging
10. Test with GraphQL Playground during development