Skip to content
Storage

Storing Vectors

Insert and update vector embeddings with metadata using the JavaScript SDK or Postgres.

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#

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')
}

Storing vectors from Embeddings API#

Generate embeddings using an LLM API and store them directly:

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)`)
}
}

Updating vectors#

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')
}

Deleting vectors#

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')
}

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:

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:

// ❌ 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'
}

Next steps#