Skip to content

Latest commit

 

History

History
224 lines (175 loc) · 6.4 KB

DOCKERHUB.md

File metadata and controls

224 lines (175 loc) · 6.4 KB

RuVector-Postgres

The most advanced PostgreSQL vector database extension. A high-performance, drop-in replacement for pgvector with 77+ SQL functions, SIMD acceleration, 39 attention mechanisms, Graph Neural Networks, hyperbolic embeddings, and self-learning capabilities.

v2.0.0 (December 2025)

  • 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
  • Multi-tenant: Validated tenant isolation with parameterized queries

Quick Start

# Start RuVector-Postgres
docker run -d --name ruvector \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  ruvnet/ruvector-postgres:latest

# Connect and use
psql -h localhost -U ruvector -d ruvector_test

# Create extension
CREATE EXTENSION ruvector;

Why RuVector vs pgvector?

Feature pgvector RuVector-Postgres
Vector Search HNSW, IVFFlat HNSW, IVFFlat (optimized)
Distance Metrics 3 8+ (including hyperbolic)
Attention Mechanisms None 39 types (scaled-dot, multi-head, flash, sparse)
Graph Neural Networks None GCN, GraphSAGE, GAT
Hyperbolic Embeddings None Poincare, Lorentz (for hierarchies)
Sparse Vectors Partial Full support + BM25
Self-Learning None ReasoningBank (adaptive search)
Agent Routing None Tiny Dancer (11 functions)
Graph/Cypher None Full support
SIMD Acceleration Partial Full AVX-512/NEON
Quantization None Scalar, Product, Binary

Features

Core Vector Operations

  • L2, Cosine, Inner Product, Manhattan distances
  • Vector normalization, addition, scalar multiplication
  • SIMD-accelerated (AVX2/AVX-512/NEON)

Hyperbolic Embeddings

Perfect for hierarchical data (taxonomies, org charts, knowledge graphs):

SELECT ruvector_poincare_distance(a, b, -1.0);
SELECT ruvector_mobius_add(a, b, -1.0);

Sparse Vectors & BM25

Full sparse vector support with text scoring:

SELECT ruvector_sparse_dot(a, b);
SELECT ruvector_bm25_score(query, doc_freqs, doc_len, avg_len, total);

39 Attention Mechanisms

Transformer-style attention in PostgreSQL:

SELECT ruvector_attention_scaled_dot(query, keys, values);
SELECT ruvector_attention_multi_head(query, keys, values, 8);

Graph Neural Networks

GNN inference directly in PostgreSQL:

SELECT ruvector_gnn_gcn_layer(features, adjacency, weights);
SELECT ruvector_gnn_graphsage_layer(features, neighbors, weights);

Self-Learning (ReasoningBank)

Adaptive search parameter optimization:

SELECT ruvector_record_trajectory(input, output, success, context);
SELECT ruvector_adaptive_search(query, context, ef_search);

Tutorial 1: Semantic Search

-- Create extension
CREATE EXTENSION ruvector;

-- Create table with vector column
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding ruvector(1536)
);

-- Insert some documents (embeddings from your ML model)
INSERT INTO documents (content, embedding) VALUES
    ('PostgreSQL is a powerful database', '[0.1, 0.2, ...]'),
    ('Vector search enables AI applications', '[0.3, 0.1, ...]');

-- Create HNSW index for fast search
CREATE INDEX ON documents USING ruhnsw (embedding ruvector_l2_ops)
WITH (m = 16, ef_construction = 64);

-- Search for similar documents
SELECT content, embedding <-> $query_embedding AS distance
FROM documents
ORDER BY distance
LIMIT 10;

Tutorial 2: Hybrid Search (Vector + BM25)

-- Combine vector similarity with text scoring
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;

Tutorial 3: Knowledge Graph with Hyperbolic Embeddings

-- Hyperbolic embeddings preserve hierarchy better than Euclidean
-- Perfect for taxonomies, org charts, knowledge graphs

-- Create taxonomy table
CREATE TABLE taxonomy_nodes (
    id SERIAL PRIMARY KEY,
    name TEXT,
    parent_id INTEGER,
    embedding ruvector(128)  -- Poincare embeddings
);

-- Find similar nodes using hyperbolic distance
SELECT name, ruvector_poincare_distance(embedding, $query, -1.0) AS distance
FROM taxonomy_nodes
ORDER BY distance
LIMIT 10;

Tutorial 4: Multi-Agent Query Routing

-- Register AI agents with their capabilities
SELECT ruvector_register_agent('code_expert', ARRAY['coding', 'debugging'], $embedding);
SELECT ruvector_register_agent('math_expert', ARRAY['math', 'statistics'], $embedding);

-- Route user query to best agent
SELECT ruvector_route_query($user_query_embedding,
    (SELECT array_agg(row(name, capabilities)) FROM agents)
) AS best_agent;

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)

CREATE INDEX ON items USING ruhnsw (embedding ruvector_l2_ops)
WITH (m = 16, ef_construction = 64);

SET ruvector.ef_search = 100;  -- Tune search quality

IVFFlat

CREATE INDEX ON items USING ruivfflat (embedding ruvector_l2_ops)
WITH (lists = 100);

SET ruvector.ivfflat_probes = 10;

Performance

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

Environment Variables

Variable Default Description
POSTGRES_USER ruvector Database user
POSTGRES_PASSWORD ruvector Database password
POSTGRES_DB ruvector_test Default database

CLI Tool

npm install -g @ruvector/postgres-cli

ruvector-pg install --method docker
ruvector-pg vector create table --dim 384 --index hnsw
ruvector-pg bench run --type all --size 10000

Links

License

MIT License