Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

2026-02-28 14:39:40 -05:00
parent 7885bf6278 d803bfe2b1
commit cd5943df23
7854 changed files with 3522914 additions and 0 deletions
--- a/vendor/ruvector/docs/examples/sparsevec_examples.sql
+++ b/vendor/ruvector/docs/examples/sparsevec_examples.sql
@@ -0,0 +1,335 @@
+-- ============================================================================
+-- SparseVec PostgreSQL Type - Usage Examples
+-- ============================================================================
+
+-- Basic Usage
+-- ============================================================================
+
+-- Create a sparse vector with format {idx:val,idx:val,...}/dimensions
+SELECT '{0:1.5,3:2.5,7:3.5}/10'::sparsevec;
+
+-- Create an empty sparse vector
+SELECT '{}/100'::sparsevec;
+
+-- Create a dense sparse vector (many non-zeros)
+SELECT '{0:1.0,1:2.0,2:3.0,3:4.0,4:5.0}/5'::sparsevec;
+
+-- Introspection
+-- ============================================================================
+
+-- Get dimensions
+SELECT sparsevec_dims('{0:1.5,3:2.5,7:3.5}/10'::sparsevec);
+-- Returns: 10
+
+-- Get number of non-zero elements
+SELECT sparsevec_nnz('{0:1.5,3:2.5,7:3.5}/10'::sparsevec);
+-- Returns: 3
+
+-- Get sparsity ratio
+SELECT sparsevec_sparsity('{0:1.5,3:2.5,7:3.5}/10'::sparsevec);
+-- Returns: 0.3 (30% non-zero)
+
+-- Get L2 norm
+SELECT sparsevec_norm('{0:3.0,1:4.0}/5'::sparsevec);
+-- Returns: 5.0
+
+-- Get value at specific index
+SELECT sparsevec_get('{0:1.5,3:2.5,7:3.5}/10'::sparsevec, 3);
+-- Returns: 2.5
+
+SELECT sparsevec_get('{0:1.5,3:2.5,7:3.5}/10'::sparsevec, 5);
+-- Returns: 0.0 (not present)
+
+-- Parse and inspect
+SELECT sparsevec_parse('{0:1.5,3:2.5,7:3.5}/10');
+-- Returns JSON with full details
+
+-- Distance Calculations
+-- ============================================================================
+
+-- L2 (Euclidean) distance
+SELECT sparsevec_l2_distance(
+    '{0:1.0,2:2.0,4:3.0}/5'::sparsevec,
+    '{1:1.0,2:1.0,3:2.0}/5'::sparsevec
+);
+
+-- Inner product distance (negative dot product)
+SELECT sparsevec_ip_distance(
+    '{0:1.0,2:2.0}/5'::sparsevec,
+    '{2:1.0,4:3.0}/5'::sparsevec
+);
+-- Returns: -2.0 (only index 2 overlaps: -(2*1))
+
+-- Cosine distance
+SELECT sparsevec_cosine_distance(
+    '{0:1.0,2:2.0}/5'::sparsevec,
+    '{0:2.0,2:4.0}/5'::sparsevec
+);
+-- Returns: ~0.0 (same direction)
+
+-- Mixed sparse-dense distances
+SELECT sparsevec_vector_l2_distance(
+    '{0:1.0,3:2.0}/5'::sparsevec,
+    '[1.0,0.0,0.0,2.0,0.0]'::ruvector
+);
+
+SELECT sparsevec_vector_cosine_distance(
+    '{0:1.0,3:2.0}/5'::sparsevec,
+    '[1.0,0.0,0.0,2.0,0.0]'::ruvector
+);
+
+-- Vector Operations
+-- ============================================================================
+
+-- Normalize to unit length
+SELECT sparsevec_normalize('{0:3.0,1:4.0}/5'::sparsevec);
+-- Returns: {0:0.6,1:0.8}/5
+
+-- Add two sparse vectors
+SELECT sparsevec_add(
+    '{0:1.0,2:2.0}/5'::sparsevec,
+    '{1:3.0,2:1.0}/5'::sparsevec
+);
+-- Returns: {0:1.0,1:3.0,2:3.0}/5
+
+-- Multiply by scalar
+SELECT sparsevec_mul_scalar('{0:1.0,2:2.0}/5'::sparsevec, 2.5);
+-- Returns: {0:2.5,2:5.0}/5
+
+-- Conversions
+-- ============================================================================
+
+-- Sparse to dense vector
+SELECT sparsevec_to_vector('{0:1.0,3:2.0}/5'::sparsevec);
+-- Returns: [1.0, 0.0, 0.0, 2.0, 0.0]
+
+-- Dense to sparse with threshold
+SELECT vector_to_sparsevec('[0.001,0.5,0.002,1.0,0.003]'::ruvector, 0.01);
+-- Returns: {1:0.5,3:1.0}/5 (filters values ≤ 0.01)
+
+-- Sparse to array
+SELECT sparsevec_to_array('{0:1.0,3:2.0}/5'::sparsevec);
+
+-- Array to sparse
+SELECT array_to_sparsevec(ARRAY[0.001, 0.5, 0.002, 1.0, 0.003]::float4[], 0.01);
+
+-- Table Creation and Queries
+-- ============================================================================
+
+-- Create table for text embeddings (TF-IDF)
+CREATE TABLE documents (
+    id SERIAL PRIMARY KEY,
+    title TEXT NOT NULL,
+    content TEXT,
+    embedding sparsevec(10000)  -- 10K vocabulary
+);
+
+-- Insert documents with sparse embeddings
+INSERT INTO documents (title, content, embedding) VALUES
+('Document 1', 'machine learning artificial intelligence',
+ '{45:0.8,123:0.6,789:0.9,1024:0.7}/10000'),
+('Document 2', 'deep learning neural networks',
+ '{45:0.3,234:0.9,789:0.4,2048:0.8}/10000'),
+('Document 3', 'natural language processing',
+ '{123:0.7,456:0.9,3072:0.6}/10000');
+
+-- Find similar documents using cosine distance
+SELECT
+    d.id,
+    d.title,
+    sparsevec_cosine_distance(d.embedding, query.embedding) AS distance
+FROM
+    documents d,
+    (SELECT embedding FROM documents WHERE id = 1) AS query
+WHERE
+    d.id != 1
+ORDER BY
+    distance ASC
+LIMIT 5;
+
+-- Find nearest neighbors using L2 distance
+SELECT
+    d.id,
+    d.title,
+    sparsevec_l2_distance(d.embedding,
+        '{45:0.8,123:0.6,789:0.9}/10000'::sparsevec) AS distance
+FROM
+    documents d
+ORDER BY
+    distance ASC
+LIMIT 10;
+
+-- Recommender System Example
+-- ============================================================================
+
+-- User-item interaction matrix (sparse)
+CREATE TABLE user_profiles (
+    user_id INT PRIMARY KEY,
+    username TEXT NOT NULL,
+    preferences sparsevec(100000)  -- 100K items
+);
+
+-- Insert user profiles with sparse preference vectors
+INSERT INTO user_profiles (user_id, username, preferences) VALUES
+(1, 'alice', '{123:5.0,456:4.5,789:3.5,1024:4.0}/100000'),
+(2, 'bob', '{123:4.0,234:5.0,789:4.5,2048:3.5}/100000'),
+(3, 'carol', '{456:5.0,890:4.0,2048:4.5,3072:5.0}/100000');
+
+-- Collaborative filtering: Find similar users
+SELECT
+    u2.user_id,
+    u2.username,
+    sparsevec_cosine_distance(u1.preferences, u2.preferences) AS similarity
+FROM
+    user_profiles u1,
+    user_profiles u2
+WHERE
+    u1.user_id = 1
+    AND u2.user_id != 1
+ORDER BY
+    similarity ASC
+LIMIT 10;
+
+-- Find items user might like (based on similar users)
+WITH similar_users AS (
+    SELECT
+        u2.user_id,
+        u2.preferences,
+        sparsevec_cosine_distance(u1.preferences, u2.preferences) AS similarity
+    FROM
+        user_profiles u1,
+        user_profiles u2
+    WHERE
+        u1.user_id = 1
+        AND u2.user_id != 1
+    ORDER BY
+        similarity ASC
+    LIMIT 5
+)
+SELECT
+    user_id,
+    similarity
+FROM
+    similar_users;
+
+-- Graph Embeddings Example
+-- ============================================================================
+
+-- Store graph node embeddings
+CREATE TABLE graph_nodes (
+    node_id BIGINT PRIMARY KEY,
+    node_type TEXT,
+    sparse_embedding sparsevec(50000)
+);
+
+-- Insert graph nodes with embeddings
+INSERT INTO graph_nodes (node_id, node_type, sparse_embedding) VALUES
+(1, 'person', '{100:0.9,500:0.7,1000:0.8}/50000'),
+(2, 'product', '{200:0.8,600:0.9,1500:0.7}/50000'),
+(3, 'company', '{100:0.5,300:0.8,2000:0.9}/50000');
+
+-- Find nearest neighbors in embedding space
+SELECT
+    node_id,
+    node_type,
+    sparsevec_l2_distance(sparse_embedding,
+        '{100:0.9,500:0.7,1000:0.8}/50000'::sparsevec) AS distance
+FROM
+    graph_nodes
+WHERE
+    node_id != 1
+ORDER BY
+    distance ASC
+LIMIT 20;
+
+-- Statistics and Analytics
+-- ============================================================================
+
+-- Analyze sparsity distribution
+SELECT
+    percentile_cont(0.5) WITHIN GROUP (ORDER BY sparsevec_sparsity(embedding)) AS median_sparsity,
+    AVG(sparsevec_sparsity(embedding)) AS avg_sparsity,
+    MIN(sparsevec_nnz(embedding)) AS min_nnz,
+    MAX(sparsevec_nnz(embedding)) AS max_nnz
+FROM
+    documents;
+
+-- Find documents with highest/lowest sparsity
+SELECT
+    id,
+    title,
+    sparsevec_nnz(embedding) AS non_zeros,
+    sparsevec_sparsity(embedding) AS sparsity_ratio
+FROM
+    documents
+ORDER BY
+    sparsity_ratio DESC
+LIMIT 10;
+
+-- Performance Comparison
+-- ============================================================================
+
+-- Compare storage efficiency
+SELECT
+    'Dense' AS type,
+    pg_column_size('[' || array_to_string(array_agg(i::text), ',') || ']'::ruvector) AS bytes
+FROM generate_series(1, 10000) AS i
+UNION ALL
+SELECT
+    'Sparse (1% non-zero)' AS type,
+    pg_column_size('{' || array_to_string(
+        array_agg(i || ':1.0'), ',') || '}/10000'::sparsevec) AS bytes
+FROM generate_series(1, 100) AS i;
+
+-- Advanced Queries
+-- ============================================================================
+
+-- Batch distance calculation
+WITH query_vector AS (
+    SELECT '{0:1.0,100:2.0,500:3.0}/10000'::sparsevec AS vec
+)
+SELECT
+    d.id,
+    d.title,
+    sparsevec_cosine_distance(d.embedding, q.vec) AS distance
+FROM
+    documents d,
+    query_vector q
+ORDER BY
+    distance ASC;
+
+-- Filter by distance threshold
+SELECT
+    d.id,
+    d.title
+FROM
+    documents d
+WHERE
+    sparsevec_cosine_distance(d.embedding,
+        '{45:0.8,123:0.6}/10000'::sparsevec) < 0.5
+ORDER BY
+    id;
+
+-- Aggregate operations
+SELECT
+    AVG(sparsevec_norm(embedding)) AS avg_norm,
+    STDDEV(sparsevec_norm(embedding)) AS stddev_norm
+FROM
+    documents;
+
+-- Index Creation (Future Enhancement)
+-- ============================================================================
+
+-- These would be available once index support is added:
+-- CREATE INDEX idx_doc_embedding ON documents
+--     USING hnsw (embedding sparsevec_cosine_ops);
+
+-- CREATE INDEX idx_user_prefs ON user_profiles
+--     USING ivfflat (preferences sparsevec_l2_ops);
+
+-- Cleanup
+-- ============================================================================
+
+-- DROP TABLE IF EXISTS documents;
+-- DROP TABLE IF EXISTS user_profiles;
+-- DROP TABLE IF EXISTS graph_nodes;