### Quick Setup with Docker Compose for ClickGraph

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

This snippet demonstrates the recommended way to quickly set up ClickGraph and ClickHouse using Docker Compose. It involves downloading the docker-compose.yaml file, starting the services, and checking the logs to confirm successful startup. This method requires Docker and Docker Compose.

```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/genezhang/clickgraph/main/docker-compose.yaml
docker-compose up -d
docker-compose logs -f clickgraph
```

--------------------------------

### Setup ClickGraph Server

Source: https://github.com/genezhang/clickgraph/blob/main/examples/variable-length-path-examples.md

Instructions to set up and run the ClickGraph server, including starting ClickHouse via Docker. Assumes Docker is installed and Docker Compose is available.

```bash
# Start ClickHouse (if using Docker)
docker-compose up -d

# Start ClickGraph server
./target/release/brahmand
```

--------------------------------

### Install Rust

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Installs Rust using the official installation script. This is a prerequisite for building ClickGraph from source.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Build and Run ClickGraph from Source

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

This section guides users through building ClickGraph from its source code, suitable for developers. It requires a Rust toolchain and Docker for ClickHouse. Steps include cloning the repository, starting only the ClickHouse service, configuring environment variables for ClickHouse connection, and then building and running the ClickGraph application using Cargo.

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

export CLICKHOUSE_URL="http://localhost:8123"
export CLICKHOUSE_USER="test_user"
export CLICKHOUSE_PASSWORD="test_pass"
export CLICKHOUSE_DATABASE="brahmand"
export GRAPH_CONFIG_PATH="./schemas/demo/social_network.yaml"

cargo build --release
cargo run --bin clickgraph
```

--------------------------------

### Use MergeTree Engine for Production

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Defines a ClickHouse table using the MergeTree engine, which provides persistent storage and is recommended for production environments. Includes an example ORDER BY clause.

```sql
CREATE TABLE users (...) ENGINE = MergeTree() ORDER BY id;
```

--------------------------------

### Production Deployment Examples for ClickGraph (Bash)

Source: https://github.com/genezhang/clickgraph/blob/main/docs/configuration.md

Provides various command-line examples for deploying ClickGraph in production environments, covering secure setups with custom ports, HTTP-only deployments, and container-friendly configurations.

```bash
# Local development with both protocols
export CLICKHOUSE_URL="http://localhost:8123"
export CLICKHOUSE_USER="test_user"
export CLICKHOUSE_PASSWORD="test_pass" 
export CLICKHOUSE_DATABASE="brahmand"

cargo run --bin brahmand

# Bind to localhost only, custom ports
cargo run --bin brahmand -- \
  --http-host 127.0.0.1 --http-port 8081 \
  --bolt-host 127.0.0.1 --bolt-port 7688

# Disable Bolt for REST-API only deployments
cargo run --bin brahmand -- --http-port 9090 --disable-bolt

# Bind to all interfaces for container deployments
cargo run --bin brahmand -- \
  --http-host 0.0.0.0 --http-port 8080 \
  --bolt-host 0.0.0.0 --bolt-port 7687
```

--------------------------------

### Install Neo4j Drivers for Programming Languages

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Package manager commands and dependency declarations for installing Neo4j drivers in Python, JavaScript/Node.js, and Java. These drivers enable programmatic interaction with ClickGraph from various applications.

```bash
pip install neo4j
```

```bash
npm install neo4j-driver
```

```xml
<dependency>
    <groupId>org.neo4j.driver</groupId>
    <artifactId>neo4j-java-driver</artifactId>
    <version>5.x.x</version>
</dependency>
```

--------------------------------

### Clone ClickGraph Repository

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Clones the ClickGraph repository from GitHub and navigates into the project directory. This is the first step for both Docker and source build setups.

```bash
git clone https://github.com/genezhang/clickgraph.git
cd clickgraph
```

--------------------------------

### Start ClickHouse Server

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Starts a ClickHouse server instance using Docker. This is required when building ClickGraph from source.

```bash
docker run -d --name clickhouse \
  -p 8123:8123 -p 9000:9000 \
  clickhouse/clickhouse-server
