GigaBrain Graph Database#

GigaBrain is a high-performance, in-memory graph database written in Rust, designed for efficient graph operations, complex queries, and real-time analytics.

Features#

• High Performance: In-memory storage with optimized data structures
• Cypher Query Language: Full support for Neo4j-compatible Cypher queries
• Interactive CLI: Comprehensive command-line interface with REPL and batch processing
• Graph Algorithms: Built-in shortest path, centrality, community detection, and more
• Dual API: Both REST and gRPC interfaces for maximum flexibility
• ACID Transactions: Full transaction support with configurable isolation levels
• Persistence: Optional RocksDB backend for data durability
• Authentication: JWT-based authentication with role-based access control
• Monitoring: Built-in metrics and observability features
• Data Import/Export: JSON and CSV import/export capabilities

Quick Start#

Installation#

git clone https://github.com/your-org/gigabrain.git
cd gigabrain
cargo build --release

Running the Server#

# Start both REST (port 3000) and gRPC (port 50051) servers
cargo run --bin gigabrain

Using the CLI#

# Build and start the interactive CLI
cargo build --release --bin gigabrain-cli
./target/release/gigabrain-cli

# Execute a single command
./target/release/gigabrain-cli --execute "CREATE (alice:Person {name: 'Alice', age: 30})"

# Run commands from file
./target/release/gigabrain-cli --file my_queries.cypher

# Show graph statistics
./target/release/gigabrain-cli stats

Basic Usage#

Using the CLI (Recommended)#

# Start interactive CLI
gigabrain> CREATE (alice:Person {name: 'Alice', age: 30})
gigabrain> CREATE (bob:Person {name: 'Bob', age: 25})
gigabrain> MATCH (a:Person), (b:Person) WHERE a.name = 'Alice' AND b.name = 'Bob'
        -> CREATE (a)-[:KNOWS]->(b)
gigabrain> MATCH (p:Person)-[:KNOWS]->(friend) RETURN p.name, friend.name

Using the REST API#

# Check server health
curl http://localhost:3000/api/v1/health

# Create a node
curl -X POST http://localhost:3000/api/v1/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "labels": ["Person"],
    "properties": [
      {"key": "name", "value": {"string_value": "Alice"}},
      {"key": "age", "value": {"int_value": 30}}
    ]
  }'

# Execute a Cypher query
curl -X POST http://localhost:3000/api/v1/cypher \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MATCH (n:Person) RETURN n.name, n.age"
  }'

Architecture#

Core Components#

• Graph Engine: High-performance graph storage and traversal
• Query Engine: Cypher parser and execution engine
• CLI Interface: Interactive REPL and command-line tools
• Algorithm Library: Graph algorithms for analytics
• API Layer: REST and gRPC interfaces
• Storage Layer: Memory and persistent storage backends
• Transaction Manager: ACID transaction support
• Observability: Metrics, tracing, and health monitoring

Performance#

• Node Operations: 1M+ operations/second
• Relationship Traversal: Sub-millisecond response times
• Cypher Queries: Optimized execution plans
• Memory Usage: Efficient memory layout with minimal overhead
• Concurrent Access: Lock-free data structures where possible

Use Cases#

Social Networks#

• Friend recommendations
• Community detection
• Influence analysis
• Content propagation modeling

Fraud Detection#

• Pattern recognition
• Anomaly detection
• Risk scoring
• Network analysis

Knowledge Graphs#

• Semantic search
• Recommendation engines
• Data lineage tracking
• Relationship discovery

Supply Chain#

• Route optimization
• Dependency analysis
• Impact assessment
• Bottleneck identification

Configuration#

CLI Configuration#

# ~/.gigabrain/config.toml
[cli]
prompt = "gigabrain> "
history_file = "~/.gigabrain/history"
max_history = 2000
output_format = "table"
show_timing = true
enable_completion = true

