wifi-densepose/examples/docs/graph-cli-usage.md

RuVector Graph CLI - Usage Examples

This guide demonstrates practical usage of the RuVector graph database CLI commands.

Quick Start

1. Create a New Graph Database

# Create with default settings
ruvector graph create --path ./my-graph.db --name production

# Create with property indexing enabled
ruvector graph create --path ./my-graph.db --name production --indexed

Output:

✓ Creating graph database at: ./my-graph.db
  Graph name: production
  Property indexing: enabled
✓ Graph database created successfully!
ℹ Use 'ruvector graph shell' to start interactive mode

2. Execute Cypher Queries

# Simple query
ruvector graph query -b ./my-graph.db -q "MATCH (n:Person) RETURN n"

# Query with output format
ruvector graph query -b ./my-graph.db -q "MATCH (n) RETURN n" --format json

# Show query execution plan
ruvector graph query -b ./my-graph.db -q "MATCH (n)-[r]->(m) RETURN n, r, m" --explain

Note: Use -b for database path (not -d, which is global debug flag) Note: Use -q for cypher query (not -c, which is global config flag)

3. Interactive Shell (REPL)

# Start shell
ruvector graph shell -b ./my-graph.db

# Start shell with multiline mode (queries end with semicolon)
ruvector graph shell -b ./my-graph.db --multiline

Example Session:

RuVector Graph Shell
Database: ./my-graph.db
Type :exit to exit, :help for help

cypher> CREATE (alice:Person {name: 'Alice', age: 30})
✓ Query completed in 5.23ms

cypher> CREATE (bob:Person {name: 'Bob', age: 25})
✓ Query completed in 3.12ms

cypher> MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
   ... CREATE (a)-[:KNOWS {since: 2020}]->(b)
✓ Query completed in 4.56ms

cypher> MATCH (n:Person) RETURN n.name, n.age
+--------+-------+
| name   | age   |
+--------+-------+
| Alice  | 30    |
| Bob    | 25    |
+--------+-------+

cypher> :exit
✓ Goodbye!

Shell Commands:

• :exit, :quit, :q - Exit the shell
• :help, :h - Show help
• :clear - Clear query buffer

4. Import Graph Data

JSON Format

ruvector graph import -b ./my-graph.db -i data.json --format json -g production

Example data.json:

{
  "nodes": [
    {
      "id": "1",
      "labels": ["Person"],
      "properties": {
        "name": "Alice",
        "age": 30,
        "city": "San Francisco"
      }
    },
    {
      "id": "2",
      "labels": ["Person"],
      "properties": {
        "name": "Bob",
        "age": 25,
        "city": "New York"
      }
    }
  ],
  "relationships": [
    {
      "id": "r1",
      "type": "KNOWS",
      "startNode": "1",
      "endNode": "2",
      "properties": {
        "since": 2020,
        "closeness": 0.8
      }
    }
  ]
}

Cypher Format

ruvector graph import -b ./my-graph.db -i init.cypher --format cypher

Example init.cypher:

CREATE (alice:Person {name: 'Alice', age: 30, city: 'SF'});
CREATE (bob:Person {name: 'Bob', age: 25, city: 'NYC'});
CREATE (carol:Person {name: 'Carol', age: 28, city: 'LA'});

MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
CREATE (a)-[:KNOWS {since: 2020}]->(b);

MATCH (b:Person {name: 'Bob'}), (c:Person {name: 'Carol'})
CREATE (b)-[:KNOWS {since: 2021}]->(c);

CSV Format

ruvector graph import -b ./my-graph.db -i nodes.csv --format csv

Example nodes.csv:

id,labels,properties
1,"[""Person""]","{""name"": ""Alice"", ""age"": 30}"
2,"[""Person""]","{""name"": ""Bob"", ""age"": 25}"

5. Export Graph Data

# Export to JSON
ruvector graph export -b ./my-graph.db -o backup.json --format json

# Export to Cypher statements
ruvector graph export -b ./my-graph.db -o backup.cypher --format cypher

# Export to GraphML (for Gephi, Cytoscape, etc.)
ruvector graph export -b ./my-graph.db -o graph.graphml --format graphml

# Export specific graph
ruvector graph export -b ./my-graph.db -o prod-backup.json -g production

6. Database Information

# Basic info
ruvector graph info -b ./my-graph.db

# Detailed statistics
ruvector graph info -b ./my-graph.db --detailed

Output:

Graph Database Statistics
  Database: ./my-graph.db
  Graphs: 1
  Total nodes: 1,234
  Total relationships: 5,678
  Node labels: 3
  Relationship types: 5

Storage Information:
  Store size: 45.2 MB
  Index size: 12.8 MB

Configuration:
  Cache size: 128 MB
  Page size: 4096 bytes

7. Performance Benchmarks

# Traverse benchmark
ruvector graph benchmark -b ./my-graph.db -n 1000 -t traverse

# Pattern matching benchmark
ruvector graph benchmark -b ./my-graph.db -n 5000 -t pattern

# Aggregation benchmark
ruvector graph benchmark -b ./my-graph.db -n 2000 -t aggregate

Output:

Running graph benchmark...
  Benchmark type: traverse
  Queries: 1000

Benchmark Results:
  Total time: 2.45s
  Queries per second: 408
  Average latency: 2.45ms

8. Start Graph Server

# Basic server
ruvector graph serve -b ./my-graph.db

# Custom ports
ruvector graph serve -b ./my-graph.db --http-port 9000 --grpc-port 50052

# Public server with GraphQL
ruvector graph serve -b ./my-graph.db --host 0.0.0.0 --graphql

# Full configuration
ruvector graph serve \
  -b ./my-graph.db \
  --host 0.0.0.0 \
  --http-port 8080 \
  --grpc-port 50051 \
  --graphql