```

--------------------------------

### Configure ClickGraph via Environment Variables

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Environment variables for configuring ClickGraph server settings, ClickHouse connection details, and the graph schema path. This allows for flexible deployment and integration with CI/CD pipelines.

```bash
# Server settings
export CLICKGRAPH_HOST="127.0.0.1"
export CLICKGRAPH_PORT="8081"  
export CLICKGRAPH_BOLT_HOST="127.0.0.1"
export CLICKGRAPH_BOLT_PORT="7688"
export CLICKGRAPH_BOLT_ENABLED="false"

# ClickHouse connection
export CLICKHOUSE_URL="http://your-clickhouse:8123"
export CLICKHOUSE_USER="your_user"
export CLICKHOUSE_PASSWORD="your_password"
export CLICKHOUSE_DATABASE="your_database"

# Graph schema (required for graph queries)
export GRAPH_CONFIG_PATH="/path/to/your/schema.yaml"
```

--------------------------------

### ClickGraph Schema Configuration (YAML)

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Example YAML configuration file for ClickGraph, defining a 'social_network' schema with 'User' nodes and 'FOLLOWS' relationships.

```yaml
# schemas/demo/users.yaml
name: social_network
views:
  - name: main
    nodes:
      User:
        source_table: users
        id_column: user_id
        property_mappings:
          name: full_name
          age: user_age
    relationships:
      FOLLOWS:
        source_table: user_follows
        from_node: User
        to_node: User
        from_id: follower_id
        to_id: followed_id
```

--------------------------------

### Create Sample ClickHouse Tables and Data

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

SQL script to create 'users' and 'user_follows' tables in ClickHouse and populate them with sample data. This involves defining table schemas with appropriate data types and engines, and then inserting records into these tables.

```sql
-- Connect to ClickHouse and create sample data
CREATE TABLE users (
    user_id UInt32,
    name String,
    age UInt8,
    country String,
    active UInt8 DEFAULT 1
) ENGINE = MergeTree()
ORDER BY user_id;

CREATE TABLE user_follows (
    follower_id UInt32,
    followed_id UInt32,
    created_date Date
) ENGINE = MergeTree()
ORDER BY (follower_id, followed_id);

-- Insert sample data
INSERT INTO users VALUES 
    (1, 'Alice', 28, 'USA', 1),
    (2, 'Bob', 34, 'Canada', 1),
    (3, 'Charlie', 22, 'UK', 1),
    (4, 'Diana', 31, 'Australia', 1);

INSERT INTO user_follows VALUES
    (1, 2, '2023-01-15'),
    (1, 3, '2023-01-20'),
    (2, 3, '2023-01-25'),
    (3, 4, '2023-02-01'),
    (2, 4, '2023-02-05');
```

--------------------------------

### Connect to ClickGraph using Neo4j Browser and Cypher Shell

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Instructions for connecting to ClickGraph using Neo4j tools. This includes opening Neo4j Browser and connecting to the Bolt endpoint, and using the Cypher Shell for interactive query execution.

```bash
# Install Neo4j Cypher Shell
# Connect to ClickGraph
cypher-shell -a bolt://localhost:7687

# Run queries interactively
neo4j> MATCH (n:User) RETURN n.name, n.age;
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Enables debug logging for the ClickGraph binary using a RUST_LOG environment variable. This is useful for diagnosing runtime issues.

```bash
RUST_LOG=debug cargo run --bin clickgraph
```

--------------------------------

### Start and Check ClickGraph Server (Docker & Source)

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Troubleshooting-Guide.md

Commands to check if the ClickGraph server is running and to start it. Supports both Docker installations and source builds. Use `docker-compose ps` or `ps aux | grep clickgraph` to check status, and `docker-compose up -d` or `cargo run --release --bin clickgraph` to start.

```bash
# Check if server is running
docker-compose ps  # Docker
ps aux | grep clickgraph  # Source build

# Start server
docker-compose up -d  # Docker
cargo run --release --bin clickgraph  # Source
```

--------------------------------

### Neo4j Integration Examples

Source: https://github.com/genezhang/clickgraph/blob/main/docs/configuration.md

Examples demonstrating how to connect to and query Neo4j using ClickGraph with Python, Node.js, and Java.

```APIDOC
## Neo4j Integration Examples

This section provides code examples for interacting with the Neo4j database through ClickGraph using different programming languages.

### Python Example

```python
from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://localhost:7687")
with driver.session() as session:
    result = session.run("MATCH (n) RETURN n LIMIT 10")
    for record in result:
        print(record)
