Storing Vectors

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

This feature is in alpha

Expect rapid changes, limited features, and possible breaking updates. Share feedback as we refine the experience and expand access.

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

1
import {  } from '@supabase/supabase-js'
2
3
const  = ('https://your-project-id.supabase.co', 'your-service-key')
4
5
// Get bucket and index
6
const  = ...('embeddings')
7
const  = .('documents-openai')
8
9
// Insert vectors
10
const {  } = await .({
11
  : [
12
    {
13
      : 'doc-1',
14
      : {
15
        : [0.1, 0.2, 0.3 /* ... rest of embedding ... */],
16
      },
17
      : {
18
        : 'Getting Started with Vector Buckets',
19
        : 'documentation',
20
      },
21
    },
22
    {
23
      : 'doc-2',
24
      : {
25
        : [0.4, 0.5, 0.6 /* ... rest of embedding ... */],
26
      },
27
      : {
28
        : 'Advanced Vector Search',
29
        : 'blog',
30
      },
31
    },
32
  ],
33
})
34
35
if () {
36
  .('Error storing vectors:', )
37
} else {
38
  .('✓ Vectors stored successfully')
39
}

1
from supabase import create_client
2
3
supabase = create_client('https://your-project-id.supabase.co', 'your-service-key')
4
5
# Get bucket and index
6
bucket = supabase.storage.vectors().from_('embeddings')
7
index = bucket.index('documents-openai')
8
9
# Insert vectors
10
index.put([
11
    {
12
        'key': 'doc-1',
13
        'data': {'float32': [0.1, 0.2, 0.3]},  # ... rest of embedding
14
        'metadata': {
15
            'title': 'Getting Started with Vector Buckets',
16
            'source': 'documentation',
17
        },
18
    },
19
    {
20
        'key': 'doc-2',
21
        'data': {'float32': [0.4, 0.5, 0.6]},  # ... rest of embedding
22
        'metadata': {
23
            'title': 'Advanced Vector Search',
24
            'source': 'blog',
25
        },
26
    },
27
])
28
29
print('✓ Vectors stored successfully')

1
-- Setup S3 Vector Wrapper (one-time setup)
2
-- https://supabase.com/docs/guides/database/extensions/wrappers/s3_vectors
3
4
-- Insert vectors into the index
5
INSERT INTO s3_vectors.documents_openai (key, data, metadata)
6
VALUES
7
  (
8
    'doc-1',
9
    '[0.1, 0.2, 0.3, /* ... rest of embedding ... */]'::embd,
10
    '{"title": "Getting Started with Vector Buckets", "source": "documentation"}'::jsonb
11
  ),
12
  (
13
    'doc-2',
14
    '[0.4, 0.5, 0.6, /* ... rest of embedding ... */]'::embd,
15
    '{"title": "Advanced Vector Search", "source": "blog"}'::jsonb
16
  );

Storing vectors from Embeddings API

Generate embeddings using an LLM API and store them directly:

1
import { createClient } from '@supabase/supabase-js'
2
import OpenAI from 'openai'
3
4
const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key')
5
6
const openai = new OpenAI({
7
  apiKey: process.env.OPENAI_API_KEY,
8
})
9
10
// Documents to embed and store
11
const documents = [
12
  { id: '1', title: 'How to Train Your AI', content: 'Guide for training models...' },
13
  { id: '2', title: 'Vector Search Best Practices', content: 'Tips for semantic search...' },
14
  {
15
    id: '3',
16
    title: 'Building RAG Systems',
17
    content: 'Implementing retrieval-augmented generation...',
18
  },
19
]
20
21
// Generate embeddings
22
const embeddings = await openai.embeddings.create({
23
  model: 'text-embedding-3-small',
24
  input: documents.map((doc) => doc.content),
25
})
26
27
// Prepare vectors for storage
28
const vectors = documents.map((doc, index) => ({
29
  key: doc.id,
30
  data: {
31
    float32: embeddings.data[index].embedding,
32
  },
33
  metadata: {
34
    title: doc.title,
35
    source: 'knowledge_base',
36
    created_at: new Date().toISOString(),
37
  },
38
}))
39
40
// Store vectors in batches (max 500 per request)
41
const bucket = supabase.storage.vectors.from('embeddings')
42
const vectorIndex = bucket.index('documents-openai')
43
44
for (let i = 0; i < vectors.length; i += 500) {
45
  const batch = vectors.slice(i, i + 500)
46
  const { error } = await vectorIndex.putVectors({ vectors: batch })
47
48
  if (error) {
49
    console.error(`Error storing batch ${i / 500 + 1}:`, error)
50
  } else {
51
    console.log(`✓ Stored batch ${i / 500 + 1} (${batch.length} vectors)`)
52
  }
53
}