Server Endpoints:

• HTTP: http://localhost:8080/query
• gRPC: localhost:50051
• GraphQL: http://localhost:8080/graphql (if enabled)

Common Workflows

Building a Social Network

# Create database
ruvector graph create --path social.db --name social --indexed

# Start interactive shell
ruvector graph shell -b social.db --multiline

In the shell:

-- Create nodes
CREATE (alice:Person {name: 'Alice', age: 30, interests: ['AI', 'Databases']});
CREATE (bob:Person {name: 'Bob', age: 25, interests: ['Rust', 'Systems']});
CREATE (carol:Person {name: 'Carol', age: 28, interests: ['AI', 'Rust']});

-- Create relationships
MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
CREATE (a)-[:KNOWS {since: 2020, strength: 0.8}]->(b);

MATCH (b:Person {name: 'Bob'}), (c:Person {name: 'Carol'})
CREATE (b)-[:KNOWS {since: 2021, strength: 0.9}]->(c);

-- Query friends
MATCH (a:Person {name: 'Alice'})-[:KNOWS]->(friend)
RETURN friend.name, friend.age;

-- Find friends of friends
MATCH (a:Person {name: 'Alice'})-[:KNOWS*2..3]-(fof)
WHERE fof.name <> 'Alice'
RETURN DISTINCT fof.name;

-- Find common interests
MATCH (p:Person)
WHERE ANY(interest IN p.interests WHERE interest IN ['AI', 'Rust'])
RETURN p.name, p.interests;

Knowledge Graph RAG System

# Create knowledge graph
ruvector graph create --path knowledge.db --name kg --indexed

# Import from JSON
ruvector graph import -b knowledge.db -i documents.json --format json

# Query for similar concepts
ruvector graph query -b knowledge.db -q \
  "MATCH (d:Document)-[:MENTIONS]->(c:Concept)
   WHERE c.name = 'Machine Learning'
   RETURN d.title, d.content"

# Export for backup
ruvector graph export -b knowledge.db -o kg-backup.cypher --format cypher

Recommendation Engine

# Create recommendations graph
ruvector graph create --path recommendations.db --name rec

# Import user-item interactions
ruvector graph import -b recommendations.db -i interactions.csv --format csv

# Find recommendations via collaborative filtering
ruvector graph query -b recommendations.db -q \
  "MATCH (u:User {id: '123'})-[:LIKED]->(i:Item)<-[:LIKED]-(other:User)
   MATCH (other)-[:LIKED]->(rec:Item)
   WHERE NOT (u)-[:LIKED]->(rec)
   RETURN rec.name, COUNT(*) as score
   ORDER BY score DESC
   LIMIT 10"

Advanced Usage

Batch Import with Error Handling

# Skip errors and continue importing
ruvector graph import -b ./db.db -i large-dataset.json --skip-errors

Performance Testing

# Run comprehensive benchmarks
for type in traverse pattern aggregate; do
  echo "Testing $type..."
  ruvector graph benchmark -b ./db.db -n 10000 -t $type
done

Multi-Graph Management

# Create multiple graphs in same database
ruvector graph query -b ./db.db -q "CREATE DATABASE users"
ruvector graph query -b ./db.db -q "CREATE DATABASE products"

# Import to specific graphs
ruvector graph import -b ./db.db -i users.json -g users
ruvector graph import -b ./db.db -i products.json -g products

# Query specific graph
ruvector graph query -b ./db.db -g users -q "MATCH (n:User) RETURN n"

Server Deployment

# Development server
ruvector graph serve -b ./dev.db --host 127.0.0.1 --http-port 8080

# Production server with GraphQL
ruvector graph serve \
  -b /data/prod.db \
  --host 0.0.0.0 \
  --http-port 8080 \
  --grpc-port 50051 \
  --graphql

Global Options

All graph commands support these global options:

# Use custom config
ruvector --config ./custom-config.toml graph query -q "MATCH (n) RETURN n"

# Enable debug mode
ruvector --debug graph info -b ./db.db

# Disable colors (for scripting)
ruvector --no-color graph query -q "MATCH (n) RETURN n" --format json

Tips and Best Practices

1. Use Short Flags for Common Options:

   • -b for --db (database path)
   • -q for --cypher (query string)
   • -i for --input (import file)
   • -o for --output (export file)
   • -g for --graph (graph name)
   • -n for --queries (benchmark count)
   • -t for --bench-type (benchmark type)

2. Interactive Mode Best Practices:

   • Use --multiline for complex queries
   • End queries with ; in multiline mode
   • Use :clear to reset query buffer
   • Use :help for shell commands

3. Performance:

   • Enable --indexed for large graphs
   • Use benchmarks to test query performance
   • Monitor with --detailed info flag

4. Data Management:

   • Always backup with export before major changes
   • Use --skip-errors for large imports
   • Export to multiple formats for compatibility

Troubleshooting

Command Not Found

# Ensure binary is built
cargo build --package ruvector-cli --bin ruvector

# Use from target directory
./target/debug/ruvector graph --help

Flag Conflicts

Remember that global flags take precedence:

• Use -b for --db (NOT -d, which is --debug)
• Use -q for --cypher (NOT -c, which is --config)

Server Won't Start

# Check if port is in use
lsof -i :8080

# Use different port
ruvector graph serve -b ./db.db --http-port 9000

Next Steps

1. See cli-graph-commands.md for detailed command reference
2. Check neo4j-integration.md for integration details
3. Read configuration.md for advanced settings

Integration Status

Current implementation provides CLI interface with placeholder functions. All commands are ready for integration with the ruvector-neo4j crate for full Neo4j-compatible graph database functionality.

TODO markers in code indicate integration points:

// TODO: Integrate with ruvector-neo4j Neo4jGraph implementation