gigabrain / docs / examples / cli-examples.md

# GigaBrain CLI Examples

This document provides practical examples of using the GigaBrain CLI for various common tasks.

## Getting Started

### Starting the CLI
```bash
# Build the CLI
cargo build --release --bin gigabrain-cli

# Start interactive REPL
./target/release/gigabrain-cli

# Or use shorter commands if in PATH
gigabrain-cli
```

## Basic Graph Operations

### Creating Nodes and Relationships

```cypher
# Create person nodes
gigabrain> CREATE (alice:Person {name: 'Alice', age: 30, email: '[e-mail]'})
gigabrain> CREATE (bob:Person {name: 'Bob', age: 25, email: '[e-mail]'})
gigabrain> CREATE (charlie:Person {name: 'Charlie', age: 35, email: '[e-mail]'})

# Create a company
gigabrain> CREATE (techcorp:Company {name: 'TechCorp', founded: 2010, industry: 'Technology'})

# Create relationships
gigabrain> MATCH (alice:Person {name: 'Alice'}), (bob:Person {name: 'Bob'})
        -> CREATE (alice)-[:KNOWS {since: 2020}]->(bob)

gigabrain> MATCH (alice:Person {name: 'Alice'}), (techcorp:Company {name: 'TechCorp'})
        -> CREATE (alice)-[:WORKS_FOR {position: 'Senior Developer', since: 2022}]->(techcorp)

gigabrain> MATCH (bob:Person {name: 'Bob'}), (techcorp:Company {name: 'TechCorp'})
        -> CREATE (bob)-[:WORKS_FOR {position: 'Junior Developer', since: 2023}]->(techcorp)
```

### Querying Data

```cypher
# Find all people
gigabrain> MATCH (p:Person) RETURN p.name, p.age, p.email

# Find relationships
gigabrain> MATCH (p:Person)-[r:KNOWS]->(friend:Person) 
        -> RETURN p.name as person, friend.name as friend, r.since as since

# Find coworkers
gigabrain> MATCH (p1:Person)-[:WORKS_FOR]->(company:Company)<-[:WORKS_FOR]-(p2:Person)
        -> WHERE p1 <> p2
        -> RETURN p1.name as person1, p2.name as person2, company.name as company

# Complex query with aggregation
gigabrain> MATCH (p:Person)-[:WORKS_FOR]->(c:Company)
        -> RETURN c.name as company, count(p) as employees
        -> ORDER BY employees DESC
```

## Administrative Tasks

### Graph Statistics and Analysis

```bash
# Show basic statistics
gigabrain> :stats

# Analyze graph structure
gigabrain> analyze structure

# Analyze connectivity
gigabrain> analyze connectivity

# Show schema information
gigabrain> :show schema

# Show sample nodes
gigabrain> :show nodes

# Show sample relationships
gigabrain> :show relationships
```

### Performance Analysis

```bash
# Run benchmark
gigabrain> benchmark

# Analyze performance characteristics
gigabrain> analyze performance

# Show memory usage
gigabrain> memory

# Profile a query
gigabrain> profile MATCH (p:Person)-[:KNOWS*1..3]->(friend) RETURN p.name, count(friend)
```

### Database Maintenance

```bash
# Create backup
gigabrain> backup daily_backup_20231201.json

# Optimize database
gigabrain> optimize

# Vacuum (cleanup)
gigabrain> vacuum

# Show connection info
gigabrain> connections
```

## Data Import/Export

### JSON Export/Import

```bash
# Export graph to JSON
gigabrain> :export graph_backup.json

# Import from JSON
gigabrain> :import graph_backup.json

# Using administrative commands
gigabrain> export-json full_export.json
gigabrain> import-json full_export.json
```

### CSV Export/Import

```bash
# Export people to CSV
gigabrain> export-csv people.csv "MATCH (p:Person) RETURN p.name, p.age, p.email"

# Export relationships to CSV
gigabrain> export-csv relationships.csv "MATCH (a)-[r]->(b) RETURN a.name, type(r), b.name"

# Import CSV data
gigabrain> import-csv new_people.csv
```

## Batch Processing

### Command Files

