Storage

Working with Vector Indexes

Create, manage, and optimize vector indexes for efficient similarity search.

Vector indexes organize embeddings within a bucket with consistent dimensions and distance metrics. Each index defines how similarity searches are performed across your vectors.

Understanding vector indexes

An index specifies:

  • Index Name - Unique identifier within the bucket
  • Dimension - Size of vector embeddings (e.g., 1536 for OpenAI)
  • Distance Metric - Similarity calculation method (cosine, euclidean, or L2)
  • Data Type - Vector format (currently float32)

Think of an index as a table in a traditional database. It has a schema (dimension) and a query strategy (distance metric).

Creating indexes

Via Dashboard

  1. Open your vector bucket in the Supabase Dashboard.
  2. Click Create Index.
  3. Enter an index name (e.g., documents-openai).
  4. Set the dimension matching your embeddings (e.g., 1536 for OpenAI's text-embedding-3-small).
  5. Select the distance metric (cosine, euclidean, or l2).
  6. Click Create.

Via SDK

1
import {  } from '@supabase/supabase-js'
2
3
const  = ('https://your-project.supabase.co', 'your-service-key')
4
5
const  = ...('embeddings')
6
7
// Create an index
8
const { ,  } = await .({
9
  : 'documents-openai',
10
  : 'float32',
11
  : 1536,
12
  : 'cosine',
13
})
14
15
if () {
16
  .('Error creating index:', )
17
} else {
18
  .('Index created:', )
19
}

Choosing the right metric

Most modern embedding models work best with cosine distance:

  • OpenAI (text-embedding-3-small, text-embedding-3-large): Cosine
  • Cohere (embed-english-v3.0): Cosine
  • Hugging Face (sentence-transformers): Cosine
  • Google (text-embedding-004): Cosine
  • Llama 2 embeddings: Cosine or L2

Tip: Check your embedding model's documentation for the recommended distance metric.

Important: Creating an index with incorrect dimensions will cause insert and query operations to fail.

Managing multiple indexes

Create multiple indexes for different use cases or embedding models:

1
const bucket = supabase.storage.vectors.from('embeddings')
2
3
// Index for OpenAI embeddings
4
await bucket.createIndex({
5
  indexName: 'documents-openai',
6
  dimension: 1536,
7
  distanceMetric: 'cosine',
8
  dataType: 'float32',
9
})
10
11
// Index for Cohere embeddings
12
await bucket.createIndex({
13
  indexName: 'documents-cohere',
14
  dimension: 1024,
15
  distanceMetric: 'cosine',
16
  dataType: 'float32',
17
})
18
19
// Index for different use case
20
await bucket.createIndex({
21
  indexName: 'images-openai',
22
  dimension: 1536,
23
  distanceMetric: 'cosine',
24
  dataType: 'float32',
25
})
26
27
// List all indexes
28
const { data: indexes } = await bucket.listIndexes()
29
console.log('All indexes:', indexes)

Use cases for multiple indexes

  • Different embedding models - Store vectors from OpenAI, Cohere, and local models separately
  • Different domains - Maintain separate indexes for documents, images, products, etc.
  • A/B testing - Compare different embedding models side-by-side
  • Multi-language - Keep language-specific embeddings separate

Listing and inspecting indexes

List all indexes in a bucket

1
const bucket = supabase.storage.vectors.from('embeddings')
2
3
const { data: indexes, error } = await bucket.listIndexes()
4
5
if (!error) {
6
  indexes?.forEach((index) => {
7
    console.log(`Index: ${index.name}`)
8
    console.log(`  Dimension: ${index.dimension}`)
9
    console.log(`  Distance: ${index.distanceMetric}`)
10
  })
11
}

Get index details

1
const { data: indexDetails, error } = await bucket.getIndex('documents-openai')
2
3
if (!error && indexDetails) {
4
  console.log(`Index: ${indexDetails.name}`)
5
  console.log(`Created at: ${indexDetails.createdAt}`)
6
  console.log(`Dimension: ${indexDetails.dimension}`)
7
  console.log(`Distance metric: ${indexDetails.distanceMetric}`)
8
}

Deleting indexes

Delete an index to free storage space:

1
const bucket = supabase.storage.vectors.from('embeddings')
2
3
const { error } = await bucket.deleteIndex('documents-openai')
4
5
if (error) {
6
  console.error('Error deleting index:', error)
7
} else {
8
  console.log('Index deleted successfully')
9
}

Before deleting an index

Warning: Deleting an index is permanent and cannot be undone.

  • Backup important data - Export vectors before deletion if needed
  • Update applications - Ensure no code references the deleted index
  • Check dependencies - Verify no active queries use the index
  • Plan the deletion - Do this during low-traffic periods

Immutable properties

Once created, these properties cannot be changed:

  • Dimension - Must create new index with different dimension
  • Distance metric - Cannot change after creation
  • Data type - Currently only float32 supported

Optimizing index performance

1
// Good - Appropriate batch size
2
const batch = vectors.slice(0, 250)
3
await index.putVectors({ vectors: batch })
4
5
// Good - Filter metadata before query
6
const { data } = await index.queryVectors({
7
  queryVector,
8
  topK: 5,
9
  filter: { category: 'electronics' },
10
})
11
12
// Avoid - Single vector inserts
13
for (const vector of vectors) {
14
  await index.putVectors({ vectors: [vector] })
15
}
16
17
// Avoid - Returning unnecessary data
18
const { data } = await index.queryVectors({
19
  queryVector,
20
  topK: 1000, // Too many results
21
  returnData: true, // Include large embeddings
22
})

Next steps