helix-db/CONTRIBUTORS.md

HelixDB Contributors Guide

Overview

HelixDB is a high-performance graph-vector database built in Rust, optimized for RAG and AI applications. It combines graph traversals, vector similarity search, and full-text search in a single database.

Project Structure

Expand message.txt 5 KB  George georgecurtis

HelixDB Contributors Guide

Overview

HelixDB is a high-performance graph-vector database built in Rust, optimized for RAG and AI applications. It combines graph traversals, vector similarity search, and full-text search in a single database.

Project Structure

Core Components

/helixdb/ - Main Database Library

The heart of HelixDB containing all database functionality.

• helix_engine/ - Database engine implementation

  • bm25/ - Full-text search using BM25 algorithm
  • graph_core/ - Graph database operations (nodes, edges, traversals)
  • storage_core/ - LMDB-based storage backend via heed3
  • vector_core/ - Vector storage and HNSW similarity search

• helix_gateway/ - Network layer

  • connection/ - TCP connection handling
  • router/ - Request routing to handlers
  • thread_pool/ - Concurrent request processing
  • mcp/ - Model Context Protocol support

• helixc/ - Query compiler

  • parser/ - Pest-based parser for .hx files
  • analyzer/ - Type checking and validation
  • generator/ - Query plan generation

• ingestion_engine/ - External data ingestion

  • PostgreSQL support (with pgvector)
  • SQLite support

• protocol/ - Wire protocol and data types

/helix-container/ - Runtime Container

The server process that hosts compiled queries and handles requests.

Files:

• main.rs - Initializes graph engine and HTTP gateway
• queries.rs - Generated code placeholder (populated during build)

Architecture:

• Loads compiled queries via inventory crate route discovery
• Creates HelixGraphEngine with LMDB storage backend
• Starts HelixGateway on configured port (default: 6969)
• Routes HTTP requests to registered handlers

Environment Variables:

• HELIX_DATA_DIR - Database storage location
• HELIX_PORT - Server port

/helix-cli/ - Command-Line Interface

User-facing CLI for managing HelixDB instances.

Files:

• main.rs - Command implementations
• args.rs - CLI argument definitions (clap)
• instance_manager.rs - Instance lifecycle management
• types.rs - Error types and version handling
• utils.rs - File handling, port management, templates

Commands:

• helix install - Clone and setup HelixDB repository
• helix init - Create new project with template files
• helix check - Validate schema and query syntax
• helix deploy - Compile queries and start new instance
• helix redeploy - Update existing instance (local/remote)
• helix instances - List all running instances
• helix start/stop - Control instance lifecycle
• helix delete - Remove instance and data
• helix save - Export instance data

Deploy Flow:

1. Read .hx files (schema.hx, queries.hx)
2. Parse and analyze using helixc
3. Generate Rust code with handler functions
4. Write to container/src/queries.rs
5. Build release binary with optimizations
6. Start instance with unique ID and port

Supporting Libraries

/debug_trace/ - Debug Macro

Procedural macro for function tracing (#[debug_trace]).

/get_routes/ - Route Registration

Procedural macro for HTTP handler registration (#[handler]).

/hbuild_redploy/ - Deployment Service

Hot-swapping service for production deployments via AWS S3.

Key Concepts

Query Language

HelixDB uses a custom query language defined in .hx files:

QUERY addUser(name: String, age: I64) =>
   user <- AddN<User({name: name, age: age})
   RETURN user

Data Model

• Nodes (N::) - Graph vertices with properties
• Edges (E::) - Relationships between nodes
• Vectors (V::) - High-dimensional embeddings

Operations

• Graph traversals: In, Out, InE, OutE
• Vector search: HNSW-based similarity search
• Text search: BM25 full-text search
• CRUD: AddN, AddE, Update, Drop

Architecture Flow

1. Definition: Write queries in .hx files
2. Compilation: helix check parses and validates
3. Deployment: helix deploy loads into container
4. Execution: Gateway routes requests to compiled handlers
5. Storage: LMDB handles persistence with ACID guarantees

Development Guidelines

Code Style

• Prefer functional patterns (pattern matching, iterators, closures)
• Document code inline - no separate docs needed
• Minimize dependencies
• Use asserts liberally in production code

Testing

• Write benchmarks before optimizing
• DST (Deterministic Simulation Testing) coming soon

Performance

• Currently 1000x faster than Neo4j for graph operations
• On par with Qdrant for vector search
• LMDB provides memory-mapped performance

Getting Started

1. Install CLI: curl -sSL "https://install.helix-db.com" | bash
2. Install Helix: helix install
3. Initialize project: helix init --path <path>
4. Write queries in .hx files
5. Deploy: helix deploy

License

AGPL (Affero General Public License)

For commercial support: founders@helix-db.com message.txt 5 KB