A high-performance, stateless, read-only graph query engine for ClickHouse with Neo4j ecosystem compatibility.

Note: ClickGraph is a fork of Brahmand with additional features including Neo4j Bolt protocol support and view-based graph analysis. This is a read-only analytical query engine - write operations are not supported.

• Read-Only Graph Analytics: Translates Cypher graph queries into optimized ClickHouse SQL for analytical workloads
• ClickHouse-native: Extends ClickHouse with native graph modeling, merging OLAP speed with graph-analysis power
• Stateless Architecture: Offloads all storage and query execution to ClickHouse—no extra datastore required
• Cypher Query Language: Industry-standard Cypher read syntax for intuitive, expressive property-graph querying
• Variable-Length Paths: Recursive traversals with *1..3 syntax using ClickHouse WITH RECURSIVE CTEs
• Path Variables & Functions: Capture and analyze path data with length(p), nodes(p), relationships(p) functions
• Analytical-scale Performance: Optimized for very large datasets and complex multi-hop traversals
• Query Performance Metrics: Phase-by-phase timing with HTTP headers and structured logging for monitoring and optimization

• Bolt Protocol v4.4: Full Neo4j driver compatibility for seamless integration
• Dual Server Architecture: HTTP REST API and Bolt protocol running simultaneously
• Authentication Support: Multiple authentication schemes including basic auth
• Tool Compatibility: Works with existing Neo4j drivers, browsers, and applications

• Zero Migration: Transform existing relational data into graph format through YAML configuration
• Native Performance: Leverages ClickHouse's columnar storage and query optimization
• Robust Implementation: Comprehensive validation, error handling, and optimization passes

ClickGraph runs as a lightweight graph wrapper alongside ClickHouse with dual protocol support:

1. Client sends HTTP POST request with Cypher query to ClickGraph
2. ClickGraph parses & plans the query, translates to ClickHouse SQL
3. ClickHouse executes the SQL and returns results
4. ClickGraph sends JSON results back to the client

1. Neo4j Driver/Tool connects via Bolt protocol to ClickGraph
2. ClickGraph handles Bolt handshake, authentication, and message protocol
3. Cypher queries are processed through the same query engine as HTTP
4. Results are streamed back via Bolt protocol format

Both protocols share the same underlying query engine and ClickHouse backend.

New to ClickGraph? See the Getting Started Guide for a complete walkthrough.

⚠️ Windows Users: The HTTP server has a known issue on Windows. Use Docker or WSL for development. See KNOWN_ISSUES.md for details.

1. Clone and start services:

   git clone https://github.com/genezhang/clickgraph
   cd clickgraph
   docker-compose up -d

   This starts both ClickHouse and ClickGraph with test data pre-loaded.

2. Test the setup:

   curl -X POST http://localhost:8080/query \
     -H "Content-Type: application/json" \
     -d '{"query": "MATCH (u:User) RETURN u.full_name LIMIT 5"}'

1. Start ClickHouse:

   docker-compose up -d clickhouse

2. Configure and run:

   export CLICKHOUSE_URL="http://localhost:8123"
   export CLICKHOUSE_USER="test_user"
   export CLICKHOUSE_PASSWORD="test_pass"
   export CLICKHOUSE_DATABASE="brahmand"
   
   cargo run --bin brahmand

3. Test with HTTP API:

   curl -X POST http://localhost:8080/query \
     -H "Content-Type: application/json" \
     -d '{"query": "RETURN 1 as test"}'

4. Test with Neo4j driver:

   from neo4j import GraphDatabase
   
   driver = GraphDatabase.driver("bolt://localhost:7687")
   with driver.session() as session:
       result = session.run("RETURN 1 as test")

📖 Complete Setup Guide →

Transform existing relational data into graph format through YAML configuration:

Example: Map your users and user_follows tables to a social network graph:

views:
  - name: social_network
    nodes:
      user:
        source_table: users
        id_column: user_id
        property_mappings:
          name: full_name
    relationships:
      follows:
        source_table: user_follows
        from_column: follower_id
        to_column: followed_id

Then query with standard Cypher:

MATCH (u:user)-[:follows]->(friend:user)
WHERE u.name = 'Alice'
RETURN friend.name

OPTIONAL MATCH for handling optional patterns:

-- Find all users and their friends (if any)
MATCH (u:user)
OPTIONAL MATCH (u)-[:follows]->(friend:user)
RETURN u.name, friend.name

-- Mixed required and optional patterns
MATCH (u:user)-[:authored]->(p:post)
OPTIONAL MATCH (p)-[:liked_by]->(liker:user)
RETURN u.name, p.title, COUNT(liker) as likes

