mirror of
https://github.com/ruvnet/RuView
synced 2026-07-23 17:33:20 +00:00
ruv
d803bfe2b1
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
170 lines
4.3 KiB
Markdown
170 lines
4.3 KiB
Markdown
# RuVector Distance Operators - Quick Reference
|
|
|
|
## 🚀 Zero-Copy Operators (Use These!)
|
|
|
|
All operators use SIMD-optimized zero-copy access automatically.
|
|
|
|
### SQL Operators
|
|
|
|
```sql
|
|
-- L2 (Euclidean) Distance
|
|
SELECT * FROM items ORDER BY embedding <-> '[1,2,3]' LIMIT 10;
|
|
|
|
-- Inner Product (Maximum similarity)
|
|
SELECT * FROM items ORDER BY embedding <#> '[1,2,3]' LIMIT 10;
|
|
|
|
-- Cosine Distance (Semantic similarity)
|
|
SELECT * FROM items ORDER BY embedding <=> '[1,2,3]' LIMIT 10;
|
|
|
|
-- L1 (Manhattan) Distance
|
|
SELECT * FROM items ORDER BY embedding <+> '[1,2,3]' LIMIT 10;
|
|
```
|
|
|
|
### Function Forms
|
|
|
|
```sql
|
|
-- When you need the distance value explicitly
|
|
SELECT
|
|
id,
|
|
ruvector_l2_distance(embedding, '[1,2,3]') as l2_dist,
|
|
ruvector_ip_distance(embedding, '[1,2,3]') as ip_dist,
|
|
ruvector_cosine_distance(embedding, '[1,2,3]') as cos_dist,
|
|
ruvector_l1_distance(embedding, '[1,2,3]') as l1_dist
|
|
FROM items;
|
|
```
|
|
|
|
## 📊 Operator Comparison
|
|
|
|
| Operator | Math Formula | Range | Best For |
|
|
|----------|--------------|-------|----------|
|
|
| `<->` | `√Σ(aᵢ-bᵢ)²` | [0, ∞) | General similarity, geometry |
|
|
| `<#>` | `-Σ(aᵢ×bᵢ)` | (-∞, ∞) | MIPS, recommendations |
|
|
| `<=>` | `1-(a·b)/(‖a‖‖b‖)` | [0, 2] | Text, semantic search |
|
|
| `<+>` | `Σ\|aᵢ-bᵢ\|` | [0, ∞) | Sparse vectors, L1 norm |
|
|
|
|
## 💡 Common Patterns
|
|
|
|
### Nearest Neighbors
|
|
```sql
|
|
-- Find 10 nearest neighbors
|
|
SELECT id, content, embedding <-> $query AS dist
|
|
FROM documents
|
|
ORDER BY embedding <-> $query
|
|
LIMIT 10;
|
|
```
|
|
|
|
### Filtered Search
|
|
```sql
|
|
-- Search within a category
|
|
SELECT * FROM products
|
|
WHERE category = 'electronics'
|
|
ORDER BY embedding <=> $query
|
|
LIMIT 20;
|
|
```
|
|
|
|
### Distance Threshold
|
|
```sql
|
|
-- Find all items within distance 0.5
|
|
SELECT * FROM items
|
|
WHERE embedding <-> $query < 0.5;
|
|
```
|
|
|
|
### Batch Distances
|
|
```sql
|
|
-- Compare one vector against many
|
|
SELECT id, embedding <-> '[1,2,3]' AS distance
|
|
FROM items
|
|
WHERE id IN (1, 2, 3, 4, 5);
|
|
```
|
|
|
|
## 🏗️ Index Creation
|
|
|
|
```sql
|
|
-- HNSW index (best for most cases)
|
|
CREATE INDEX ON items USING hnsw (embedding ruvector_l2_ops)
|
|
WITH (m = 16, ef_construction = 64);
|
|
|
|
-- IVFFlat index (good for large datasets)
|
|
CREATE INDEX ON items USING ivfflat (embedding ruvector_cosine_ops)
|
|
WITH (lists = 100);
|
|
```
|
|
|
|
## ⚡ Performance Tips
|
|
|
|
1. **Use RuVector type, not arrays**: `ruvector` type enables zero-copy
|
|
2. **Create indexes**: Essential for large datasets
|
|
3. **Normalize for cosine**: Pre-normalize vectors if using cosine often
|
|
4. **Check SIMD**: Run `SELECT ruvector_simd_info()` to verify acceleration
|
|
|
|
## 🔄 Migration from pgvector
|
|
|
|
RuVector operators are **drop-in compatible** with pgvector:
|
|
|
|
```sql
|
|
-- pgvector syntax works unchanged
|
|
SELECT * FROM items ORDER BY embedding <-> '[1,2,3]' LIMIT 10;
|
|
|
|
-- Just change the type from 'vector' to 'ruvector'
|
|
ALTER TABLE items ALTER COLUMN embedding TYPE ruvector(384);
|
|
```
|
|
|
|
## 📏 Dimension Support
|
|
|
|
- **Maximum**: 16,000 dimensions
|
|
- **Recommended**: 128-2048 for most use cases
|
|
- **Performance**: Optimal at multiples of 16 (AVX-512) or 8 (AVX2)
|
|
|
|
## 🐛 Debugging
|
|
|
|
```sql
|
|
-- Check SIMD support
|
|
SELECT ruvector_simd_info();
|
|
|
|
-- Verify vector dimensions
|
|
SELECT array_length(embedding::float4[], 1) FROM items LIMIT 1;
|
|
|
|
-- Test distance calculation
|
|
SELECT '[1,2,3]'::ruvector <-> '[4,5,6]'::ruvector;
|
|
-- Should return: 5.196152 (≈√27)
|
|
```
|
|
|
|
## 🎯 Choosing the Right Metric
|
|
|
|
| Your Data | Recommended Operator |
|
|
|-----------|---------------------|
|
|
| Text embeddings (BERT, OpenAI) | `<=>` (cosine) |
|
|
| Image features (ResNet, CLIP) | `<->` (L2) |
|
|
| Recommender systems | `<#>` (inner product) |
|
|
| Document vectors (TF-IDF) | `<=>` (cosine) |
|
|
| Sparse features | `<+>` (L1) |
|
|
| General floating-point | `<->` (L2) |
|
|
|
|
## ✅ Validation
|
|
|
|
```sql
|
|
-- Test basic functionality
|
|
CREATE TEMP TABLE test_vectors (v ruvector(3));
|
|
INSERT INTO test_vectors VALUES ('[1,2,3]'), ('[4,5,6]');
|
|
|
|
-- Should return distances
|
|
SELECT a.v <-> b.v AS l2,
|
|
a.v <#> b.v AS ip,
|
|
a.v <=> b.v AS cosine,
|
|
a.v <+> b.v AS l1
|
|
FROM test_vectors a, test_vectors b
|
|
WHERE a.v <> b.v;
|
|
```
|
|
|
|
Expected output:
|
|
```
|
|
l2 | ip | cosine | l1
|
|
---------+---------+----------+------
|
|
5.19615 | -32.000 | 0.025368 | 9.00
|
|
```
|
|
|
|
## 📚 Further Reading
|
|
|
|
- [Complete Documentation](./zero-copy-operators.md)
|
|
- [SIMD Implementation](../crates/ruvector-postgres/src/distance/simd.rs)
|
|
- [Benchmarks](../benchmarks/distance_bench.md)
|