VelesDB CLI

Interactive CLI and REPL for VelesDB with VelesQL support.

Installation

From crates.io

cargo install velesdb-cli

From source

git clone https://github.com/cyberlife-coder/VelesDB
cd VelesDB
cargo install --path crates/velesdb-cli

Usage

Interactive REPL

# Start interactive REPL with default data directory (./data)
velesdb repl

# Or specify a data directory
velesdb repl ./my_vectors

Single Query Execution

# Execute a query directly
velesdb query ./my_vectors "SELECT * FROM documents LIMIT 10"

# Output as JSON
velesdb query ./my_vectors "SELECT * FROM documents LIMIT 5" --format json

Database Info

velesdb info ./my_vectors

List Collections

# List all collections
velesdb list ./my_vectors

# Output as JSON
velesdb list ./my_vectors --format json

Show Collection Details

# Show collection schema and stats
velesdb show ./my_vectors documents

# Show with sample records
velesdb show ./my_vectors documents --samples 5

Import/Export

# Export collection to JSON
velesdb export ./my_vectors documents --output documents.json

# Export without vectors (metadata only)
velesdb export ./my_vectors documents --output meta.json --include-vectors false

# Import from JSONL file
velesdb import data.jsonl --database ./my_vectors --collection documents --dimension 768

# Import from CSV
velesdb import embeddings.csv --database ./my_vectors --collection docs --dimension 384

VelesQL Queries

Vector Search

-- Vector similarity search (uses collection's metric)
SELECT * FROM documents 
WHERE VECTOR NEAR [0.15, 0.25, ...] 
LIMIT 5;

-- With parameter (for API usage)
SELECT * FROM documents 
WHERE VECTOR NEAR $query_vector
LIMIT 10;

ℹ️ Note: The distance metric is defined at collection creation time and cannot be changed per-query. All 5 metrics (Cosine, Euclidean, DotProduct, Hamming, Jaccard) are supported.

Metadata Filtering

Metadata is stored as JSON. Query any field with SQL operators:

-- Equality
SELECT * FROM docs WHERE category = 'tech' LIMIT 10;

-- Numeric comparisons
SELECT * FROM docs WHERE views > 1000 LIMIT 10;
SELECT * FROM docs WHERE price >= 50 AND price <= 200 LIMIT 10;

-- String patterns
SELECT * FROM docs WHERE title LIKE '%rust%' LIMIT 10;

-- IN list
SELECT * FROM docs WHERE status IN ('published', 'featured') LIMIT 10;

-- BETWEEN range
SELECT * FROM docs WHERE score BETWEEN 0.5 AND 1.0 LIMIT 10;

-- NULL checks
SELECT * FROM docs WHERE author IS NOT NULL LIMIT 10;

-- Full-text search (BM25)
SELECT * FROM docs WHERE content MATCH 'rust programming' LIMIT 10;

Combined Queries (Vector + Metadata + Text)

-- Vector search + metadata filter
SELECT * FROM documents 
WHERE VECTOR NEAR [0.15, 0.25, ...] 
AND category = 'tech' 
AND views > 100
LIMIT 5;

-- Hybrid search (vector + full-text)
SELECT * FROM documents
WHERE VECTOR NEAR $query 
AND content MATCH 'rust'
LIMIT 5;

-- Complex conditions
SELECT * FROM products
WHERE VECTOR NEAR COSINE [0.1, 0.2, ...]
AND (category = 'electronics' OR category = 'gadgets')
AND price BETWEEN 100 AND 500
AND in_stock = true
LIMIT 10;

Available Filter Operators

Dot Commands

Features

• VelesQL Support: SQL-like syntax for vector operations
• Tab Completion: Auto-complete collection names and keywords
• Command History: Arrow keys to navigate history
• Colored Output: Easy-to-read formatted results
• Timing: Query execution time display

Examples

Semantic Search

-- Search with metadata filter
SELECT id, score, payload->title FROM articles
WHERE VECTOR NEAR $query_embedding
AND category = 'technology'
LIMIT 5;

-- Search with multiple conditions
SELECT * FROM documents
WHERE VECTOR NEAR [0.1, 0.2, 0.3, ...]
AND status = 'published'
AND views > 1000
LIMIT 10;

Binary Vector Search

-- Find similar binary vectors (fingerprints, hashes)
SELECT * FROM images
WHERE VECTOR NEAR [1.0, 0.0, 1.0, 1.0, 0.0, ...]
LIMIT 10;

Creating Collections (via Rust API)

Collections are created programmatically, not via VelesQL:

use velesdb_core::{Database, DistanceMetric};

let db = Database::open("./data")?;
db.create_collection("articles", 384, DistanceMetric::Cosine)?;
db.create_collection("images", 256, DistanceMetric::Hamming)?;

License

Elastic License 2.0 (ELv2)

See LICENSE for details.