```

### Node.js Example

```javascript
const neo4j = require('neo4j-driver');

const driver = neo4j.driver('bolt://localhost:7687');
const session = driver.session();

session.run('MATCH (n) RETURN n LIMIT 10')
  .then(result => {
    result.records.forEach(record => console.log(record));
  });
```

### Java Example

```java
import org.neo4j.driver.*;

// ... inside a method ...
Driver driver = GraphDatabase.driver("bolt://localhost:7687");
Session session = driver.session();

Result result = session.run("MATCH (n) RETURN n LIMIT 10");
while (result.hasNext()) {
    Record record = result.next();
    System.out.println(record);
}
// Remember to close the driver and session when done
driver.close();
```
```

--------------------------------

### Configure ClickGraph Server Ports and Binding

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Bash commands to configure ClickGraph server settings using command-line arguments. This includes specifying custom HTTP and Bolt ports, disabling the Bolt protocol, and setting the host binding address.

```bash
# Custom ports
cargo run --bin clickgraph -- --http-port 8081 --bolt-port 7688

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

# Custom host binding
cargo run --bin clickgraph -- --http-host 127.0.0.1

# Show all options
cargo run --bin clickgraph -- --help
```

--------------------------------

### Load Schema and Run Graph Queries via HTTP

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Bash commands to load the ClickGraph schema and execute Cypher queries against the ClickHouse data via the HTTP API. It includes setting the schema path, restarting the ClickGraph service, and making POST requests with different query payloads.

```bash
# Set schema path
export GRAPH_CONFIG_PATH="./social_network.yaml"

# Restart ClickGraph to load the schema
cargo run --bin clickgraph

# Find Alice's friends (in a new terminal)
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MATCH (alice:User {name: \"Alice\"})-[:FOLLOWS]->(friend:User) RETURN friend.name, friend.age"
  }'

# Find mutual connections
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MATCH (a:User)-[:FOLLOWS]->(mutual:User)<-[:FOLLOWS]-(b:User) WHERE a.name = \"Alice\" AND b.name = \"Bob\" RETURN mutual.name"
  }'

# Count followers by country
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MATCH (u:User)-[:FOLLOWS]->(f:User) RETURN f.country, count(u) as follower_count ORDER BY follower_count DESC"
  }'
```

--------------------------------

### Resolve ClickGraph Port Conflicts

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Bash command to run ClickGraph with alternative HTTP and Bolt ports, which is useful for resolving conflicts if the default ports are already in use by other applications.

```bash
# Use different ports
cargo run --bin clickgraph -- --http-port 8081 --bolt-port 7688
```

--------------------------------

### Development Setup Commands (Bash)

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Architecture-Internals.md

A sequence of bash commands to set up the development environment for the ClickGraph project, including cloning the repository, installing Rust toolchain and development tools, starting dependencies, building, and running tests.

```bash
# 1. Clone repository
git clone https://github.com/yourusername/clickgraph.git
cd clickgraph

# 2. Install Rust toolchain
rustup install stable
rustup default stable

# 3. Install development tools
cargo install cargo-watch
cargo install cargo-audit

# 4. Start dependencies
docker-compose up -d clickhouse

# 5. Build project
cargo build

# 6. Run tests
cargo test --all

# 7. Run in development mode
cargo watch -x run
```

--------------------------------

### Run ClickGraph with Custom Ports from Source

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

This snippet shows how to run the ClickGraph application from source using custom HTTP and Bolt ports. This is useful when the default ports (8080 and 7687) are already in use. It requires the ClickGraph application to be built first using `cargo build --release`.

```bash
cargo run --bin clickgraph -- --http-port 8081 --bolt-port 7688
```

--------------------------------

### Start ClickGraph Service with Environment Variables

Source: https://github.com/genezhang/clickgraph/blob/main/examples/ecommerce-analytics.md

Sets up necessary environment variables for ClickHouse connection (URL, user, password, database) and then starts the ClickGraph service using Cargo. Ensure ClickHouse is running and accessible.