Create a file `setup_social_network.cypher`:
```cypher
# Social network setup script
# Clear existing data
MATCH (n) DETACH DELETE n;

# Create people
CREATE (alice:Person {name: 'Alice', age: 30, city: 'New York'});
CREATE (bob:Person {name: 'Bob', age: 25, city: 'San Francisco'});
CREATE (charlie:Person {name: 'Charlie', age: 35, city: 'Los Angeles'});
CREATE (diana:Person {name: 'Diana', age: 28, city: 'Chicago'});
CREATE (eve:Person {name: 'Eve', age: 32, city: 'Boston'});

# Create friendships
MATCH (alice:Person {name: 'Alice'}), (bob:Person {name: 'Bob'})
CREATE (alice)-[:FRIENDS {since: 2018}]->(bob);

MATCH (bob:Person {name: 'Bob'}), (charlie:Person {name: 'Charlie'})
CREATE (bob)-[:FRIENDS {since: 2019}]->(charlie);

MATCH (charlie:Person {name: 'Charlie'}), (diana:Person {name: 'Diana'})
CREATE (charlie)-[:FRIENDS {since: 2020}]->(diana);

MATCH (diana:Person {name: 'Diana'}), (eve:Person {name: 'Eve'})
CREATE (diana)-[:FRIENDS {since: 2021}]->(eve);

MATCH (eve:Person {name: 'Eve'}), (alice:Person {name: 'Alice'})
CREATE (eve)-[:FRIENDS {since: 2017}]->(alice);

# Create some interests
CREATE (tech:Interest {name: 'Technology'});
CREATE (music:Interest {name: 'Music'});
CREATE (sports:Interest {name: 'Sports'});
CREATE (travel:Interest {name: 'Travel'});

# Connect people to interests
MATCH (alice:Person {name: 'Alice'}), (tech:Interest {name: 'Technology'})
CREATE (alice)-[:INTERESTED_IN]->(tech);

MATCH (alice:Person {name: 'Alice'}), (music:Interest {name: 'Music'})
CREATE (alice)-[:INTERESTED_IN]->(music);

MATCH (bob:Person {name: 'Bob'}), (tech:Interest {name: 'Technology'})
CREATE (bob)-[:INTERESTED_IN]->(tech);

MATCH (bob:Person {name: 'Bob'}), (sports:Interest {name: 'Sports'})
CREATE (bob)-[:INTERESTED_IN]->(sports);

# Show final statistics
MATCH (n) RETURN labels(n)[0] as type, count(n) as count;
```

Execute the file:
```bash
# Run the setup script
./gigabrain-cli --file setup_social_network.cypher

# Run silently for automation
./gigabrain-cli --file setup_social_network.cypher --silent
```

### Analysis Queries File

Create `social_analysis.cypher`:
```cypher
# Social network analysis queries

# Find mutual friends
MATCH (a:Person)-[:FRIENDS]-(mutual)-[:FRIENDS]-(b:Person)
WHERE a <> b AND NOT (a)-[:FRIENDS]-(b)
RETURN a.name as person1, b.name as person2, mutual.name as mutual_friend;

# Find popular interests
MATCH (p:Person)-[:INTERESTED_IN]->(i:Interest)
RETURN i.name as interest, count(p) as popularity
ORDER BY popularity DESC;

# Find people with similar interests
MATCH (p1:Person)-[:INTERESTED_IN]->(i:Interest)<-[:INTERESTED_IN]-(p2:Person)
WHERE p1 <> p2
RETURN p1.name as person1, p2.name as person2, count(i) as shared_interests
ORDER BY shared_interests DESC;

# Find the social network diameter
MATCH path = shortestPath((a:Person)-[:FRIENDS*]-(b:Person))
WHERE a <> b
RETURN a.name as start, b.name as end, length(path) as distance
ORDER BY distance DESC
LIMIT 5;

# Show network statistics
MATCH (p:Person)
OPTIONAL MATCH (p)-[:FRIENDS]-(friend)
RETURN p.name as person, count(friend) as friend_count
ORDER BY friend_count DESC;
```

Run analysis:
```bash
./gigabrain-cli --file social_analysis.cypher --format table
```

## Output Formatting

### Different Output Formats

```bash
# Table format (default)
gigabrain> MATCH (p:Person) RETURN p.name, p.age LIMIT 3
╭────────────┬─────────╮
│    name    │   age   │
├────────────┼─────────┤
│   Alice    │   30    │
│    Bob     │   25    │
│  Charlie   │   35    │
╰────────────┴─────────╯

# Switch to JSON
gigabrain> :format json
gigabrain> MATCH (p:Person) RETURN p.name, p.age LIMIT 3
{"columns": ["p.name", "p.age"], "rows": 3}

# Switch to CSV
gigabrain> :format csv
gigabrain> MATCH (p:Person) RETURN p.name, p.age LIMIT 3
p.name,p.age
Alice,30
Bob,25
Charlie,35

# Switch back to table
gigabrain> :format table
```

### Command Line Format Options

```bash
# JSON output for scripting
./gigabrain-cli --execute "MATCH (p:Person) RETURN count(p)" --format json

# CSV output for data analysis
./gigabrain-cli --execute "MATCH (p:Person) RETURN p.name, p.age" --format csv > people.csv

# Plain output for debugging
./gigabrain-cli --execute ":stats" --format plain
```

## Advanced Examples

### Graph Algorithm Analysis