[connection]
rest_endpoint = "http://localhost:3000"
grpc_endpoint = "http://localhost:50051"
timeout = 30

Server Configuration#

ServerConfig {
    rest_port: 3000,
    grpc_port: 50051,
    max_connections: 1000,
    request_timeout: Duration::from_secs(30),
    enable_cors: true,
    jwt_secret: "your-secret-key",
}

Storage Configuration#

// In-memory storage (default)
let storage = MemoryStore::new();

// Persistent storage with RocksDB
let storage = RocksDBStore::new("./data")?;

Authentication#

// Generate JWT token
let auth_service = AuthService::new("secret-key");
let token = auth_service.generate_token("user123", "ReadWrite", 24)?;

// Validate token
let claims = auth_service.validate_token(&token)?;

Documentation#

• CLI and REPL Guide - Complete command-line interface documentation
• API Reference - REST and gRPC API documentation
• Architecture Guide - Technical architecture overview
• gRPC Protocol Buffers - Protocol buffer definitions
• Examples - Usage examples and tutorials

Benchmarks#

Performance benchmarks on a 16-core machine with 32GB RAM:

Development#

Building#

# Debug build
cargo build

# Release build
cargo build --release

# With RocksDB support
cargo build --features rocksdb-storage

Testing#

# Run all tests
cargo test

# Run with RocksDB features
cargo test --features rocksdb-storage

# Property-based testing
cargo test --test property_tests

# Benchmarks
cargo bench

Contributing#

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Code Style#

• Follow Rust standard formatting (cargo fmt)
• Use cargo clippy for linting
• Write comprehensive tests
• Document public APIs

Deployment#

Docker#

FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/gigabrain /usr/local/bin/
EXPOSE 3000 50051
CMD ["gigabrain"]

Kubernetes#

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gigabrain
spec:
  replicas: 3
  selector:
    matchLabels:
      app: gigabrain
  template:
    metadata:
      labels:
        app: gigabrain
    spec:
      containers:
      - name: gigabrain
        image: gigabrain:latest
        ports:
        - containerPort: 3000
        - containerPort: 50051
        env:
        - name: JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: gigabrain-secrets
              key: jwt-secret

Production Considerations#

• High Availability: Deploy multiple instances with load balancing
• Backup Strategy: Regular snapshots for persistent storage
• Monitoring: Use Prometheus metrics and distributed tracing
• Security: Enable TLS, rotate JWT secrets regularly
• Resource Limits: Configure memory and CPU limits appropriately

Monitoring and Observability#

Metrics#

GigaBrain exposes Prometheus-compatible metrics:

# Node and relationship counts
gigabrain_nodes_total
gigabrain_relationships_total

# Query performance
gigabrain_query_duration_seconds
gigabrain_query_errors_total

# API performance
gigabrain_http_requests_total
gigabrain_grpc_requests_total

# System resources
gigabrain_memory_usage_bytes
gigabrain_cpu_usage_percent

Logging#

Structured logging with multiple levels:

use tracing::{info, warn, error};

info!(node_id = %node.id, "Node created successfully");
warn!(query = %cypher, duration_ms = %elapsed, "Slow query detected");
error!(error = %e, "Failed to process request");

Tracing#

Distributed tracing support with OpenTelemetry:

use tracing_opentelemetry::OpenTelemetryLayer;

// Configure tracing
let tracer = opentelemetry_jaeger::new_pipeline()
    .with_service_name("gigabrain")
    .install_simple()?;

License#

This project is licensed under the MIT License - see the LICENSE file for details.

Support#

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Community Server

Roadmap#

Version 0.2.0#

• Distributed deployment support
• Advanced query optimization
• Real-time streaming APIs
• Graph visualization tools

Version 0.3.0#

• Machine learning integration
• Time-series graph support
• Advanced security features
• Cloud provider integrations

Version 1.0.0#

• Production-ready stability
• Comprehensive documentation
• Enterprise features
• Professional support options