Skip to content

Commit 4157a91

Browse files
claudeclaude
committed
docs(postgres): Add comprehensive SQL Functions Reference table
53+ functions organized by category with descriptions and usage examples: - Distance Functions (5) - Vector Operations (5) - Hyperbolic Geometry (8) - Sparse Vectors & BM25 (14) - Attention Mechanisms (39) - Graph Neural Networks (5) - Agent Routing - Tiny Dancer (11) - Self-Learning / ReasoningBank (7) - Graph Storage & Cypher (8) - Quantization (4) - Index Management (3)
1 parent e2a1422 commit 4157a91

1 file changed

Lines changed: 213 additions & 0 deletions

File tree

‎crates/ruvector-postgres/docs/SQL_FUNCTIONS_REFERENCE.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# RuVector-Postgres SQL Functions Reference
2+
3+
Complete reference table of all 53+ SQL functions with descriptions and usage examples.
4+
5+
## Quick Reference Table
6+
7+
| Category | Function | Description | Example |
8+
|----------|----------|-------------|---------|
9+
| **Core** | `ruvector_version()` | Get extension version | `SELECT ruvector_version();` |
10+
| **Core** | `ruvector_simd_info()` | Get SIMD capabilities | `SELECT ruvector_simd_info();` |
11+
12+
### Distance Functions (5)
13+
14+
| Function | Description | Usage |
15+
|----------|-------------|-------|
16+
| `ruvector_l2_distance(a, b)` | Euclidean (L2) distance | `SELECT ruvector_l2_distance('[1,2,3]', '[4,5,6]');` |
17+
| `ruvector_cosine_distance(a, b)` | Cosine distance (1 - similarity) | `SELECT ruvector_cosine_distance('[1,0]', '[0,1]');` |
18+
| `ruvector_inner_product(a, b)` | Dot product distance | `SELECT ruvector_inner_product('[1,2]', '[3,4]');` |
19+
| `ruvector_l1_distance(a, b)` | Manhattan (L1) distance | `SELECT ruvector_l1_distance('[1,2]', '[3,4]');` |
20+
| `ruvector_hamming_distance(a, b)` | Hamming distance for binary | `SELECT ruvector_hamming_distance(a, b);` |
21+
22+
### Vector Operations (5)
23+
24+
| Function | Description | Usage |
25+
|----------|-------------|-------|
26+
| `ruvector_normalize(v)` | Normalize to unit length | `SELECT ruvector_normalize('[3,4]');` → `[0.6,0.8]` |
27+
| `ruvector_norm(v)` | Get L2 norm (magnitude) | `SELECT ruvector_norm('[3,4]');` → `5.0` |
28+
| `ruvector_add(a, b)` | Add two vectors | `SELECT ruvector_add('[1,2]', '[3,4]');` → `[4,6]` |
29+
| `ruvector_sub(a, b)` | Subtract vectors | `SELECT ruvector_sub('[5,6]', '[1,2]');` → `[4,4]` |
30+
| `ruvector_scalar_mul(v, s)` | Multiply by scalar | `SELECT ruvector_scalar_mul('[1,2]', 2.0);` → `[2,4]` |
31+
32+
### Hyperbolic Geometry (8)
33+
34+
| Function | Description | Usage |
35+
|----------|-------------|-------|
36+
| `ruvector_poincare_distance(a, b, c)` | Poincaré ball distance | `SELECT ruvector_poincare_distance(a, b, -1.0);` |
37+
| `ruvector_lorentz_distance(a, b, c)` | Lorentz hyperboloid distance | `SELECT ruvector_lorentz_distance(a, b, -1.0);` |
38+
| `ruvector_mobius_add(a, b, c)` | Möbius addition (hyperbolic translation) | `SELECT ruvector_mobius_add(a, b, -1.0);` |
39+
| `ruvector_exp_map(base, tangent, c)` | Exponential map (tangent → manifold) | `SELECT ruvector_exp_map(base, tangent, -1.0);` |
40+
| `ruvector_log_map(base, target, c)` | Logarithmic map (manifold → tangent) | `SELECT ruvector_log_map(base, target, -1.0);` |
41+
| `ruvector_poincare_to_lorentz(v, c)` | Convert Poincaré to Lorentz | `SELECT ruvector_poincare_to_lorentz(v, -1.0);` |
42+
| `ruvector_lorentz_to_poincare(v, c)` | Convert Lorentz to Poincaré | `SELECT ruvector_lorentz_to_poincare(v, -1.0);` |
43+
| `ruvector_minkowski_dot(a, b)` | Minkowski inner product | `SELECT ruvector_minkowski_dot(a, b);` |
44+
45+
### Sparse Vectors & BM25 (14)
46+
47+
| Function | Description | Usage |
48+
|----------|-------------|-------|
49+
| `ruvector_sparse_create(idx, vals, dim)` | Create sparse vector | `SELECT ruvector_sparse_create(ARRAY[0,5,10], ARRAY[0.5,0.3,0.2], 100);` |
50+
| `ruvector_sparse_from_dense(v, thresh)` | Dense to sparse conversion | `SELECT ruvector_sparse_from_dense(dense_vec, 0.01);` |
51+
| `ruvector_sparse_to_dense(sv)` | Sparse to dense conversion | `SELECT ruvector_sparse_to_dense(sparse_vec);` |
52+
| `ruvector_sparse_dot(a, b)` | Sparse dot product | `SELECT ruvector_sparse_dot(sv1, sv2);` |
53+
| `ruvector_sparse_cosine(a, b)` | Sparse cosine similarity | `SELECT ruvector_sparse_cosine(sv1, sv2);` |
54+
| `ruvector_sparse_l2_distance(a, b)` | Sparse L2 distance | `SELECT ruvector_sparse_l2_distance(sv1, sv2);` |
55+
| `ruvector_sparse_add(a, b)` | Add sparse vectors | `SELECT ruvector_sparse_add(sv1, sv2);` |
56+
| `ruvector_sparse_scale(sv, s)` | Scale sparse vector | `SELECT ruvector_sparse_scale(sv, 2.0);` |
57+
| `ruvector_sparse_normalize(sv)` | Normalize sparse vector | `SELECT ruvector_sparse_normalize(sv);` |
58+
| `ruvector_sparse_topk(sv, k)` | Get top-k elements | `SELECT ruvector_sparse_topk(sv, 10);` |
59+
| `ruvector_sparse_nnz(sv)` | Count non-zero elements | `SELECT ruvector_sparse_nnz(sv);` |
60+
| `ruvector_bm25_score(...)` | BM25 relevance score | `SELECT ruvector_bm25_score(terms, doc_freqs, doc_len, avg_len, total);` |
61+
| `ruvector_tf_idf(tf, df, total)` | TF-IDF score | `SELECT ruvector_tf_idf(term_freq, doc_freq, total_docs);` |
62+
| `ruvector_sparse_intersection(a, b)` | Intersection of sparse vectors | `SELECT ruvector_sparse_intersection(sv1, sv2);` |
63+
64+
### Attention Mechanisms (10 primary + 29 variants)
65+
66+
| Function | Description | Usage |
67+
|----------|-------------|-------|
68+
| `ruvector_attention_scaled_dot(q, k, v)` | Scaled dot-product attention | `SELECT ruvector_attention_scaled_dot(query, keys, values);` |
69+
| `ruvector_attention_multi_head(q, k, v, h)` | Multi-head attention | `SELECT ruvector_attention_multi_head(q, k, v, 8);` |
70+
| `ruvector_attention_flash(q, k, v, blk)` | Flash attention (memory efficient) | `SELECT ruvector_attention_flash(q, k, v, 64);` |
71+
| `ruvector_attention_sparse(q, k, v, pat)` | Sparse attention | `SELECT ruvector_attention_sparse(q, k, v, pattern);` |
72+
| `ruvector_attention_linear(q, k, v)` | Linear attention O(n) | `SELECT ruvector_attention_linear(q, k, v);` |
73+
| `ruvector_attention_causal(q, k, v)` | Causal/masked attention | `SELECT ruvector_attention_causal(q, k, v);` |
74+
| `ruvector_attention_cross(q, ck, cv)` | Cross attention | `SELECT ruvector_attention_cross(query, ctx_keys, ctx_values);` |
75+
| `ruvector_attention_self(input, heads)` | Self attention | `SELECT ruvector_attention_self(input, 8);` |
76+
| `ruvector_attention_local(q, k, v, win)` | Local/sliding window attention | `SELECT ruvector_attention_local(q, k, v, 256);` |
77+
| `ruvector_attention_relative(q, k, v)` | Relative position attention | `SELECT ruvector_attention_relative(q, k, v);` |
78+
79+
**Additional Attention Types:** `performer`, `linformer`, `bigbird`, `longformer`, `reformer`, `synthesizer`, `routing`, `mixture_of_experts`, `alibi`, `rope`, `xpos`, `grouped_query`, `sliding_window`, `dilated`, `axial`, `product_key`, `hash_based`, `random_feature`, `nystrom`, `clustered`, `sinkhorn`, `entmax`, `adaptive_span`, `compressive`, `feedback`, `talking_heads`, `realformer`, `rezero`, `fixup`
80+
81+
### Graph Neural Networks (5)
82+
83+
| Function | Description | Usage |
84+
|----------|-------------|-------|
85+
| `ruvector_gnn_gcn_layer(feat, adj, w)` | Graph Convolutional Network | `SELECT ruvector_gnn_gcn_layer(features, adjacency, weights);` |
86+
| `ruvector_gnn_graphsage_layer(feat, neigh, w)` | GraphSAGE (inductive) | `SELECT ruvector_gnn_graphsage_layer(feat, neighbors, weights);` |
87+
| `ruvector_gnn_gat_layer(feat, adj, attn)` | Graph Attention Network | `SELECT ruvector_gnn_gat_layer(feat, adj, attention_weights);` |
88+
| `ruvector_gnn_message_pass(feat, edges, w)` | Message passing | `SELECT ruvector_gnn_message_pass(node_feat, edge_idx, edge_w);` |
89+
| `ruvector_gnn_aggregate(msg, type)` | Aggregate messages | `SELECT ruvector_gnn_aggregate(messages, 'mean');` |
90+
91+
### Agent Routing - Tiny Dancer (11)
92+
93+
| Function | Description | Usage |
94+
|----------|-------------|-------|
95+
| `ruvector_route_query(embed, agents)` | Route query to best agent | `SELECT ruvector_route_query(query_embed, agent_registry);` |
96+
| `ruvector_route_with_context(q, ctx, agents)` | Route with context | `SELECT ruvector_route_with_context(query, context, agents);` |
97+
| `ruvector_multi_agent_route(q, agents, k)` | Multi-agent routing | `SELECT ruvector_multi_agent_route(query, agents, 3);` |
98+
| `ruvector_register_agent(name, caps, embed)` | Register new agent | `SELECT ruvector_register_agent('gpt4', caps, embedding);` |
99+
| `ruvector_update_agent_performance(id, metrics)` | Update agent metrics | `SELECT ruvector_update_agent_performance(agent_id, metrics);` |
100+
| `ruvector_get_routing_stats()` | Get routing statistics | `SELECT * FROM ruvector_get_routing_stats();` |
101+
| `ruvector_calculate_agent_affinity(q, agent)` | Calculate query-agent affinity | `SELECT ruvector_calculate_agent_affinity(query, agent);` |
102+
| `ruvector_select_best_agent(q, agents)` | Select best agent | `SELECT ruvector_select_best_agent(query, agent_list);` |
103+
| `ruvector_adaptive_route(q, ctx, lr)` | Adaptive routing with learning | `SELECT ruvector_adaptive_route(query, context, 0.01);` |
104+
| `ruvector_fastgrnn_forward(in, hidden, w)` | FastGRNN acceleration | `SELECT ruvector_fastgrnn_forward(input, hidden, weights);` |
105+
| `ruvector_get_agent_embeddings(agents)` | Get agent embeddings | `SELECT ruvector_get_agent_embeddings(agent_ids);` |
106+
107+
### Self-Learning / ReasoningBank (7)
108+
109+
| Function | Description | Usage |
110+
|----------|-------------|-------|
111+
| `ruvector_record_trajectory(in, out, ok, ctx)` | Record learning trajectory | `SELECT ruvector_record_trajectory(input, output, true, ctx);` |
112+
| `ruvector_get_verdict(traj_id)` | Get verdict on trajectory | `SELECT ruvector_get_verdict(trajectory_id);` |
113+
| `ruvector_distill_memory(trajs, ratio)` | Distill memory (compress) | `SELECT ruvector_distill_memory(trajectories, 0.5);` |
114+
| `ruvector_adaptive_search(q, ctx, ef)` | Adaptive search with learning | `SELECT ruvector_adaptive_search(query, context, 100);` |
115+
| `ruvector_learning_feedback(id, scores)` | Provide learning feedback | `SELECT ruvector_learning_feedback(search_id, scores);` |
116+
| `ruvector_get_learning_patterns(ctx)` | Get learned patterns | `SELECT * FROM ruvector_get_learning_patterns(context);` |
117+
| `ruvector_optimize_search_params(type, hist)` | Optimize search parameters | `SELECT ruvector_optimize_search_params('semantic', history);` |
118+
119+
### Graph Storage & Cypher (8)
120+
121+
| Function | Description | Usage |
122+
|----------|-------------|-------|
123+
| `ruvector_graph_create_node(labels, props, embed)` | Create graph node | `SELECT ruvector_graph_create_node('Person', '{"name":"Alice"}', embed);` |
124+
| `ruvector_graph_create_edge(from, to, type, props)` | Create graph edge | `SELECT ruvector_graph_create_edge(1, 2, 'KNOWS', '{}');` |
125+
| `ruvector_graph_get_neighbors(node, type, depth)` | Get node neighbors | `SELECT * FROM ruvector_graph_get_neighbors(1, 'KNOWS', 2);` |
126+
| `ruvector_graph_shortest_path(start, end)` | Find shortest path | `SELECT ruvector_graph_shortest_path(1, 10);` |
127+
| `ruvector_graph_pagerank(edges, damp, iters)` | Compute PageRank | `SELECT * FROM ruvector_graph_pagerank('edges', 0.85, 20);` |
128+
| `ruvector_cypher_query(query)` | Execute Cypher query | `SELECT * FROM ruvector_cypher_query('MATCH (n) RETURN n');` |
129+
| `ruvector_graph_traverse(start, dir, depth)` | Traverse graph | `SELECT * FROM ruvector_graph_traverse(1, 'outgoing', 3);` |
130+
| `ruvector_graph_similarity_search(embed, type, k)` | Vector search on graph | `SELECT * FROM ruvector_graph_similarity_search(embed, 'Person', 10);` |
131+
132+
### Quantization (4)
133+
134+
| Function | Description | Usage |
135+
|----------|-------------|-------|
136+
| `ruvector_quantize_scalar(v)` | Scalar quantization (int8) | `SELECT ruvector_quantize_scalar(embedding);` |
137+
| `ruvector_quantize_product(v, subvecs)` | Product quantization | `SELECT ruvector_quantize_product(embedding, 8);` |
138+
| `ruvector_quantize_binary(v)` | Binary quantization | `SELECT ruvector_quantize_binary(embedding);` |
139+
| `ruvector_dequantize(qv)` | Dequantize vector | `SELECT ruvector_dequantize(quantized_vec);` |
140+
141+
### Index Management (3)
142+
143+
| Function | Description | Usage |
144+
|----------|-------------|-------|
145+
| `ruvector_index_stats(name)` | Get index statistics | `SELECT * FROM ruvector_index_stats('idx_name');` |
146+
| `ruvector_index_maintenance(name)` | Perform index maintenance | `SELECT ruvector_index_maintenance('idx_name');` |
147+
| `ruvector_index_rebuild(name)` | Rebuild index | `SELECT ruvector_index_rebuild('idx_name');` |
148+
149+
## Operators Quick Reference
150+
151+
| Operator | Metric | Description | Example |
152+
|----------|--------|-------------|---------|
153+
| `<->` | L2 | Euclidean distance | `ORDER BY embedding <-> query` |
154+
| `<=>` | Cosine | Cosine distance | `ORDER BY embedding <=> query` |
155+
| `<#>` | IP | Inner product (negative) | `ORDER BY embedding <#> query` |
156+
| `<+>` | L1 | Manhattan distance | `ORDER BY embedding <+> query` |
157+
158+
## Data Types
159+
160+
| Type | Description | Storage | Max Dimensions |
161+
|------|-------------|---------|----------------|
162+
| `ruvector(n)` | Dense float32 vector | 8 + 4×n bytes | 16,000 |
163+
| `halfvec(n)` | Dense float16 vector | 8 + 2×n bytes | 16,000 |
164+
| `sparsevec(n)` | Sparse vector | 12 + 8×nnz bytes | 1,000,000 |
165+
166+
## Common Usage Patterns
167+
168+
### Semantic Search
169+
170+
```sql
171+
SELECT content, embedding <=> $query AS distance
172+
FROM documents
173+
ORDER BY distance
174+
LIMIT 10;
175+
```
176+
177+
### Hybrid Search (Vector + BM25)
178+
179+
```sql
180+
SELECT content,
181+
0.7 * (1.0 / (1.0 + embedding <-> $vec)) +
182+
0.3 * ruvector_bm25_score(terms, freqs, len, avg_len, total) AS score
183+
FROM documents
184+
ORDER BY score DESC LIMIT 10;
185+
```
186+
187+
### Hierarchical Search with Hyperbolic
188+
189+
```sql
190+
SELECT name, ruvector_poincare_distance(embedding, $query, -1.0) AS dist
191+
FROM taxonomy
192+
ORDER BY dist LIMIT 10;
193+
```
194+
195+
### Agent Routing
196+
197+
```sql
198+
SELECT ruvector_route_query($user_query_embedding,
199+
(SELECT array_agg(row(name, capabilities)) FROM agents)
200+
) AS best_agent;
201+
```
202+
203+
### Graph + Vector Search
204+
205+
```sql
206+
SELECT * FROM ruvector_graph_similarity_search($embedding, 'Document', 10);
207+
```
208+
209+
## See Also
210+
211+
- [API.md](./API.md) - Detailed API documentation
212+
- [ARCHITECTURE.md](./ARCHITECTURE.md) - System architecture
213+
- [README.md](../README.md) - Getting started guide

0 commit comments

Comments
 (0)