→ Generates efficient LEFT JOIN SQL with NULL handling for unmatched patterns

Perfect for first-time users! Simple social network demo with:

• 3 users, friendships - minimal setup with Memory tables
• Basic Cypher queries - find friends, mutual connections
• HTTP & Neo4j drivers - both integration methods
• 5-minute setup - zero to working graph analytics

Complete end-to-end demonstration with:

• Complete data setup with realistic e-commerce schema (customers, products, orders, reviews)
• Advanced graph queries for customer segmentation, product recommendations, and market basket analysis
• Real-world workflows with both HTTP REST API and Neo4j driver examples
• Performance optimization techniques and expected benchmarks
• Business insights from customer journeys, seasonal patterns, and cross-selling opportunities

Start with Quick Start, then explore E-commerce Analytics for advanced usage! 🎯

ClickGraph supports flexible configuration via command-line arguments and environment variables:

# View all options
cargo run --bin brahmand -- --help

# Custom ports
cargo run --bin brahmand -- --http-port 8081 --bolt-port 7688

# Disable Bolt protocol (HTTP only)
cargo run --bin brahmand -- --disable-bolt

# Custom host binding
cargo run --bin brahmand -- --http-host 127.0.0.1 --bolt-host 127.0.0.1

# Configure CTE depth limit for variable-length paths (default: 100)
cargo run --bin brahmand -- --max-cte-depth 150
export BRAHMAND_MAX_CTE_DEPTH=150  # Or via environment variable

See docs/configuration.md for complete configuration documentation.

For Windows users, ClickGraph supports running in the background using PowerShell jobs:

# Start server in background
.\start_server_background.ps1

# Check if server is running
Invoke-WebRequest -Uri "http://localhost:8080/health"

# Stop the server (replace JOB_ID with actual job ID shown)
Stop-Job -Id JOB_ID; Remove-Job -Id JOB_ID

Use the batch file to start the server in a separate command window:

start_server_background.bat

The server also supports a --daemon flag for Unix-like daemon behavior:

cargo run --bin brahmand -- --daemon --http-port 8080

• Getting Started - Complete setup walkthrough and first queries
• Features Overview - Comprehensive feature list and capabilities
• API Documentation - HTTP REST API and Bolt protocol usage
• Configuration Guide - Server configuration and CLI options

• GraphView Model - Complete view-based graph analysis
• Test Infrastructure - Testing framework and validation
• Development Guide - Development workflow and architecture

• Original Brahmand Docs - Original project documentation
• Neo4j Cypher Manual - Cypher query language reference
• ClickHouse Documentation - ClickHouse database documentation

Preliminary informal tests on a MacBook Pro (M3 Pro, 18 GB RAM) running ClickGraph in Docker against a ~12 million-node Stack Overflow dataset show multihop traversals running approximately 10× faster than Neo4j v2025.03. These early, unoptimized results are for reference only; a full benchmark report is coming soon.

ClickGraph includes the following completed features:

• ✅ Query Performance Metrics: Phase-by-phase timing with HTTP headers and structured logging
• ✅ Neo4j Bolt Protocol v4.4: Full compatibility with Neo4j drivers and tools
• ✅ PageRank Algorithm: Graph centrality analysis with CALL pagerank(iterations: 10, damping: 0.85)
• ✅ OPTIONAL MATCH: LEFT JOIN semantics for optional graph patterns with NULL handling
• ✅ Variable-Length Paths: Recursive traversals with configurable depth limits
• ✅ Path Variables & Functions: MATCH p = (a)-[*]->(b) RETURN length(p), nodes(p), relationships(p)
• ✅ View-Based Graph Model: Transform existing tables to graphs via YAML configuration
• ✅ Dual Server Architecture: HTTP REST API and Bolt protocol simultaneously
• ✅ Comprehensive Testing: 261/262 tests passing (99.6% success rate)
• ✅ Flexible Configuration: CLI options, environment variables, Docker deployment
• ✅ Query Optimization: Advanced optimization passes including chained JOIN optimization for exact hop counts

• ⚠️ Schema warnings: Cosmetic warnings about internal catalog system (functionality unaffected)
• 🔧 Memory vs MergeTree: Use Memory engine for development, MergeTree for persistent storage
• 🐳 Docker permissions: May require volume permission fixes on some systems

ClickGraph welcomes contributions! Key areas for development:

• Additional Cypher language features
• Query optimization improvements
• Neo4j compatibility enhancements
• Performance benchmarking
• Documentation improvements

ClickGraph is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

This project is a fork of Brahmand with significant enhancements for Neo4j ecosystem compatibility and enterprise deployment capabilities.