Once you've created a bucket and index, you can start storing vectors. Vectors can include optional metadata for filtering and enrichment during queries.
Basic vector insertion
JavaScript
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key')
// Get bucket and index
const bucket = supabase.storage.vectors.from('embeddings')
const index = bucket.index('documents-openai')
// Insert vectors
const { error } = await index.putVectors({
vectors: [
{
key: 'doc-1',
data: {
float32: [0.1, 0.2, 0.3 /* ... rest of embedding ... */],
},
metadata: {
title: 'Getting Started with Vector Buckets',
source: 'documentation',
},
},
{
key: 'doc-2',
data: {
float32: [0.4, 0.5, 0.6 /* ... rest of embedding ... */],
},
metadata: {
title: 'Advanced Vector Search',
source: 'blog',
},
},
],
})
if (error) {
console.error('Error storing vectors:', error)
} else {
console.log('✓ Vectors stored successfully')
}
SQL (via S3 Vector Wrapper)
-- Setup S3 Vector Wrapper (one-time setup)
-- https://docs.zuvodev.com/guides/database/extensions/wrappers/s3_vectors
-- Insert vectors into the index
INSERT INTO s3_vectors.documents_openai (key, data, metadata)
VALUES
(
'doc-1',
'[0.1, 0.2, 0.3, /* ... rest of embedding ... */]'::embd,
'{"title": "Getting Started with Vector Buckets", "source": "documentation"}'::jsonb
),
(
'doc-2',
'[0.4, 0.5, 0.6, /* ... rest of embedding ... */]'::embd,
'{"title": "Advanced Vector Search", "source": "blog"}'::jsonb
);
Storing vectors from Embeddings API
Generate embeddings using an LLM API and store them directly:
JavaScript
import { createClient } from '@supabase/supabase-js'
import OpenAI from 'openai'
const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key')
const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY,
})
// Documents to embed and store
const documents = [
{ id: '1', title: 'How to Train Your AI', content: 'Guide for training models...' },
{ id: '2', title: 'Vector Search Best Practices', content: 'Tips for semantic search...' },
{
id: '3',
title: 'Building RAG Systems',
content: 'Implementing retrieval-augmented generation...',
},
]
// Generate embeddings
const embeddings = await openai.embeddings.create({
model: 'text-embedding-3-small',
input: documents.map((doc) => doc.content),
})
// Prepare vectors for storage
const vectors = documents.map((doc, index) => ({
key: doc.id,
data: {
float32: embeddings.data[index].embedding,
},
metadata: {
title: doc.title,
source: 'knowledge_base',
created_at: new Date().toISOString(),
},
}))
// Store vectors in batches (max 500 per request)
const bucket = supabase.storage.vectors.from('embeddings')
const vectorIndex = bucket.index('documents-openai')
for (let i = 0; i < vectors.length; i += 500) {
const batch = vectors.slice(i, i + 500)
const { error } = await vectorIndex.putVectors({ vectors: batch })
if (error) {
console.error(`Error storing batch ${i / 500 + 1}:`, error)
} else {
console.log(`✓ Stored batch ${i / 500 + 1} (${batch.length} vectors)`)
}
}
SQL (via S3 Vector Wrapper)
-- Insert vectors with pre-generated embeddings
INSERT INTO s3_vectors.documents_openai (key, data, metadata)
VALUES
(
'1',
'[0.1, 0.2, 0.3, /* ... rest of embedding ... */]'::embd,
'{"title": "How to Train Your AI", "source": "knowledge_base", "created_at": "2025-01-01T00:00:00Z"}'::jsonb
),
(
'2',
'[0.4, 0.5, 0.6, /* ... rest of embedding ... */]'::embd,
'{"title": "Vector Search Best Practices", "source": "knowledge_base", "created_at": "2025-01-01T00:00:00Z"}'::jsonb
),
(
'3',
'[0.7, 0.8, 0.9, /* ... rest of embedding ... */]'::embd,
'{"title": "Building RAG Systems", "source": "knowledge_base", "created_at": "2025-01-01T00:00:00Z"}'::jsonb
);
Updating vectors
JavaScript
const index = bucket.index('documents-openai')
// Update a vector (same key)
const { error } = await index.putVectors({
vectors: [
{
key: 'doc-1',
data: {
float32: [0.15, 0.25, 0.35 /* ... updated embedding ... */],
},
metadata: {
title: 'Getting Started with Vector Buckets - Updated',
updated_at: new Date().toISOString(),
},
},
],
})
if (!error) {
console.log('✓ Vector updated successfully')
}
SQL (via S3 Vector Wrapper)
-- Update a vector (delete and re-insert)
DELETE FROM s3_vectors.documents_openai WHERE key = 'doc-1';
INSERT INTO s3_vectors.documents_openai (key, data, metadata)
VALUES (
'doc-1',
'[0.15, 0.25, 0.35, /* ... updated embedding ... */]'::embd,
'{"title": "Getting Started with Vector Buckets - Updated", "updated_at": "2025-01-01T00:00:00Z"}'::jsonb
);
Deleting vectors
JavaScript
const index = bucket.index('documents-openai')
// Delete specific vectors
const { error } = await index.deleteVectors({
keys: ['doc-1', 'doc-2'],
})
if (!error) {
console.log('✓ Vectors deleted successfully')
}
SQL (via S3 Vector Wrapper)
-- Delete vectors by key
delete from s3_vectors.documents_openai
where key in ('doc-1', 'doc-2');
Metadata best practices
Metadata makes vectors more useful by enabling filtering and context:
const vectors = [
{
key: 'product-001',
data: { float32: [...] },
metadata: {
product_id: 'prod-001',
category: 'electronics',
price: 299.99,
in_stock: true,
tags: ['laptop', 'portable'],
description: 'High-performance ultrabook'
}
},
{
key: 'product-002',
data: { float32: [...] },
metadata: {
product_id: 'prod-002',
category: 'electronics',
price: 99.99,
in_stock: true,
tags: ['headphones', 'wireless'],
description: 'Noise-cancelling wireless headphones'
}
}
]
const { error } = await index.putVectors({ vectors })
Metadata field guidelines
- Keep it lightweight - Metadata is returned with query results, so large values increase response size
- Use consistent types - Store the same field with consistent data types across vectors
- Index key fields - Mark fields you'll filter by to improve query performance
- Avoid nested objects - While supported, flat structures are easier to filter
Batch processing large datasets
For storing large numbers of vectors efficiently:
JavaScript
import { createClient } from '@supabase/supabase-js'
import fs from 'fs'
const supabase = createClient(...)
const index = supabase.storage.vectors
.from('embeddings')
.index('documents-openai')
// Read embeddings from file
const embeddingsFile = fs.readFileSync('embeddings.jsonl', 'utf-8')
const lines = embeddingsFile.split('\n').filter(line => line.trim())
const vectors = lines.map((line, idx) => {
const { key, embedding, metadata } = JSON.parse(line)
return {
key,
data: { float32: embedding },
metadata
}
})
// Process in batches
const BATCH_SIZE = 500
let processed = 0
for (let i = 0; i < vectors.length; i += BATCH_SIZE) {
const batch = vectors.slice(i, i + BATCH_SIZE)
try {
const { error } = await index.putVectors({ vectors: batch })
if (error) throw error
processed += batch.length
console.log(`Progress: ${processed}/${vectors.length}`)
} catch (error) {
console.error(`Batch failed at offset ${i}:`, error)
// Optionally implement retry logic
}
}
console.log('✓ All vectors stored successfully')
Performance optimization
Batch operations
Always use batch operations for better performance:
JavaScript
// ❌ Inefficient - Multiple requests
for (const vector of vectors) {
await index.putVectors({ vectors: [vector] })
}
// ✅ Efficient - Single batch operation
await index.putVectors({ vectors })
Metadata considerations
Keep metadata concise:
// ❌ Large metadata
metadata: {
full_document_text: 'Very long document content...',
detailed_analysis: { /* large object */ }
}
// ✅ Lean metadata
metadata: {
doc_id: 'doc-123',
category: 'news',
summary: 'Brief summary'
}