```bash
# Set environment variables
export CLICKHOUSE_URL="http://localhost:8123"
export CLICKHOUSE_USER="default"
export CLICKHOUSE_PASSWORD=""
export CLICKHOUSE_DATABASE="ecommerce"

# Start ClickGraph
cargo run --bin brahmand
```

--------------------------------

### Show Tables in ClickHouse

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Lists all available tables within the default database of the ClickHouse instance.

```bash
docker exec clickhouse-clickhouse clickhouse-client -q "SHOW TABLES FROM default"
```

--------------------------------

### Quick Production Setup for ClickGraph using Docker

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Docker-Deployment.md

This snippet demonstrates the essential steps to quickly set up and deploy ClickGraph in a production environment using Docker. It covers cloning the repository, creating a production environment file with necessary configurations like ClickHouse connection details and schema paths, and starting the production Docker Compose stack. Finally, it includes a command to verify the deployment by checking the health endpoint.

```bash
# 1. Clone and prepare
git clone https://github.com/genezhang/clickgraph.git
cd clickgraph

# 2. Create production environment file
cat > .env.production <<EOF
CLICKHOUSE_URL=http://clickhouse:8123
CLICKHOUSE_USER=clickgraph_user
CLICKHOUSE_PASSWORD=your_secure_password
CLICKHOUSE_DATABASE=production_graph
GRAPH_CONFIG_PATH=/app/schemas/production.yaml
RUST_LOG=info
EOF

# 3. Start production stack
docker-compose -f docker-compose.prod.yaml up -d

# 4. Verify deployment
curl http://localhost:8080/health
```

--------------------------------

### Configure ClickGraph Social Network Schema

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

YAML configuration file defining the graph schema for a social network. It maps ClickHouse tables ('users', 'user_follows') to graph nodes ('User') and relationships ('FOLLOWS'), specifying ID columns and property mappings.

```yaml
name: social_network
version: "1.0"
description: "Social network analysis"

graph_schema:
  nodes:
    - label: User
      database: brahmand
      table: users
      id_column: user_id
      property_mappings:
        name: name
        age: age
        country: country
      filters:
        - "active = 1"
          
  relationships:
    - type: FOLLOWS
      database: brahmand
      table: user_follows
      from_node: User
      to_node: User
      from_id: follower_id
      to_id: followed_id
      property_mappings:
        since: created_date
```

--------------------------------

### Starting ClickGraph Server with Cargo

Source: https://github.com/genezhang/clickgraph/blob/main/examples/quick-start.md

This bash command compiles and runs the ClickGraph (Brahmand) server using Cargo. It requires setting environment variables for the ClickHouse database and the graph configuration file, and specifies the HTTP and Bolt ports.

```bash
# Set environment and start server
export CLICKHOUSE_DATABASE="social"
export GRAPH_CONFIG_FILE="social_network.yaml"

# Start ClickGraph
cargo run --bin brahmand -- --http-port 8080 --bolt-port 7687
```

--------------------------------

### Start ClickGraph with Docker Compose

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Starts ClickHouse and ClickGraph services using Docker Compose in detached mode. It also provides a command to check the status of the running services.

```bash
# Start ClickHouse and ClickGraph
docker-compose up -d

# Check that services are running
docker-compose ps
```

--------------------------------

### Test ClickGraph HTTP API

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

This code snippet demonstrates how to test the ClickGraph HTTP API by sending a POST request with a simple query. It uses `curl` to send a JSON payload to the `/query` endpoint and expects a JSON response containing the query results and execution statistics. This test confirms the HTTP server is operational.

```bash
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query": "RETURN 1 as test, \"Hello ClickGraph!\" as message"}'
```

--------------------------------

### Setting up ClickHouse Environment

Source: https://github.com/genezhang/clickgraph/blob/main/examples/quick-start.md

This bash script sets up the ClickHouse service using Docker Compose and exports the necessary connection URLs and credentials for subsequent operations.

```bash
# Ensure ClickHouse is running
docker-compose up -d clickhouse-service
```

```bash
# Use credentials from docker-compose.yaml
export CLICKHOUSE_URL="http://localhost:8123"
export CLICKHOUSE_USER="test_user"
export CLICKHOUSE_PASSWORD="test_pass"
```

--------------------------------

### Run ClickGraph from Source

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Runs the ClickGraph server in release mode from the built binary. It shows how to run with default ports and with custom ports.