```cypher
# Create a more complex network for algorithm testing
CREATE (a:Node {id: 'A'}), (b:Node {id: 'B'}), (c:Node {id: 'C'}), 
       (d:Node {id: 'D'}), (e:Node {id: 'E'}), (f:Node {id: 'F'});

CREATE (a)-[:CONNECTS {weight: 1}]->(b),
       (b)-[:CONNECTS {weight: 2}]->(c),
       (c)-[:CONNECTS {weight: 1}]->(d),
       (d)-[:CONNECTS {weight: 3}]->(e),
       (e)-[:CONNECTS {weight: 1}]->(f),
       (f)-[:CONNECTS {weight: 2}]->(a),
       (a)-[:CONNECTS {weight: 4}]->(d),
       (b)-[:CONNECTS {weight: 1}]->(e);

# Find shortest paths
MATCH path = shortestPath((start:Node {id: 'A'})-[:CONNECTS*]-(end:Node {id: 'E'}))
RETURN start.id as start, end.id as end, length(path) as hops;

# Show node connectivity
MATCH (n:Node)
OPTIONAL MATCH (n)-[:CONNECTS]-(connected)
RETURN n.id as node, count(connected) as degree
ORDER BY degree DESC;
```

### Time-Series Data Analysis

```cypher
# Create time-series events
CREATE (user1:User {id: 'user1'}),
       (user2:User {id: 'user2'}),
       (user3:User {id: 'user3'});

CREATE (event1:Event {type: 'login', timestamp: 1640995200}),
       (event2:Event {type: 'purchase', timestamp: 1640995800}),
       (event3:Event {type: 'logout', timestamp: 1640996400});

CREATE (user1)-[:PERFORMED]->(event1),
       (user1)-[:PERFORMED]->(event2),
       (user1)-[:PERFORMED]->(event3);

# Query events by time
MATCH (u:User)-[:PERFORMED]->(e:Event)
WHERE e.timestamp > 1640995000
RETURN u.id as user, e.type as event, e.timestamp as time
ORDER BY time;
```

## Scripting and Automation

### Backup Script

Create `backup.sh`:
```bash
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="gigabrain_backup_${DATE}.json"

echo "Creating backup: ${BACKUP_FILE}"
./gigabrain-cli --execute "backup ${BACKUP_FILE}" --silent

if [ $? -eq 0 ]; then
    echo "Backup completed successfully"
    # Optionally upload to cloud storage
    # aws s3 cp "${BACKUP_FILE}" s3://my-backups/gigabrain/
else
    echo "Backup failed!"
    exit 1
fi
```

### Health Check Script

Create `health_check.sh`:
```bash
#!/bin/bash
STATS=$(./gigabrain-cli --execute ":stats" --format json --silent)
NODE_COUNT=$(echo $STATS | jq -r '.nodes // 0')

if [ "$NODE_COUNT" -gt 0 ]; then
    echo "Database healthy: $NODE_COUNT nodes"
    exit 0
else
    echo "Database issue: No nodes found"
    exit 1
fi
```

### Data Migration Script

Create `migrate_data.cypher`:
```cypher
# Data migration script
# Add new properties to existing nodes
MATCH (p:Person)
WHERE NOT EXISTS(p.created_at)
SET p.created_at = timestamp();

# Create indexes for performance
# Note: Index creation syntax may vary
MATCH (p:Person) WHERE EXISTS(p.email) SET p:EmailUser;

# Update relationship properties
MATCH (p1:Person)-[r:FRIENDS]->(p2:Person)
WHERE NOT EXISTS(r.strength)
SET r.strength = 1.0;

# Show migration results
MATCH (p:Person) 
RETURN 
  count(p) as total_people,
  count(CASE WHEN EXISTS(p.created_at) THEN 1 END) as with_timestamps,
  count(CASE WHEN p:EmailUser THEN 1 END) as email_users;
```

## Troubleshooting Examples

### Performance Issues

```cypher
# Identify slow queries by profiling
gigabrain> profile MATCH (p:Person)-[:FRIENDS*1..5]->(distant) RETURN p.name, count(distant)

# Check memory usage
gigabrain> memory

# Analyze performance characteristics
gigabrain> analyze performance

# Optimize database
gigabrain> optimize
```

### Data Validation

```cypher
# Check for orphaned nodes
MATCH (n)
WHERE NOT (n)--()
RETURN labels(n)[0] as type, count(n) as orphaned_count;

# Validate relationship consistency
MATCH (p:Person)-[r:FRIENDS]->(friend:Person)
WHERE NOT EXISTS((friend)-[:FRIENDS]->(p))
RETURN p.name as person, friend.name as one_way_friend;

# Check for duplicate data
MATCH (p1:Person), (p2:Person)
WHERE p1 <> p2 AND p1.email = p2.email
RETURN p1.name as person1, p2.name as person2, p1.email as duplicate_email;
```

### Debugging Connection Issues

```bash
# Check connection status
gigabrain> connections

# Test basic functionality
gigabrain> CREATE (test:Test {id: 1}) RETURN test

# Clean up test data
gigabrain> MATCH (test:Test) DELETE test

# Show recent logs (if implemented)
gigabrain> logs recent
```

These examples demonstrate the full capabilities of the GigaBrain CLI for interactive use, batch processing, administration, and automation. The CLI provides a powerful interface for both development and production use cases.