Guide

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

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

Next steps