Skip to content

Latest commit

 

History

History
306 lines (224 loc) · 7.84 KB

cli-graph-commands.md

File metadata and controls

306 lines (224 loc) · 7.84 KB

RuVector CLI - Graph Database Commands

The RuVector CLI now includes comprehensive graph database support with Neo4j-compatible Cypher query capabilities.

Available Graph Commands

1. Create Graph Database

Create a new graph database with optional property indexing.

ruvector graph create --path ./my-graph.db --name my-graph --indexed

Options:

  • --path, -p - Database file path (default: ./ruvector-graph.db)
  • --name, -n - Graph name (default: default)
  • --indexed - Enable property indexing for faster queries

2. Execute Cypher Query

Run a Cypher query against the graph database.

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

Options:

  • --db, -b - Database file path (default: ./ruvector-graph.db)
  • --cypher, -q - Cypher query to execute
  • --format - Output format: table, json, or csv (default: table)
  • --explain - Show query execution plan

Note: Use -b for database (NOT -d, which is for --debug) and -q for query (NOT -c, which is for --config)

Examples:

# Create a node
ruvector graph query -q "CREATE (n:Person {name: 'Alice', age: 30})"

# Find nodes
ruvector graph query -q "MATCH (n:Person) WHERE n.age > 25 RETURN n"

# Create relationships
ruvector graph query -q "MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) CREATE (a)-[:KNOWS]->(b)"

# Pattern matching
ruvector graph query -q "MATCH (a)-[r:KNOWS]->(b) RETURN a.name, b.name"

# Get execution plan
ruvector graph query -q "MATCH (n:Person) RETURN n" --explain

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

3. Interactive Cypher Shell (REPL)

Start an interactive shell for executing Cypher queries.

ruvector graph shell --db ./my-graph.db --multiline

Options:

  • --db, -b - Database file path (default: ./ruvector-graph.db)
  • --multiline - Enable multiline mode (queries end with ;)

Shell Commands:

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

Example Session:

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

cypher> CREATE (n:Person {name: 'Alice'})
✓ Query completed in 12.34ms

cypher> MATCH (n:Person) RETURN n.name
+--------+
| n.name |
+--------+
| Alice  |
+--------+

cypher> :exit
✓ Goodbye!

4. Import Graph Data

Import data from CSV, JSON, or Cypher files.

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

Options:

  • --db, -b - Database file path (default: ./ruvector-graph.db)
  • --input, -i - Input file path
  • --format - Input format: csv, json, or cypher (default: json)
  • --graph, -g - Graph name (default: default)
  • --skip-errors - Continue on errors

JSON Format Example:

{
  "nodes": [
    {
      "id": "1",
      "labels": ["Person"],
      "properties": {"name": "Alice", "age": 30}
    }
  ],
  "relationships": [
    {
      "id": "1",
      "type": "KNOWS",
      "startNode": "1",
      "endNode": "2",
      "properties": {"since": 2020}
    }
  ]
}

CSV Format:

  • Nodes: nodes.csv with columns: id,labels,properties
  • Relationships: relationships.csv with columns: id,type,start,end,properties

Cypher Format: Plain text file with Cypher CREATE statements.

5. Export Graph Data

Export graph data to various formats.

ruvector graph export -b ./my-graph.db -o backup.json --format json

Options:

  • --db, -b - Database file path (default: ./ruvector-graph.db)
  • --output, -o - Output file path
  • --format - Output format: json, csv, cypher, or graphml (default: json)
  • --graph, -g - Graph name (default: default)

Output Formats:

  • json - JSON graph format (nodes and relationships)
  • csv - Separate CSV files for nodes and relationships
  • cypher - Cypher CREATE statements
  • graphml - GraphML XML format for visualization tools

6. Graph Database Info

Display statistics and information about the graph database.

ruvector graph info -b ./my-graph.db --detailed

Options:

  • --db, -b - Database file path (default: ./ruvector-graph.db)
  • --detailed - Show detailed statistics including storage and configuration

Example 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. Graph Benchmarks

Run performance benchmarks on the graph database.

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

Options:

  • --db, -b - Database file path (default: ./ruvector-graph.db)
  • --queries, -n - Number of queries to run (default: 1000)
  • --bench-type, -t - Benchmark type: traverse, pattern, or aggregate (default: traverse)

Benchmark Types:

  • traverse - Graph traversal operations
  • pattern - Pattern matching queries
  • aggregate - Aggregation queries

Example 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

Start an HTTP/gRPC server for remote graph access.

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

Options:

  • --db, -b - Database file path (default: ./ruvector-graph.db)
  • --host - Server host (default: 127.0.0.1)
  • --http-port - HTTP port (default: 8080)
  • --grpc-port - gRPC port (default: 50051)
  • --graphql - Enable GraphQL endpoint

Endpoints:

  • HTTP: http://localhost:8080/query - Execute Cypher queries via HTTP POST
  • gRPC: localhost:50051 - High-performance RPC interface
  • GraphQL: http://localhost:8080/graphql - GraphQL endpoint (if enabled)

Integration with RuVector Neo4j

These CLI commands are designed to work seamlessly with the ruvector-neo4j crate for full Neo4j-compatible graph database functionality. The current implementation provides placeholder functionality that will be integrated with the actual graph database implementation.

Common Workflows

Building a Social Network Graph

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

# Start shell
ruvector graph shell --db social.db

# In the shell:
CREATE (alice:Person {name: 'Alice', age: 30})
CREATE (bob:Person {name: 'Bob', age: 25})
CREATE (carol:Person {name: 'Carol', age: 28})
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)

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

Import and Export

# Import from JSON
ruvector graph import -b mydb.db -i data.json --format json

# Export to Cypher for backup
ruvector graph export -b mydb.db -o backup.cypher --format cypher

# Export to GraphML for visualization
ruvector graph export -b mydb.db -o graph.graphml --format graphml

Performance Testing

# Run traversal benchmark
ruvector graph benchmark -b mydb.db -n 10000 -t traverse

# Run pattern matching benchmark
ruvector graph benchmark -b mydb.db -n 5000 -t pattern

Global Options

All graph commands support these global options (inherited from main CLI):

  • --config, -c - Configuration file path
  • --debug, -d - Enable debug mode
  • --no-color - Disable colored output

See Also