sqlitegraph-cli

Command-line interface for SQLiteGraph graph database.

Installation

cargo install sqlitegraph-cli

Or install from source:

git clone https://github.com/oldnordic/sqlitegraph
cd sqlitegraph/sqlitegraph-cli
cargo install --path .

Quick Start

# Create an in-memory graph
sqlitegraph --backend sqlite --db :memory: entity-insert --kind User --name Alice

# Create a file-based graph
sqlitegraph --backend sqlite --db mygraph.db entity-insert --kind User --name Bob

# Use Native V2 backend (high performance)
sqlitegraph --backend native --db mygraph.db entity-insert --kind User --name Charlie

Backend Selection

SQLite Backend (Default)

• Mature, ACID-compliant storage
• WAL mode enabled by default for concurrent performance
• Best for general-purpose use

sqlitegraph --backend sqlite --db mygraph.db [command]

Native V2 Backend

• High-performance clustered adjacency
• Custom binary format for maximum speed
• Best for performance-critical applications

sqlitegraph --backend native --db mygraph.db [command]

Commands

Entity Operations

Insert Entity

sqlitegraph --backend sqlite --db mygraph.db entity-insert \
  --kind User \
  --name "Alice Smith" \
  --file-path "/users/alice" \
  --data '{"age": 30, "city": "NYC"}'

Get Entity

sqlitegraph --backend sqlite --db mygraph.db entity-get --id 1

Update Entity

sqlitegraph --backend sqlite --db mygraph.db entity-update \
  --id 1 \
  --name "Alice Johnson" \
  --data '{"age": 31, "city": "LA"}'

Delete Entity

sqlitegraph --backend sqlite --db mygraph.db entity-delete --id 1

List Entities

# List all entities
sqlitegraph --backend sqlite --db mygraph.db entity-list

# Filter by kind
sqlitegraph --backend sqlite --db mygraph.db entity-list --kind User

# Filter by name pattern
sqlitegraph --backend sqlite --db mygraph.db entity-list --name-pattern "Alice%"

Edge Operations

Insert Edge

sqlitegraph --backend sqlite --db mygraph.db edge-insert \
  --from-id 1 \
  --to-id 2 \
  --type "knows" \
  --data '{"since": 2020}'

Get Edge

sqlitegraph --backend sqlite --db mygraph.db edge-get --id 1

Update Edge

sqlitegraph --backend sqlite --db mygraph.db edge-update \
  --id 1 \
  --type "knows" \
  --data '{"since": 2019, "strength": "strong"}'

Delete Edge

sqlitegraph --backend sqlite --db mygraph.db edge-delete --id 1

List Edges

# List all edges
sqlitegraph --backend sqlite --db mygraph.db edge-list

# Edges from entity
sqlitegraph --backend sqlite --db mygraph.db edge-list --from-id 1

# Edges to entity
sqlitegraph --backend sqlite --db mygraph.db edge-list --to-id 2

# Filter by type
sqlitegraph --backend sqlite --db mygraph.db edge-list --type knows

Query Operations

Neighbors

# Get outgoing neighbors
sqlitegraph --backend sqlite --db mygraph.db neighbors \
  --entity-id 1 \
  --direction outgoing

# Get incoming neighbors
sqlitegraph --backend sqlite --db mygraph.db neighbors \
  --entity-id 1 \
  --direction incoming

# Get all neighbors
sqlitegraph --backend sqlite --db mygraph.db neighbors \
  --entity-id 1 \
  --direction both

K-Hop Query

sqlitegraph --backend sqlite --db mygraph.db k-hop \
  --entity-id 1 \
  --max-depth 2 \
  --max-results 100

BFS Traversal

sqlitegraph --backend sqlite --db mygraph.db bfs \
  --start-entity-id 1 \
  --max-depth 3

Bulk Operations

Bulk Insert

# Insert from JSON file
sqlitegraph --backend sqlite --db mygraph.db bulk-insert \
  --input entities.json

# Input format:
# {
#   "entities": [
#     {"kind": "User", "name": "Alice", "data": {"age": 30}},
#     {"kind": "User", "name": "Bob", "data": {"age": 25}}
#   ],
#   "edges": [
#     {"from": 0, "to": 1, "type": "knows", "data": {}}
#   ]
# }

Snapshot Export

sqlitegraph --backend sqlite --db mygraph.db snapshot-export \
  --output /backups/graph.snapshot