```bash
# Run with default settings (HTTP: 8080, Bolt: 7687)

cargo run --release --bin clickgraph

# Or with custom ports
cargo run --release --bin clickgraph -- --http-port 8081 --bolt-port 7688
```

--------------------------------

### Clone Project and Start ClickHouse in WSL2

Source: https://github.com/genezhang/clickgraph/blob/main/notes/windows_mergetree_fix.md

This setup guide demonstrates how to resolve ClickHouse permission issues on Windows by leveraging the WSL2 backend for Docker. It involves cloning the project within the WSL2 filesystem and starting Docker Compose, which eliminates Windows filesystem limitations and provides native Linux performance.

```bash
# From WSL2 terminal
cd ~
git clone https://github.com/genezhang/clickgraph.git
cd clickgraph
docker-compose up -d
```

--------------------------------

### Run ClickGraph in Background (Windows PowerShell - Incorrect)

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

An example of incorrectly trying to run the ClickGraph binary, which will exit when the script finishes.

```powershell
# ❌ Wrong (exits when script ends)
cargo run --release --bin clickgraph
```

--------------------------------

### Build ClickGraph from Source

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Clones the ClickGraph repository and builds the project in release mode using Cargo. This option is for users who prefer not to use Docker.

```bash
git clone https://github.com/genezhang/clickgraph.git
cd clickgraph

# Build in release mode for better performance
cargo build --release
```

--------------------------------

### Check ClickGraph Server Health

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Sends a GET request to the /health endpoint of the ClickGraph server to check its operational status and connectivity to ClickHouse.

```bash
curl http://localhost:8080/health
```

--------------------------------

### Quick Start: Docker Setup and First Query

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Home.md

This section details the steps to set up ClickGraph using Docker, including pulling the image, starting ClickHouse, running ClickGraph with ClickHouse credentials, and executing a first Cypher query via the HTTP REST API. It emphasizes the required environment variables for ClickHouse connection.

```bash
# 1. Pull the latest Docker image
docker pull genezhang/clickgraph:latest

# 2. Start ClickHouse
docker run -d --name clickhouse \
  -p 8123:8123 \
  -e CLICKHOUSE_DB=brahmand \
  -e CLICKHOUSE_USER=test_user \
  -e CLICKHOUSE_PASSWORD=test_pass \
  clickhouse/clickhouse-server:latest

# 3. Run ClickGraph with ClickHouse credentials
docker run -d --name clickgraph \
  --link clickhouse:clickhouse \
  -p 8080:8080 \
  -p 7687:7687 \
  -e CLICKHOUSE_URL="http://clickhouse:8123" \
  -e CLICKHOUSE_USER="test_user" \
  -e CLICKHOUSE_PASSWORD="test_pass" \
  -e CLICKHOUSE_DATABASE="brahmand" \
  genezhang/clickgraph:latest

# 4. Run your first query
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (u:User) RETURN u.name LIMIT 5"}'
```

--------------------------------

### Set ClickHouse Credentials

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Configures environment variables for ClickHouse user and password, typically used when running ClickGraph with Docker Compose. This is essential for authentication.

```bash
# Use docker-compose credentials
export CLICKHOUSE_USER="test_user"
export CLICKHOUSE_PASSWORD="test_pass"
```

--------------------------------

### Setup Scripts (SQL/Bash)

Source: https://github.com/genezhang/clickgraph/blob/main/docs/development/testing.md

Scripts for setting up demo and test data, located in the `scripts/setup/` directory. This includes SQL scripts for data population.

```bash
scripts/setup/setup_demo_data.sql      # Demo data
scripts/setup/setup_test_data.sql      # Test data
```

--------------------------------

### Retrieve ClickGraph Schema Information

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Sends a GET request to the /schema endpoint of the ClickGraph server to retrieve information about the loaded graph schema, including node and relationship types.

```bash
curl http://localhost:8080/schema
```

--------------------------------

### Run ClickGraph Query (POST Request)

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Executes a Cypher query against the ClickGraph server via a POST request. Demonstrates cold cache (first run) and cached (second run) performance.

```shell
time curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (u:User) RETURN count(u)"}'
```

--------------------------------

### Start Server using Batch Script

Source: https://github.com/genezhang/clickgraph/blob/main/docs/development/environment-checklist.md