1
from supabase import create_client
2
from openai import OpenAI
3
from datetime import datetime
4
5
supabase = create_client('https://your-project-id.supabase.co', 'your-service-key')
6
openai = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
7
8
# Documents to embed and store
9
documents = [
10
    {'id': '1', 'title': 'How to Train Your AI', 'content': 'Guide for training models...'},
11
    {'id': '2', 'title': 'Vector Search Best Practices', 'content': 'Tips for semantic search...'},
12
    {'id': '3', 'title': 'Building RAG Systems', 'content': 'Implementing retrieval-augmented generation...'},
13
]
14
15
# Generate embeddings
16
embeddings_response = openai.embeddings.create(
17
    model='text-embedding-3-small',
18
    input=[doc['content'] for doc in documents]
19
)
20
21
# Prepare vectors for storage
22
vectors = []
23
for doc, embedding_data in zip(documents, embeddings_response.data):
24
    vectors.append({
25
        'key': doc['id'],
26
        'data': {'float32': embedding_data.embedding},
27
        'metadata': {
28
            'title': doc['title'],
29
            'source': 'knowledge_base',
30
            'created_at': datetime.now().isoformat(),
31
        },
32
    })
33
34
# Store vectors in batches (max 500 per request)
35
bucket = supabase.storage.vectors().from_('embeddings')
36
vector_index = bucket.index('documents-openai')
37
38
batch_size = 500
39
for i in range(0, len(vectors), batch_size):
40
    batch = vectors[i:i + batch_size]
41
    vector_index.put(batch)
42
    print(f'✓ Stored batch {i // batch_size + 1} ({len(batch)} vectors)')

1
-- Insert vectors with pre-generated embeddings
2
INSERT INTO s3_vectors.documents_openai (key, data, metadata)
3
VALUES
4
  (
5
    '1',
6
    '[0.1, 0.2, 0.3, /* ... rest of embedding ... */]'::embd,
7
    '{"title": "How to Train Your AI", "source": "knowledge_base", "created_at": "2025-01-01T00:00:00Z"}'::jsonb
8
  ),
9
  (
10
    '2',
11
    '[0.4, 0.5, 0.6, /* ... rest of embedding ... */]'::embd,
12
    '{"title": "Vector Search Best Practices", "source": "knowledge_base", "created_at": "2025-01-01T00:00:00Z"}'::jsonb
13
  ),
14
  (
15
    '3',
16
    '[0.7, 0.8, 0.9, /* ... rest of embedding ... */]'::embd,
17
    '{"title": "Building RAG Systems", "source": "knowledge_base", "created_at": "2025-01-01T00:00:00Z"}'::jsonb
18
  );

Updating vectors

1
const index = bucket.index('documents-openai')
2
3
// Update a vector (same key)
4
const { error } = await index.putVectors({
5
  vectors: [
6
    {
7
      key: 'doc-1',
8
      data: {
9
        float32: [0.15, 0.25, 0.35 /* ... updated embedding ... */],
10
      },
11
      metadata: {
12
        title: 'Getting Started with Vector Buckets - Updated',
13
        updated_at: new Date().toISOString(),
14
      },
15
    },
16
  ],
17
})
18
19
if (!error) {
20
  console.log('✓ Vector updated successfully')
21
}

1
index = bucket.index('documents-openai')
2
3
# Update a vector (same key)
4
index.put([
5
    {
6
        'key': 'doc-1',
7
        'data': {'float32': [0.15, 0.25, 0.35]},  # ... updated embedding
8
        'metadata': {
9
            'title': 'Getting Started with Vector Buckets - Updated',
10
            'updated_at': datetime.now().isoformat(),
11
        },
12
    },
13
])
14
15
print('✓ Vector updated successfully')

1
-- Update a vector (delete and re-insert)
2
DELETE FROM s3_vectors.documents_openai WHERE key = 'doc-1';
3
4
INSERT INTO s3_vectors.documents_openai (key, data, metadata)
5
VALUES (
6
  'doc-1',
7
  '[0.15, 0.25, 0.35, /* ... updated embedding ... */]'::embd,
8
  '{"title": "Getting Started with Vector Buckets - Updated", "updated_at": "2025-01-01T00:00:00Z"}'::jsonb
9
);

Deleting vectors

1
const index = bucket.index('documents-openai')
2
3
// Delete specific vectors
4
const { error } = await index.deleteVectors({
5
  keys: ['doc-1', 'doc-2'],
6
})
7
8
if (!error) {
9
  console.log('✓ Vectors deleted successfully')
10
}