Snapshot Import

sqlitegraph --backend sqlite --db mygraph.db snapshot-import \
  --input /backups/graph.snapshot

HNSW Vector Search Commands

The CLI provides HNSW vector search commands for testing and development.

Important: HNSW indexes do not persist across CLI invocations. Each CLI command creates a new database connection with empty HNSW storage. For persistent vector search functionality, use the Rust API directly in your application.

Create HNSW Index

sqlitegraph --backend sqlite --db :memory: hnsw-create \
  --dimension 768 \
  --m 16 \
  --ef-construction 200 \
  --ef-search 50 \
  --distance-metric cosine

Insert Vectors

# Create JSON file with vectors
cat > vectors.json <<EOF
{
  "vectors": [
    {
      "id": "vec1",
      "vector": [0.1, 0.2, 0.3],
      "metadata": {"label": "sample1"}
    },
    {
      "id": "vec2",
      "vector": [0.4, 0.5, 0.6],
      "metadata": {"label": "sample2"}
    }
  ]
}
EOF

# Insert vectors
sqlitegraph --backend sqlite --db :memory: hnsw-insert --input vectors.json

Search Vectors

# Create query file
cat > query.json <<EOF
{
  "vector": [0.15, 0.25, 0.35],
  "k": 5
}
EOF

# Search
sqlitegraph --backend sqlite --db :memory: hnsw-search --input query.json

Get Statistics

sqlitegraph --backend sqlite --db :memory: hnsw-stats

Note on Persistence: The HNSW CLI commands are useful for single-session testing. For production use with persistent vector indexes, use the sqlitegraph Rust library API.

Utility Commands

Statistics

sqlitegraph --backend sqlite --db mygraph.db stats

Export Schema

sqlitegraph --backend sqlite --db mygraph.db schema-export

Validate Graph

sqlitegraph --backend sqlite --db mygraph.db validate

Output Formats

Most commands output JSON by default:

{
  "status": "success",
  "entity_id": 1,
  "kind": "User",
  "name": "Alice",
  "data": {"age": 30}
}

Use jq for pretty-printing:

sqlitegraph --backend sqlite --db mygraph.db entity-get --id 1 | jq '.'

Exit Codes

• 0 - Success
• 1 - Error (check error message in JSON output)

Examples

Social Network

# Create graph
sqlitegraph --backend sqlite --db social.db entity-insert --kind User --name Alice
sqlitegraph --backend sqlite --db social.db entity-insert --kind User --name Bob
sqlitegraph --backend sqlite --db social.db entity-insert --kind User --name Charlie

# Create connections
sqlitegraph --backend sqlite --db social.db edge-insert --from-id 1 --to-id 2 --type "friend"
sqlitegraph --backend sqlite --db social.db edge-insert --from-id 2 --to-id 3 --type "friend"

# Find friends of friends
sqlitegraph --backend sqlite --db social.db neighbors --entity-id 1 --direction outgoing
sqlitegraph --backend sqlite --db social.db bfs --start-entity-id 1 --max-depth 2

Knowledge Graph

# Create entities
sqlitegraph --backend sqlite --db knowledge.db entity-insert --kind Concept --name "Graph"
sqlitegraph --backend sqlite --db knowledge.db entity-insert --kind Concept --name "Database"
sqlitegraph --backend sqlite --db knowledge.db entity-insert --kind Concept --name "SQL"

# Link concepts
sqlitegraph --backend sqlite --db knowledge.db edge-insert --from-id 1 --to-id 2 --type "related-to"
sqlitegraph --backend sqlite --db knowledge.db edge-insert --from-id 2 --to-id 3 --type "uses"

# Query relationships
sqlitegraph --backend sqlite --db knowledge.db k-hop --entity-id 1 --max-depth 2

Performance Tips

1. Use Native V2 backend for high-performance scenarios
2. Enable WAL mode (automatic for SQLite backend with file databases)
3. Use bulk operations for inserting large datasets
4. Use snapshot export/import for fast backups

Limitations

HNSW CLI Commands

• HNSW indexes do not persist across CLI invocations
• Each command creates a new process with empty HNSW storage
• For persistent HNSW functionality, use the Rust API

General CLI

• Single-threaded operations
• No interactive mode
• Limited error recovery options

See Also

• sqlitegraph Library - Rust library API
• SQLiteGraph GitHub - Source code
• Documentation - API documentation

License

GPL-3.0-or-later