This is the recommended method for starting the project's server. Executing this batch file typically ensures that the server is launched in a new, clean environment, correctly inheriting necessary configurations.

```batch
# RECOMMENDED: Use the batch file (starts in new window)
.\start_server_new_window.bat
```

--------------------------------

### Troubleshoot ClickHouse Authentication Errors

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Bash command to test ClickHouse connection with provided user credentials. This helps in diagnosing authentication failures when ClickGraph attempts to connect to ClickHouse.

```bash
# Test ClickHouse connection
curl "http://localhost:8123/?user=test_user&password=test_pass" -d "SELECT 1"
```

--------------------------------

### Load Demo Data into ClickHouse

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Executes a SQL script to load sample data into the ClickHouse database used by ClickGraph.

```bash
docker exec -i clickhouse-clickhouse clickhouse-client < schemas/demo/setup_demo_data.sql
```

--------------------------------

### Develop with Memory Engine

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Specifies the Memory engine for ClickHouse tables. This is a recommended solution for development environments to avoid file permission issues, although it leads to data loss on restart.

```sql
ENGINE = Memory
```

--------------------------------

### Troubleshoot ClickGraph Connection Issues

Source: https://github.com/genezhang/clickgraph/blob/main/docs/getting-started.md

Bash commands to diagnose and resolve common connection problems with ClickGraph and ClickHouse. This includes checking if the services are running and testing direct connectivity to ClickHouse.

```bash
# Check if ClickGraph is running
curl http://localhost:8080/query

# Check ClickHouse connectivity
curl http://localhost:8123/ping
```

--------------------------------

### Example Log Messages: Filter Categorization (DEBUG + TRACE)

Source: https://github.com/genezhang/clickgraph/blob/main/notes/debug-logging-guide.md

These log messages, generated at both DEBUG and TRACE levels, show the process of categorizing filters for start and end aliases, including the filter expression details.

```text
Categorizing filters for start alias 'a' and end alias 'b'  [DEBUG]
Filter expression: PropertyAccessExp(...)  [TRACE]
Filter categorization result:  [TRACE]
  Start filters: Some(...)
  End filters: Some(...)
```

--------------------------------

### Cypher Social Network: Friend Recommendations

Source: https://github.com/genezhang/clickgraph/blob/main/docs/variable-length-paths-guide.md

Example Cypher query to find potential friend recommendations within 2-3 degrees of connection in a social network. Excludes the starting user and limits the results.

```cypher
-- Friends and friends-of-friends
MATCH (me:User {user_id: 123})-[f:FOLLOWS*1..2]->(suggested:User)
WHERE suggested.user_id <> 123  -- Exclude self
RETURN DISTINCT suggested.name, suggested.email
LIMIT 10
```

--------------------------------

### Quick Start Commands for ClickGraph

Source: https://github.com/genezhang/clickgraph/blob/main/docs/features/packstream.md

Provides a series of bash commands to set up and run the clickgraph application, including starting ClickHouse, loading demo data, setting environment variables, and running the cargo build.

```bash
# 1. Start ClickHouse
docker-compose up -d

# 2. Load demo data
docker exec -i clickgraph-clickhouse clickhouse-client --user test_user --password test_pass < setup_demo_data.sql

# 3. Start ClickGraph with debug logging
$env:RUST_LOG="debug"
$env:CLICKHOUSE_URL="http://localhost:8123"
$env:CLICKHOUSE_USER="test_user"
$env:CLICKHOUSE_PASSWORD="test_pass"
cargo run --release --bin clickgraph

# 4. Test with Python driver
python test_bolt_protocol.py
```

--------------------------------

### Dockerfile for ClickGraph Runtime

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Docker-Deployment.md

This Dockerfile sets up the runtime environment for ClickGraph. It installs dependencies, creates a non-root user, copies the application binary and schemas, exposes necessary ports, and defines health check and entrypoint commands.

```dockerfile
FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y \
    ca-certificates \
    curl \
    && rm -rf /var/lib/apt/lists/*

RUN useradd -r -u 1000 -m -s /bin/bash clickgraph

WORKDIR /app

COPY --from=builder /build/target/release/clickgraph /app/

COPY --chown=clickgraph:clickgraph schemas /app/schemas

USER clickgraph

EXPOSE 8080 7687

HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

CMD ["/app/clickgraph"]
```