1
index = bucket.index('documents-openai')
2
3
# Delete specific vectors
4
index.delete(['doc-1', 'doc-2'])
5
6
print('✓ Vectors deleted successfully')

1
-- Delete vectors by key
2
delete from s3_vectors.documents_openai
3
where key in ('doc-1', 'doc-2');

Metadata best practices

Metadata makes vectors more useful by enabling filtering and context:

1
const vectors = [
2
  {
3
    key: 'product-001',
4
    data: { float32: [...] },
5
    metadata: {
6
      product_id: 'prod-001',
7
      category: 'electronics',
8
      price: 299.99,
9
      in_stock: true,
10
      tags: ['laptop', 'portable'],
11
      description: 'High-performance ultrabook'
12
    }
13
  },
14
  {
15
    key: 'product-002',
16
    data: { float32: [...] },
17
    metadata: {
18
      product_id: 'prod-002',
19
      category: 'electronics',
20
      price: 99.99,
21
      in_stock: true,
22
      tags: ['headphones', 'wireless'],
23
      description: 'Noise-cancelling wireless headphones'
24
    }
25
  }
26
]
27
28
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:

1
import { createClient } from '@supabase/supabase-js'
2
import fs from 'fs'
3
4
const supabase = createClient(...)
5
const index = supabase.storage.vectors
6
  .from('embeddings')
7
  .index('documents-openai')
8
9
// Read embeddings from file
10
const embeddingsFile = fs.readFileSync('embeddings.jsonl', 'utf-8')
11
const lines = embeddingsFile.split('\n').filter(line => line.trim())
12
13
const vectors = lines.map((line, idx) => {
14
  const { key, embedding, metadata } = JSON.parse(line)
15
  return {
16
    key,
17
    data: { float32: embedding },
18
    metadata
19
  }
20
})
21
22
// Process in batches
23
const BATCH_SIZE = 500
24
let processed = 0
25
26
for (let i = 0; i < vectors.length; i += BATCH_SIZE) {
27
  const batch = vectors.slice(i, i + BATCH_SIZE)
28
29
  try {
30
    const { error } = await index.putVectors({ vectors: batch })
31
32
    if (error) throw error
33
34
    processed += batch.length
35
    console.log(`Progress: ${processed}/${vectors.length}`)
36
  } catch (error) {
37
    console.error(`Batch failed at offset ${i}:`, error)
38
    // Optionally implement retry logic
39
  }
40
}
41
42
console.log('✓ All vectors stored successfully')

1
from supabase import create_client
2
import json
3
4
supabase = create_client(...)
5
index = supabase.storage.vectors().from_('embeddings').index('documents-openai')
6
7
# Read embeddings from file
8
with open('embeddings.jsonl', 'r') as f:
9
    lines = [line.strip() for line in f if line.strip()]
10
11
vectors = []
12
for line in lines:
13
    data = json.loads(line)
14
    vectors.append({
15
        'key': data['key'],
16
        'data': {'float32': data['embedding']},
17
        'metadata': data.get('metadata', {})
18
    })
19
20
# Process in batches
21
BATCH_SIZE = 500
22
processed = 0
23
24
for i in range(0, len(vectors), BATCH_SIZE):
25
    batch = vectors[i:i + BATCH_SIZE]
26
27
    try:
28
        index.put(batch)
29
        processed += len(batch)
30
        print(f'Progress: {processed}/{len(vectors)}')
31
    except Exception as e:
32
        print(f'Batch failed at offset {i}: {e}')
33
        # Optionally implement retry logic
34
35
print('✓ All vectors stored successfully')

Performance optimization

Batch operations

Always use batch operations for better performance:

1
// ❌ Inefficient - Multiple requests
2
for (const vector of vectors) {
3
  await index.putVectors({ vectors: [vector] })
4
}
5
6
// ✅ Efficient - Single batch operation
7
await index.putVectors({ vectors })

1
# ❌ Inefficient - Multiple requests
2
for vector in vectors:
3
    index.put([vector])
4
5
# ✅ Efficient - Single batch operation
6
index.put(vectors)

Metadata considerations

Keep metadata concise:

1
// ❌ Large metadata
2
metadata: {
3
  full_document_text: 'Very long document content...',
4
  detailed_analysis: { /* large object */ }
5
}
6
7
// ✅ Lean metadata
8
metadata: {
9
  doc_id: 'doc-123',
10
  category: 'news',
11
  summary: 'Brief summary'
12
}