Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
RuVector-Postgres
The most advanced PostgreSQL vector database extension. A drop-in pgvector replacement with 290+ SQL functions, SIMD acceleration, 39 attention mechanisms, GNN layers, hyperbolic embeddings, mincut-gated transformers, hybrid search, multi-tenancy, self-healing, and self-learning capabilities.
v2.0.0 Highlights (December 2025)
- Mincut-Gated Transformers: Ultra-low-latency inference with coherence control via λ signals
- Hybrid Search: Vector + BM25 fusion with RRF and linear blending
- Multi-Tenancy: Row-level security with automatic tenant isolation
- Self-Healing: Automated index repair with integrity validation
- Integrity Control: Stoer-Wagner mincut-based quality assurance
- IVFFlat Index: Full inverted list storage with proper page management
- HNSW Index: Fixed query execution with heap scan integration
- Security Audit: 3 critical SQL injection vulnerabilities fixed
- GNN Module: Complete Graph Neural Network operators
Why RuVector?
| Feature | pgvector | RuVector-Postgres |
|---|---|---|
| Vector Search | HNSW, IVFFlat | HNSW, IVFFlat (optimized) |
| Distance Metrics | 3 | 8+ (including hyperbolic) |
| Local Embeddings | - | 6 models (fastembed) |
| Attention Mechanisms | - | 39 types |
| Gated Transformers | - | Mincut-coherence control |
| Hybrid Search | - | RRF + Linear fusion |
| Graph Neural Networks | - | GCN, GraphSAGE, GAT |
| Hyperbolic Embeddings | - | Poincare, Lorentz |
| Sparse Vectors / BM25 | Partial | Full support |
| Multi-Tenancy | - | Row-level isolation |
| Self-Healing | - | Auto index repair |
| Integrity Control | - | Stoer-Wagner mincut |
| Self-Learning | - | ReasoningBank |
| Neural DAG Learning | - | 59 SQL functions |
| Agent Routing | - | Tiny Dancer |
| Graph/Cypher | - | Full support |
| SPARQL/RDF | - | W3C SPARQL 1.1 |
| AVX-512/NEON SIMD | Partial | Full |
| Quantization | No | Scalar, Product, Binary |
Installation
Docker (Recommended)
# Start the container
# Connect with psql
PGPASSWORD=secret
# Or use the ruvector app user (created automatically)
PGPASSWORD=ruvector
The container initializes with:
- Extension
ruvectorpre-installed and tested - User
ruvectorwith passwordruvectorfor application use - SIMD acceleration (AVX2/AVX-512) auto-detected
npm (Node.js Bindings)
# Install the core package with native bindings
# Or install the full ruvector package
const = require;
// Create a vector database
const db = ;
// Add vectors
db.;
// Search
const results = db.;
From Source
# Install pgrx
# Build and install
CLI Tool
Quick Start
-- Create the extension
CREATE EXTENSION ruvector;
-- Create a table with vector column
(
id SERIAL PRIMARY KEY,
content TEXT,
embedding ruvector(1536)
);
-- Create an HNSW index
(embedding ruvector_l2_ops);
-- Find similar documents
SELECT content, embedding <-> '[0.15, 0.25, ...]'::ruvector AS distance
FROM documents
ORDER BY distance
LIMIT 10;
290+ SQL Functions
RuVector exposes all advanced AI capabilities as native PostgreSQL functions.
Core Vector Operations
-- Distance metrics
SELECT ruvector_cosine_distance(a, b);
SELECT ruvector_l2_distance(a, b);
SELECT ruvector_inner_product(a, b);
SELECT ruvector_manhattan_distance(a, b);
-- Vector operations
SELECT ruvector_normalize(embedding);
SELECT ruvector_add(a, b);
SELECT ruvector_scalar_mul(embedding, 2.0);
Hyperbolic Geometry (8 functions)
Perfect for hierarchical data like taxonomies, knowledge graphs, and org charts.
-- Poincare ball model
SELECT ruvector_poincare_distance(a, b, -1.0); -- curvature -1
-- Lorentz hyperboloid model
SELECT ruvector_lorentz_distance(a, b, -1.0);
-- Hyperbolic operations
SELECT ruvector_mobius_add(a, b, -1.0); -- Hyperbolic translation
SELECT ruvector_exp_map(base, tangent, -1.0); -- Tangent to manifold
SELECT ruvector_log_map(base, target, -1.0); -- Manifold to tangent
-- Model conversion
SELECT ruvector_poincare_to_lorentz(poincare_vec, -1.0);
SELECT ruvector_lorentz_to_poincare(lorentz_vec, -1.0);
-- Minkowski inner product
SELECT ruvector_minkowski_dot(a, b);
Sparse Vectors & BM25 (14 functions)
Full sparse vector support with text scoring.
-- Create sparse vectors
SELECT ruvector_sparse_create(ARRAY[0, 5, 10], ARRAY[0.5, 0.3, 0.2], 100);
SELECT ruvector_sparse_from_dense(dense_vector, 0.01); -- threshold
-- Sparse operations
SELECT ruvector_sparse_dot(a, b);
SELECT ruvector_sparse_cosine(a, b);
SELECT ruvector_sparse_l2_distance(a, b);
SELECT ruvector_sparse_add(a, b);
SELECT ruvector_sparse_scale(vec, 2.0);
SELECT ruvector_sparse_normalize(vec);
SELECT ruvector_sparse_topk(vec, 10); -- Top-k elements
-- Text scoring
SELECT ruvector_bm25_score(query_terms, doc_freqs, doc_len, avg_doc_len, total_docs);
SELECT ruvector_tf_idf(term_freq, doc_freq, total_docs);
39 Attention Mechanisms
Full transformer-style attention in PostgreSQL.
-- Scaled dot-product attention
SELECT ruvector_attention_scaled_dot(query, keys, values);
-- Multi-head attention
SELECT ruvector_attention_multi_head(query, keys, values, num_heads);
-- Flash attention (memory efficient)
SELECT ruvector_attention_flash(query, keys, values, block_size);
-- Sparse attention patterns
SELECT ruvector_attention_sparse(query, keys, values, sparsity_pattern);
-- Linear attention (O(n) complexity)
SELECT ruvector_attention_linear(query, keys, values);
-- Causal/masked attention
SELECT ruvector_attention_causal(query, keys, values);
-- Cross attention
SELECT ruvector_attention_cross(query, context_keys, context_values);
-- Self attention
SELECT ruvector_attention_self(input, num_heads);
Graph Neural Networks (5 functions)
GNN layers for graph-structured data.
-- GCN (Graph Convolutional Network)
SELECT ruvector_gnn_gcn_layer(features, adjacency, weights);
-- GraphSAGE (inductive learning)
SELECT ruvector_gnn_graphsage_layer(features, neighbor_features, weights);
-- GAT (Graph Attention Network)
SELECT ruvector_gnn_gat_layer(features, adjacency, attention_weights);
-- Message passing
SELECT ruvector_gnn_message_pass(node_features, edge_index, edge_weights);
-- Aggregation
SELECT ruvector_gnn_aggregate(messages, aggregation_type); -- mean, max, sum
Agent Routing - Tiny Dancer (11 functions)
Intelligent query routing to specialized AI agents.
-- Route query to best agent
SELECT ruvector_route_query(query_embedding, agent_registry);
-- Route with context
SELECT ruvector_route_with_context(query, context, agents);
-- Multi-agent routing
SELECT ruvector_multi_agent_route(query, agents, top_k);
-- Agent management
SELECT ruvector_register_agent(name, capabilities, embedding);
SELECT ruvector_update_agent_performance(agent_id, metrics);
SELECT ruvector_get_routing_stats;
-- Affinity calculation
SELECT ruvector_calculate_agent_affinity(query, agent);
SELECT ruvector_select_best_agent(query, agent_list);
-- Adaptive routing
SELECT ruvector_adaptive_route(query, context, learning_rate);
-- FastGRNN acceleration
SELECT ruvector_fastgrnn_forward(input, hidden, weights);
Local Embeddings (6 functions)
Generate embeddings directly in PostgreSQL - no external API calls needed.
-- Generate embedding from text (default: all-MiniLM-L6-v2)
SELECT ruvector_embed('Hello, world!');
-- Use specific model
SELECT ruvector_embed('Hello, world!', 'bge-small-en-v1.5');
-- Batch embedding (efficient for multiple texts)
SELECT ruvector_embed_batch(ARRAY['First doc', 'Second doc', 'Third doc']);
-- List available models
SELECT ruvector_list_models;
-- Get model information (dimensions, description)
SELECT ruvector_model_info('all-MiniLM-L6-v2');
-- Preload model into cache for faster subsequent calls
SELECT ruvector_preload_model('bge-base-en-v1.5');
Supported Models:
| Model | Dimensions | Use Case |
|---|---|---|
all-MiniLM-L6-v2 |
384 | Fast, general-purpose (default) |
bge-small-en-v1.5 |
384 | MTEB #1, English |
bge-base-en-v1.5 |
768 | Higher accuracy, English |
bge-large-en-v1.5 |
1024 | Highest accuracy, English |
nomic-embed-text-v1 |
768 | Long context (8192 tokens) |
nomic-embed-text-v1.5 |
768 | Updated long context |
Example: Automatic Embedding on Insert
-- Create table with trigger for auto-embedding
(
id SERIAL PRIMARY KEY,
title TEXT,
content TEXT,
embedding ruvector(384)
);
-- Insert with automatic embedding generation
INSERT INTO articles (title, content, embedding)
VALUES (
'Introduction to AI',
'Artificial intelligence is transforming...',
ruvector_embed('Artificial intelligence is transforming...')
);
-- Semantic search
SELECT title, embedding <=> ruvector_embed('machine learning basics') AS distance
FROM articles
ORDER BY distance
LIMIT 5;
Self-Learning / ReasoningBank (7 functions)
Adaptive search parameter optimization.
-- Record learning trajectory
SELECT ruvector_record_trajectory(input, output, success, context);
-- Get verdict on approach
SELECT ruvector_get_verdict(trajectory_id);
-- Memory distillation
SELECT ruvector_distill_memory(trajectories, compression_ratio);
-- Adaptive search
SELECT ruvector_adaptive_search(query, context, ef_search);
-- Learning feedback
SELECT ruvector_learning_feedback(search_id, relevance_scores);
-- Get learned patterns
SELECT ruvector_get_learning_patterns(context);
-- Optimize search parameters
SELECT ruvector_optimize_search_params(query_type, historical_data);
Neural DAG Learning (59 functions)
Query optimization with neural self-learning DAG analysis. The system learns from query patterns and automatically optimizes execution plans.
-- Configuration
SELECT rudag_set_config(
learning_rate := 0.01,
attention_mechanism := 'mincut_gated',
trajectory_capacity := 10000,
ewc_lambda := 5000.0
);
SELECT rudag_get_config;
SELECT rudag_reset_config;
-- DAG Analysis
SELECT rudag_analyze_query('SELECT * FROM vectors WHERE embedding <-> $1 < 0.5');
SELECT rudag_get_bottlenecks(query_id);
SELECT rudag_compute_critical_path(query_id);
SELECT rudag_estimate_cost(query_id);
-- Attention Mechanisms (7 types)
SELECT rudag_attention_topological(query_id); -- Position-based
SELECT rudag_attention_causal_cone(query_id); -- Downstream impact
SELECT rudag_attention_critical_path(query_id); -- Latency focus
SELECT rudag_attention_mincut_gated(query_id); -- Flow-aware (default)
SELECT rudag_attention_hierarchical(query_id); -- Deep hierarchies
SELECT rudag_attention_parallel_branch(query_id); -- Wide execution
SELECT rudag_attention_temporal(query_id); -- Time-series
-- Learning Status
SELECT rudag_status; -- Current learning state
SELECT rudag_pattern_count; -- Learned patterns
SELECT rudag_trajectory_count; -- Recorded trajectories
SELECT rudag_get_statistics; -- Comprehensive stats
-- Pattern Management
SELECT rudag_get_patterns(limit_n := 100);
SELECT rudag_search_patterns(query_embedding, top_k := 10);
SELECT rudag_export_patterns; -- JSON export
SELECT rudag_import_patterns(json_data);
-- Trajectory Recording
SELECT rudag_record_trajectory(query_id, execution_time, baseline_time);
SELECT rudag_get_trajectories(limit_n := 100);
SELECT rudag_clear_trajectories;
-- Background Learning
SELECT rudag_trigger_learning; -- Force learning cycle
SELECT rudag_get_learning_progress;
-- Self-Healing Integration
SELECT rudag_healing_status;
SELECT rudag_detect_anomalies;
SELECT rudag_trigger_repair(strategy := 'reindex');
SELECT rudag_get_repair_history;
-- QuDAG Distributed Learning (quantum-resistant)
SELECT rudag_qudag_status; -- Network connection status
SELECT rudag_qudag_sync_patterns; -- Sync with network
SELECT rudag_qudag_receive_patterns; -- Get network patterns
SELECT rudag_qudag_get_peers; -- Connected peers
SELECT rudag_qudag_stake_info; -- rUv token staking
SELECT rudag_qudag_governance_vote(proposal_id, approve := true);
Key Features:
- MinCut as Control Signal: Bottleneck tension drives attention switching and healing
- SONA Learning: MicroLoRA adaptation (<100μs) with EWC++ catastrophic forgetting prevention
- 7 Attention Mechanisms: Auto-selected based on query characteristics and MinCut stress
- Predictive Healing: Rising cut tension triggers early intervention before failures
- QuDAG Integration: Distributed pattern learning with ML-KEM-768 quantum-resistant crypto
Graph Storage & Cypher (8 functions)
Graph operations with Cypher query support.
-- Create graph elements
SELECT ruvector_graph_create_node(labels, properties, embedding);
SELECT ruvector_graph_create_edge(from_node, to_node, edge_type, properties);
-- Graph queries
SELECT ruvector_graph_get_neighbors(node_id, edge_type, depth);
SELECT ruvector_graph_shortest_path(start_node, end_node);
SELECT ruvector_graph_pagerank(edge_table, damping, iterations);
-- Cypher queries
SELECT ruvector_cypher_query('MATCH (n:Person)-[:KNOWS]->(m) RETURN n, m');
-- Traversal
SELECT ruvector_graph_traverse(start_node, direction, max_depth);
-- Similarity search on graph
SELECT ruvector_graph_similarity_search(query_embedding, node_type, top_k);
SPARQL & RDF (14 functions)
W3C-standard SPARQL 1.1 query language for RDF data.
-- Create RDF triple store
SELECT ruvector_create_rdf_store('knowledge_graph');
-- Insert triples
SELECT ruvector_insert_triple(
'knowledge_graph',
'<http://example.org/person/1>',
'<http://www.w3.org/1999/02/22-rdf-syntax-ns#type>',
'<http://example.org/Person>'
);
-- Bulk load N-Triples
SELECT ruvector_load_ntriples('knowledge_graph', '
<http://example.org/person/1> <http://xmlns.com/foaf/0.1/name> "Alice" .
<http://example.org/person/1> <http://xmlns.com/foaf/0.1/knows> <http://example.org/person/2> .
');
-- SPARQL SELECT query
SELECT ruvector_sparql('knowledge_graph', '
PREFIX foaf: <http://xmlns.com/foaf/0.1/>
SELECT ?person ?name
WHERE {
?person a <http://example.org/Person> .
?person foaf:name ?name .
}
', 'json');
-- SPARQL ASK query
SELECT ruvector_sparql('knowledge_graph',
'ASK { <http://example.org/person/1> ?p ?o }',
'json'
);
-- Get store statistics
SELECT ruvector_rdf_stats('knowledge_graph');
-- Query triples by pattern (NULL = wildcard)
SELECT ruvector_query_triples('knowledge_graph',
NULL, -- any subject
'<http://xmlns.com/foaf/0.1/name>', -- predicate
NULL -- any object
);
-- SPARQL UPDATE operations
SELECT ruvector_sparql_update('knowledge_graph', '
INSERT DATA {
<http://example.org/person/3> <http://xmlns.com/foaf/0.1/name> "Charlie" .
}
');
SPARQL Features:
- SELECT, CONSTRUCT, ASK, DESCRIBE query forms
- Property paths (sequence
/, alternative|, inverse^, transitive*,+) - FILTER expressions with 50+ built-in functions
- Aggregates (COUNT, SUM, AVG, MIN, MAX, GROUP_CONCAT)
- OPTIONAL, UNION, MINUS graph patterns
- Named graphs support
- Result formats: JSON, XML, CSV, TSV
- ~198K triples/sec insertion, ~5.5M queries/sec lookups
Gated Transformers (13 functions)
Ultra-low-latency transformer inference with mincut-gated coherence control.
-- Get gate decision from integrity mincut signals
SELECT gated_transformer_gate_decision(
lambda := 150, -- Current mincut value
lambda_prev := 160, -- Previous mincut
boundary_count := 5, -- Witness edge count
layer := 3 -- Current transformer layer
);
-- Returns: {"decision": "Allow", "reason": "None", "tier": 3, ...}
-- Check early exit conditions
SELECT gated_transformer_early_exit_check(
lambda := 180,
layer := 8,
total_layers := 12
);
-- Returns: {"can_exit": true, "confidence": 0.92, "exit_layer": 8, ...}
-- Mixture-of-Depths token routing (50% FLOPs reduction)
SELECT gated_transformer_route_tokens(
lambda := 150,
token_count := 512,
layer_capacity := 0.5 -- Route only 50% of tokens through compute
);
-- Returns: [{"index": 0, "route": "Compute"}, {"index": 1, "route": "Skip"}, ...]
-- Configuration management
SELECT gated_transformer_config; -- Get current config
SELECT gated_transformer_set_config(
lambda_min := 50,
lambda_critical := 20,
check_interval := 64
);
-- Policy management
SELECT gated_transformer_gate_policy; -- Get current policy
SELECT gated_transformer_set_policy(
enable_tiering := true,
enable_kv_flush := true,
enable_freeze := false
);
-- Bridge with integrity module
SELECT gated_transformer_from_integrity('my_hnsw_index');
-- Get combined coherence score
SELECT gated_transformer_coherence_score(
lambda := 150,
lambda_prev := 160,
boundary_count := 5
);
-- Returns: 0.875 (normalized 0-1 coherence)
Gated Transformer Features:
- Dynamic Compute Allocation: Mixture-of-Depths routes tokens for 50% FLOPs reduction
- Early Exit: Layer-skipping with 30-50% latency reduction when coherence is high
- Tiered Decisions: 5 tiers from Full→Reduced→Conservative→Minimal→Critical
- KV-Cache Management: Automatic flush/freeze based on coherence signals
- Boundary Detection: Witness edge tracking for structural integrity
Hybrid Search (7 functions)
Vector + keyword fusion with multiple ranking strategies.
-- Linear fusion (alpha blending)
SELECT ruvector_hybrid_linear(
vector_results, -- Array of (id, score) from vector search
keyword_results, -- Array of (id, score) from BM25
alpha := 0.7 -- 0.7 vector weight, 0.3 keyword weight
);
-- Reciprocal Rank Fusion (RRF)
SELECT ruvector_hybrid_rrf(
vector_results,
keyword_results,
k := 60 -- RRF constant
);
-- Combined search with auto-fusion
SELECT ruvector_hybrid_search(
query_text := 'machine learning optimization',
query_embedding := $embedding,
table_name := 'documents',
text_column := 'content',
vector_column := 'embedding',
limit_k := 10
);
-- Get/Set hybrid search parameters
SELECT ruvector_get_hybrid_alpha; -- Returns current alpha
SELECT ruvector_set_hybrid_alpha(0.6);
SELECT ruvector_get_hybrid_rrf_k;
SELECT ruvector_set_hybrid_rrf_k(40);
Multi-Tenancy (17 functions)
Row-level security with automatic tenant isolation.
-- Set current tenant context
SELECT ruvector_set_tenant('tenant_123');
SELECT ruvector_get_tenant;
-- Create tenant-isolated table
SELECT ruvector_create_tenant_table(
'documents',
'id SERIAL PRIMARY KEY, content TEXT, embedding ruvector(384)'
);
-- Automatic tenant filtering (via RLS policies)
INSERT INTO documents (content, embedding)
VALUES ('Hello', '[0.1, 0.2, ...]'::ruvector);
-- Automatically tagged with tenant_id
-- Query only sees current tenant's data
SELECT * FROM documents
WHERE embedding <-> $query < 0.5;
-- Tenant management
SELECT ruvector_list_tenants;
SELECT ruvector_tenant_stats('tenant_123');
SELECT ruvector_migrate_tenant('old_tenant', 'new_tenant');
-- Cross-tenant queries (admin only)
SELECT ruvector_admin_query_all_tenants('documents', 'SELECT count(*) FROM documents');
Self-Healing (23 functions)
Automated index repair with integrity validation.
-- Check index health
SELECT ruvector_index_health('documents_embedding_idx');
-- Returns: {"status": "healthy", "fragmentation": 0.05, "orphaned_nodes": 0}
-- Automatic repair
SELECT ruvector_auto_repair('documents_embedding_idx');
-- Schedule maintenance
SELECT ruvector_schedule_maintenance(
'documents_embedding_idx',
interval := '1 day',
repair_threshold := 0.1 -- Repair if fragmentation > 10%
);
-- Self-healing operations
SELECT ruvector_compact_index('documents_embedding_idx');
SELECT ruvector_rebalance_hnsw('documents_embedding_idx');
SELECT ruvector_rebuild_ivf_centroids('documents_embedding_idx');
SELECT ruvector_validate_graph_connectivity('documents_embedding_idx');
-- Monitor healing status
SELECT ruvector_healing_status;
SELECT ruvector_last_repair_log('documents_embedding_idx');
-- Integrity checks
SELECT ruvector_check_orphaned_vectors('documents');
SELECT ruvector_check_duplicate_vectors('documents', threshold := 0.001);
Integrity Control (4 functions)
Stoer-Wagner mincut-based quality assurance for vector indices.
-- Get integrity status
SELECT ruvector_integrity_status;
-- Returns: {"enabled": true, "active_contracts": 1, "contracts": ["default"]}
-- Create integrity contract (SLA)
SELECT ruvector_integrity_create_contract(
id := 'production_sla',
name := 'Production SLA',
min_recall := 0.95, -- Minimum recall requirement
max_latency_ms := 100, -- Maximum query latency
min_mincut := 0.1 -- Minimum graph connectivity
);
-- Validate against contract
SELECT ruvector_integrity_validate(
'production_sla',
recall := 0.97,
latency_ms := 45,
mincut := 0.15
);
-- Returns: {"passed": true, "recall": 0.97, "latency_ms": 45, "mincut": 0.15, "failures": []}
-- Compute mincut for graph connectivity
SELECT ruvector_mincut(
n := 100, -- Number of nodes
edges_json := '[{"u": 0, "v": 1, "w": 1.0}, ...]'::jsonb
);
-- Returns minimum cut value (Stoer-Wagner algorithm)
Vector Types
ruvector(n) - Dense Vector
(embedding ruvector(1536));
-- Storage: 8 + (4 x dimensions) bytes
halfvec(n) - Half-Precision Vector
(embedding halfvec(1536));
-- Storage: 8 + (2 x dimensions) bytes (50% savings)
sparsevec(n) - Sparse Vector
(embedding sparsevec(50000));
INSERT INTO items VALUES ('{1:0.5, 100:0.8, 5000:0.3}/50000');
-- Storage: 12 + (8 x non_zero_elements) bytes
Distance Operators
| Operator | Distance | Use Case |
|---|---|---|
<-> |
L2 (Euclidean) | General similarity |
<=> |
Cosine | Text embeddings |
<#> |
Inner Product | Normalized vectors |
<+> |
Manhattan (L1) | Sparse features |
Index Types
HNSW (Hierarchical Navigable Small World)
(embedding ruvector_l2_ops)
WITH (m = 16, ef_construction = 64);
SET ruvector.ef_search = 100; -- Tune search quality
IVFFlat (Inverted File Flat)
(embedding ruvector_l2_ops)
WITH (lists = 100);
SET ruvector.ivfflat_probes = 10; -- Tune search quality
Performance Benchmarks
AMD EPYC 7763 (64 cores), 256GB RAM:
| Operation | 10K vectors | 100K vectors | 1M vectors |
|---|---|---|---|
| HNSW Build | 0.8s | 8.2s | 95s |
| HNSW Search (top-10) | 0.3ms | 0.5ms | 1.2ms |
| Cosine Distance | 0.01ms | 0.01ms | 0.01ms |
| Poincare Distance | 0.02ms | 0.02ms | 0.02ms |
| GCN Forward | 2.1ms | 18ms | 180ms |
| BM25 Score | 0.05ms | 0.08ms | 0.15ms |
Single distance calculation (1536 dimensions):
| Metric | AVX2 Time | Speedup vs Scalar |
|---|---|---|
| L2 (Euclidean) | 38 ns | 3.7x |
| Cosine | 51 ns | 3.7x |
| Inner Product | 36 ns | 3.7x |
Use Cases
Semantic Search with RAG
SELECT content, embedding <=> $query_embedding AS similarity
FROM documents
WHERE category = 'technical'
ORDER BY similarity
LIMIT 5;
Knowledge Graph with Hierarchical Embeddings
-- Use hyperbolic embeddings for taxonomy
SELECT name, ruvector_poincare_distance(embedding, $query, -1.0) AS distance
FROM taxonomy_nodes
ORDER BY distance
LIMIT 10;
Hybrid Search (Vector + BM25)
SELECT
content,
0.7 * (1.0 / (1.0 + embedding <-> $query_vector)) +
0.3 * ruvector_bm25_score(terms, doc_freqs, length, avg_len, total) AS score
FROM documents
ORDER BY score DESC
LIMIT 10;
Multi-Agent Query Routing
SELECT ruvector_route_query(
$user_query_embedding,
(SELECT array_agg(row(name, capabilities)) FROM agents)
) AS best_agent;
Graph Neural Network Inference
SELECT ruvector_gnn_gcn_layer(
node_features,
adjacency_matrix,
trained_weights
) AS updated_features
FROM graph_nodes;
CLI Tool
Install the CLI for easy management:
# Commands
Related Packages
@ruvector/postgres-cli- CLI for RuVector PostgreSQLruvector-core- Core vector operations libraryruvector-tiny-dancer- Agent routing library
Documentation
| Document | Description |
|---|---|
| docs/API.md | Complete SQL API reference |
| docs/ARCHITECTURE.md | System architecture |
| docs/SIMD_OPTIMIZATION.md | SIMD details |
| docs/guides/ATTENTION_QUICK_REFERENCE.md | Attention mechanisms |
| docs/GNN_QUICK_REFERENCE.md | GNN layers |
| docs/ROUTING_QUICK_REFERENCE.md | Tiny Dancer routing |
| docs/LEARNING_MODULE_README.md | ReasoningBank |
Requirements
- PostgreSQL 14, 15, 16, or 17
- x86_64 (AVX2/AVX-512) or ARM64 (NEON)
- Linux, macOS, or Windows (WSL)
License
MIT License - See LICENSE
Contributing
Contributions welcome! See CONTRIBUTING.md