--------------------------------

### Cypher Nested Optional Matches Example

Source: https://github.com/genezhang/clickgraph/blob/main/docs/optional-match-guide.md

Demonstrates a two-level optional traversal in Cypher, starting from a user and optionally matching their friends and the posts those friends like. This pattern helps retrieve data even when intermediate relationships or nodes are missing.

```cypher
MATCH (u:User)
OPTIONAL MATCH (u)-[:FRIENDS_WITH]->(friend:User)
OPTIONAL MATCH (friend)-[:LIKES]->(p:Post)
RETURN u.name, friend.name, p.title
```

--------------------------------

### Run First Graph Query via HTTP API

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/Quick-Start-Guide.md

Sends a POST request to the ClickGraph HTTP API to execute a graph query. It retrieves user names and ages, ordered by age, limited to 5 results.

```bash
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MATCH (u:User) RETURN u.name, u.age ORDER BY u.age LIMIT 5"
  }'
```

--------------------------------

### Get Specific Schema Information - Curl Example

Source: https://github.com/genezhang/clickgraph/blob/main/docs/wiki/API-Reference-HTTP.md

Example using curl to retrieve detailed information for a specific schema, 'social_network'. This demonstrates a GET request to the /schemas/{name} endpoint.

```bash
curl http://localhost:8080/schemas/social_network
```

--------------------------------

### ClickGraph Server Configuration Examples

Source: https://github.com/genezhang/clickgraph/blob/main/README.md

Illustrates how to configure the ClickGraph server using command-line arguments and environment variables. Examples include setting HTTP and Bolt ports, disabling protocols, binding hosts, and adjusting CTE depth.

```bash
# View all options
cargo run --bin clickgraph -- --help
```

```bash
# Custom ports
cargo run --bin clickgraph -- --http-port 8081 --bolt-port 7688
```

```bash
# Disable Bolt protocol (HTTP only)
cargo run --bin clickgraph -- --disable-bolt
```

```bash
# Custom host binding
cargo run --bin clickgraph -- --http-host 127.0.0.1 --bolt-host 127.0.0.1
```

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

--------------------------------

### Troubleshoot Container Start Issues: Volume Mount Permissions

Source: https://github.com/genezhang/clickgraph/blob/main/docs/docker-deployment.md

Resolve permission issues related to volume mounts by ensuring that the mounted files and directories are readable by the correct user ID within the container. This example shows how to change ownership to UID 1000.

```bash
# Ensure files are readable by UID 1000
chown -R 1000:1000 ./schemas
```

--------------------------------

### Basic ClickGraph Command-Line Options (Bash)

Source: https://github.com/genezhang/clickgraph/blob/main/docs/configuration.md

Demonstrates basic command-line operations for ClickGraph, including running with default settings, displaying all available options, and showing version information.

```bash
# Default configuration (HTTP:8080, Bolt:7687)
cargo run --bin brahmand

# Show all available options
cargo run --bin brahmand -- --help

# Show version information  
cargo run --bin brahmand -- --version
```

--------------------------------

### Creating Social Network Database and Tables in ClickHouse

Source: https://github.com/genezhang/clickgraph/blob/main/examples/quick-start.md

This SQL script defines and populates the 'social' database with 'users' and 'friendships' tables using in-memory storage. It includes sample data for users and their relationships.

```sql
-- Connect and create database
CREATE DATABASE IF NOT EXISTS social;
USE social;

-- Users table
CREATE TABLE users (
    user_id UInt32,
    name String,
    age UInt8,
    city String
) ENGINE = Memory;  -- Simple in-memory storage

-- Friendships table  
CREATE TABLE friendships (
    user1_id UInt32,
    user2_id UInt32,
    since_date Date
) ENGINE = Memory;

-- Insert sample data
INSERT INTO users VALUES 
    (1, 'Alice', 25, 'New York'),
    (2, 'Bob', 30, 'San Francisco'), 
    (3, 'Carol', 28, 'London');

INSERT INTO friendships VALUES
    (1, 2, '2023-01-15'),  -- Alice -> Bob
    (2, 3, '2023-02-10'),  -- Bob -> Carol  
    (1, 3, '2023-03-05');  -- Alice -> Carol
```

```sql
-- Check our data
SELECT * FROM users;
SELECT * FROM friendships;
```

--------------------------------

### Docker Compose Production Example for ClickGraph

Source: https://github.com/genezhang/clickgraph/blob/main/docs/docker-deployment.md

This YAML file defines a Docker Compose setup for a production ClickGraph environment. It includes services for ClickHouse and ClickGraph itself, with configurations for environment variables, volumes, health checks, and resource limits. It also defines Docker volumes for persistent data storage.

```yaml
version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:25.8.11
    container_name: clickhouse
    environment:
      CLICKHOUSE_DB: "production"
      CLICKHOUSE_USER: "clickgraph_user"
      CLICKHOUSE_PASSWORD: "${CH_PASSWORD}" # Use secrets!
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: "1"
    ports:
      - "8123:8123"
    volumes:
      - clickhouse_data:/var/lib/clickhouse
    healthcheck:
      test: ["CMD", "clickhouse-client", "--query", "SELECT 1"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  clickgraph:
    image: genezhang/clickgraph:0.5.0  # Pin to specific version
    container_name: clickgraph
    depends_on:
      clickhouse:
        condition: service_healthy
    environment:
      # ClickHouse connection
      CLICKHOUSE_URL: "http://clickhouse:8123"
      CLICKHOUSE_USER: "clickgraph_user"
      CLICKHOUSE_PASSWORD: "${CH_PASSWORD}" # Use secrets!
      CLICKHOUSE_DATABASE: "production"
      
      # Server config
      CLICKGRAPH_PORT: "8080"
      CLICKGRAPH_BOLT_PORT: "7687"
      CLICKGRAPH_BOLT_ENABLED: "true"
      CLICKGRAPH_MAX_CTE_DEPTH: "200"
      
      # Logging
      RUST_LOG: "warn" # Less verbose in production
      
      # Cache config
      CLICKGRAPH_QUERY_CACHE_ENABLED: "true"
      CLICKGRAPH_QUERY_CACHE_MAX_ENTRIES: "5000"
      CLICKGRAPH_QUERY_CACHE_MAX_SIZE_MB: "500"
      
      # Schema
      GRAPH_CONFIG_PATH: "/app/config/schema.yaml"
    ports:
      - "8080:8080"
      - "7687:7687"
    volumes:
      - ./config/schema.yaml:/app/config/schema.yaml:ro
      - ./schemas:/app/schemas:ro
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s
    restart: unless-stopped
    # Resource limits
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

volumes:
  clickhouse_data:

```

--------------------------------

### Manual ClickHouse Setup and Data Insertion

Source: https://github.com/genezhang/clickgraph/blob/main/docs/TESTING_SETUP.md

Provides step-by-step instructions to manually set up ClickHouse, including starting the service, creating databases and tables, and inserting test data using cURL commands.

```powershell
docker-compose up -d clickhouse-service
```

```powershell
# Using curl (Windows)
curl -X POST "http://localhost:8123/?user=test_user&password=test_pass" \
  -d "CREATE DATABASE IF NOT EXISTS test_integration"

curl -X POST "http://localhost:8123/?user=test_user&password=test_pass&database=test_integration" \
  -d "CREATE TABLE IF NOT EXISTS users (id UInt32, name String, age UInt32) ENGINE = Memory"

curl -X POST "http://localhost:8123/?user=test_user&password=test_pass&database=test_integration" \
  -d "CREATE TABLE IF NOT EXISTS follows (follower_id UInt32, followed_id UInt32, since String) ENGINE = Memory"
```

```powershell
curl -X POST "http://localhost:8123/?user=test_user&password=test_pass&database=test_integration" \
  -d "INSERT INTO users VALUES (1, 'Alice', 30), (2, 'Bob', 25), (3, 'Charlie', 35), (4, 'Diana', 28), (5, 'Eve', 32)"

curl -X POST "http://localhost:8123/?user=test_user&password=test_pass&database=test_integration" \
  -d "INSERT INTO follows VALUES (1, 2, '2023-01-01'), (1, 3, '2023-01-15'), (2, 3, '2023-02-01'), (3, 4, '2023-02-15'), (4, 5, '2023-03-01'), (2, 4, '2023-03-15')"
```